Next: astPrism - Create a Prism
Up: AST Function Descriptions
Previous: astPolyTran - Fit a PolyMap inverse or forward transformation

## astPolygon - Create a Polygon

Description:
This function creates a new Polygon object and optionally initialises its attributes.

The Polygon class implements a polygonal area, defined by a collection of vertices, within a 2-dimensional Frame. The vertices are connected together by geodesic curves within the encapsulated Frame. For instance, if the encapsulated Frame is a simple Frame then the geodesics will be straight lines, but if the Frame is a SkyFrame then the geodesics will be great circles. Note, the vertices must be supplied in an order such that the inside of the polygon is to the left of the boundary as the vertices are traversed. Supplying them in the reverse order will effectively negate the polygon.

Within a SkyFrame, neighbouring vertices are always joined using the shortest path. Thus if an edge of 180 degrees or more in length is required, it should be split into section each of which is less than 180 degrees. The closed path joining all the vertices in order will divide the celestial sphere into two disjoint regions. The inside of the polygon is the region which is circled in an anti-clockwise manner (when viewed from the inside of the celestial sphere) when moving through the list of vertices in the order in which they were supplied when the Polygon was created (i.e. the inside is to the left of the boundary when moving through the vertices in the order supplied).

Synopsis:
AstPolygon astPolygon( AstFrame frame, int npnt, int dim, const double points, AstRegion unc, const char options, ... )
Parameters:
frame
A pointer to the Frame in which the region is defined. It must have exactly 2 axes. A deep copy is taken of the supplied Frame. This means that any subsequent changes made to the Frame using the supplied pointer will have no effect the Region.
npnt
The number of points in the Region.
dim
The number of elements along the second dimension of the "points" array (which contains the point coordinates). This value is required so that the coordinate values can be correctly located if they do not entirely fill this array. The value given should not be less than "npnt".
points
The address of the first element of a 2-dimensional array of shape "[2][dim]" giving the physical coordinates of the vertices. These should be stored such that the value of coordinate number "coord" for point number "pnt" is found in element "in[coord][pnt]".
unc
An optional pointer to an existing Region which specifies the uncertainties associated with the boundary of the Box being created. The uncertainty in any point on the boundary of the Box is found by shifting the supplied "uncertainty" Region so that it is centred at the boundary point being considered. The area covered by the shifted uncertainty Region then represents the uncertainty in the boundary position. The uncertainty is assumed to be the same for all points.

If supplied, the uncertainty Region must be of a class for which all instances are centro-symetric (e.g. Box, Circle, Ellipse, etc.) or be a Prism containing centro-symetric component Regions. A deep copy of the supplied Region will be taken, so subsequent changes to the uncertainty Region using the supplied pointer will have no effect on the created Box. Alternatively, a NULL Object pointer may be supplied, in which case a default uncertainty is used equivalent to a box 1.0E-6 of the size of the Box being created.

The uncertainty Region has two uses: 1) when the astOverlap function compares two Regions for equality the uncertainty Region is used to determine the tolerance on the comparison, and 2) when a Region is mapped into a different coordinate system and subsequently simplified (using astSimplify), the uncertainties are used to determine if the transformed boundary can be accurately represented by a specific shape of Region.

options
Pointer to a null-terminated string containing an optional comma-separated list of attribute assignments to be used for initialising the new Polygon. The syntax used is identical to that for the astSet function and may include "printf" format specifiers identified by "%" symbols in the normal way.
...
If the "options" string contains "%" format specifiers, then an optional list of additional arguments may follow it in order to supply values to be substituted for these specifiers. The rules for supplying these are identical to those for the astSet function (and for the C "printf" function).
Returned Value:
astPolygon()
A pointer to the new Polygon.
Notes:
• A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.
Status Handling
The protected interface to this function includes an extra parameter at the end of the parameter list descirbed above. This parameter is a pointer to the integer inherited status variable: "int status".

Next: astPrism - Create a Prism
Up: AST Function Descriptions
Previous: astPolyTran - Fit a PolyMap inverse or forward transformation

AST A Library for Handling World Coordinate Systems in Astronomy