Polygons

The polygon commands include: Data_Clip_Polygon, Polygon File, Polygon Border, Polygon Cull, Polygon Draw, Polygon List, Polygon Area, Polygon Intersect, Polygon Shade Contours, and Inside.

Polygons

ACON supports the display and manipulation of polygons, including the handling of polygon holes (as of version 9.0) [using code from the Generic Polygon Clipper by Alan Murta amurta@cs.man.ac.uk, Advanced Interfaces Group, University of Manchester].

The commands in this section accept n x 2 or n x 3 numeric matrices containing the x,y coordinates of the polygons. More than one polygon may be contained in a polygon definition.

There are 3 ways to define multiple polygons in the polygon matrix.

- add a separating row between polygons in the matrix with x,y values greater than or equal to 1.0E35 (or the characters "NAN")

- close the polygon by adding a row with the same x,y values as the starting coordinate of the polygon

- add an optional 3rd column which defines the polygon ID number to which the x,y coordinates belong.

Adding a 3rd column provides the most flexibility, in that polygons which represent holes in the polygon structure may be defined. Each polygon is given an arbitrary ID number. Polygon holes are given negative polygon IDs. For example, this polygon contains 2 sub-polygons, and 1 hole-polygon.

pol5
 3.5 3.5 -1
 2.5 3.5 -1
 2.5 2.5 -1
 3.5 2.5 -1
 4.0 2.0  1
 2.1 2.0  1
 2.1 4.0  1
 4.0 4.0  1
 4.0 0.3  2
 2.1 0.3  2
 2.1 1.0  2
 4.0 1.0  2

Data Clip Polygon

This command is used to clip the data so that any data points outside the polygon border are removed from memory. The data must already be in memory, and a valid polygon must exist in memory before this command will execute.

There are 2 or more parameters:

polygon matrix - the x,y matrix to use as the clipping polygon. See the note on the structure of Polygons .

xyz matrix - a matrix containing the x, y, and z data as 3 columns.

or

x, y, and z vectors- 3 vectors containing the data to be plotted.

Data_Clip_Polygon(polygon matrix,<xyz matrix>);

Polygon File

This command is used to read a polygon (text) file containing polygon x,y coordinates. The name of the polygon file is specified. The file is read into memory, after which the polygon is then available.

The simplest format for the polygon file is:
<x value> <y value>
e.g.
-67.234 44.567
-67.232 44.654

The coordinates may be comma, blank, or tab separated. See the note on the structure of Polygons .

There is parameter:

file name - the name of the polygon file to read.

matrix = Polygon_File(,"filename");

Polygon Border

This command is used to create a polygon from the data border of data currently in memory. The name of the polygon, and the data vectors are specified. The data border is calculated and stored as a polygon in memory. See the note on the structure of Polygons

There are 2 or more parameters:

polygon matrix name - the name of the polygon to create.

xyz matrix - a matrix containing the x, y, and z data as 3 columns.

OR

x, y, and z vectors- 3 vectors containing the data to be plotted.

Polygon_Border("polygon matrix name",<data matrix>);

Polygon Cull

This command is used to cull a polygon to reduce its complexity. The polygon is represented by a matrix of x,y data. The user can use this command to reduce the number of points in this matrix, which reduces the complexity of the polygon.

There are 5 parameters:

tolerance distance - the maximum distance ( in NDC units) a coordinate point may lie from the resultant smoothed line and still be removed.

angle - the minimum angle (_) formed between 3 points which will force a data point to be included in the smoothed line.

wedges - the number of wedges along the smoothed line used to track the created smoothed line.

area/perimeter tolerance - ratio of area/perimeter used to remove polygons which are insignificant. insignificant polygons are considered to be those with higher area/perimeter ratios.

matrix - it represents the matrix to cull.

matrix = Polygon_Cull(tolerance distance,angle,# of wedges [, area/perimeter tolerance],matrix_to_cull);

Polygon Draw

This command is used to draw a previously created polygon on the current output device. The matrix containing the x,y data is specified. A line segment joining the last and 1st coordinates will be drawn, if they are not coincident.

When drawing a filled polygon to a MIF_Output() file, one or more attributes may be included which will be associated with the polygon. The optional attributes must match the attribute names supplied as part of the Graph_Layer() command.

There are 1 or more parameters:

polygon matrix - the matrix containing the x,y coordinates of the polygon to draw. See the note on the structure of Polygons .

attribute value(s) - the optional attribute value to be included with this polygon when a filled polygon is drawn to a MIF_Output() file. Attribute values may be either a character string or numeric value.

Polygon_Draw(polygon matrix);

Polygon List

This command is used to list the coordinates of a previously created polygon to the text window (or output file). The matrix containing the xy coordinates of the polygon to list is specified. The normal matrix manipulation routines may also be used to list a polygon. See the note on the structure of Polygons .

There is 1 parameter:

polygon matrix - the polygon to list.

Polygon_List(polygon matrix);

Polygon Area

This command is used to calculate the area of a polygon. The matrix containing the x,y coordinates of the polygon is specified. If the current projection is not a NIL projection, the coordinates are converted to km. See the note on the structure of Polygons .

There is 1 parameter:

polygon matrix - the matrix of x,y coordinates of the polygon for which the area is to be computed.

area = Polygon_Area(polygon matrix);

Polygon Intersect

This command is used to create a new polygon from the intersection of 2 previously existing polygons. The 2 existing polygons specified. See the note on the structure of Polygons .

The result is a new (polygon) matrix containing 3 columns.

This command now uses code from the Generic Polygon Clipper by Alan Murta amurta@cs.man.ac.uk, Advanced Interfaces Group, University of Manchester.

There are 2 or more parameter:s

polygon matrix1 - the 1st input polygon.

polygon matrix2 - the 2nd input polygon.

operand - a flag indicating the operation to perform.

0 - intersect,

1 - subtract,

2 - exclusive OR,

3 - union.

result -> polygon number3 - the resultant polygon is returned on the stack.

<new matrix> = Polygon Intersect(polygon 1,polygon 2[,operand]);

Polygon Shade Contours

This command is used to shade the data surface within a polygon boundary. The polygon within which the contouring should be restricted is specified.

There are 2 or more parameter:s

polygon matrix - the polygon within which the data is contoured..

data matrix - the n x 3 matrix of x,y,z data to be contoured.

OR

x vector, y vector, z vector - 3 vectors of x,y,z data to be contoured. See the note on the structure of Polygons .

Polygon_Shade_Contours(polygon);

Inside

This command returns a boolean vector indicating which of the reference points supplied are found inside a polygon (and conversely which are outside as well).

There are 3 parameter:s

polygon matrix - an n x 2 (or n x 3) matrix defining the x,y coordinates of a polygon. See the note on the structure of Polygons .

data matrix- the matrix containing the x,y points to be tested to check if they are inside or outside the polygon.

or

2 vectors - the x and y vectors to be tested to check if they are inside the polygon.

boundary flag- optional flag, if 1, any points falling exactly on the polygon boundary will be considered inside. Default is 0.

boolean vector = Inside(polygon,data matrix [, boundary flag]);