This function creates a new
PointList object
and optionally initialises its attributes.
A PointList object is a specialised type of Region which represents a collection of points in a
coordinate Frame.
RESULT = AST_POINTLIST( FRAME, NPNT, COORD, DIM, POINTS,
UNC, OPTIONS, STATUS )
FRAME = INTEGER (Given)
A pointer to the Frame in
which the region is defined. 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 = INTEGER (Given)
The number of points in the Region.
NCOORD = INTEGER (Given)
The number of coordinates being supplied for each point. This must equal the number of
axes in the supplied Frame, given by its
Naxes attribute.
DIM = INTEGER (Given)
The
number of elements along the first 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( DIM, NCOORD ) = DOUBLE PRECISION (Given)
A 2-dimensional array giving the
physical coordinates of the points. These should be stored such that the value of coordinate
number COORD for point number PNT is found in element IN(PNT,COORD).
UNC =
INTEGER (Given)
An optional pointer to an existing Region which specifies the uncertainties
associated with each point in the PointList being created. The uncertainty at any point in
the PointList is found by shifting the supplied
"
uncertainty
"
Region so that it is centred
at the point being considered. The area covered by the shifted uncertainty Region then
represents the uncertainty in the 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 (AST__NULL) may be supplied, in which case a default uncertainty
is used equivalent to a box 1.0E-6 of the size of the bounding box of the PointList being
created.
The uncertainty Region has two uses: 1) when the AST_OVERLAP 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
AST_SIMPLIFY), the uncertainties are used to determine if the transformed boundary
can be accurately represented by a specific shape of Region.
OPTIONS = CHARACTER
∗ (
∗ )
(Given)
A character string containing an optional comma-separated list of attribute assignments
to be used for initialising the new PointList. The syntax used is identical to that for the
AST_SET routine.
STATUS = INTEGER (Given and Returned)
The global status.
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"
.