AST_NORMPOINTS

Normalise a collection of points

Description:

This routine normalises the axis values representing a collection of points within a Frame. The normalisation can be done in two ways - 1) to put the axis values into the range expected for display to human readers or 2) to put the axis values into which ever range avoids discontinuities within the collection of positions. Using method 1) is the same as using routine AST_NORM on each point in the collection. Using method 2) is useful when handling collections of points that may span some discontinuity in the coordinate system.

Invocation

CALL AST_NORMPOINTS( THIS, NPOINT, NCOORD_IN, INDIM, IN, CONTIG, NCOORD_OUT, OUTDIM, OUT, STATUS )

Arguments

THIS = INTEGER (Given)
Pointer to the Frame.
NPOINT = INTEGER (Given)
The number of points to be normalised.
NCOORD_IN = INTEGER (Given)
The number of coordinates being supplied for each input point. This should be the same as the number of axes in the Frame.
INDIM = INTEGER (Given)
The number of elements along the first dimension of the IN array (which contains the input 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 NPOINT.
IN( INDIM, NCOORD_IN ) = DOUBLE PRECISION (Given)
An array containing the coordinates of the input (unnormalised) points. These should be stored such that the value of coordinate number COORD for input point number POINT is found in element IN(POINT,COORD).
CONTIG = LOGICAL (Given)
Indicates the way in which the normalised axis values are to be calculated. .TRUE. causes the values to be normalised in such a way as to reduce the effects of any discontinuities in the coordinate system. For instance, points in a SkyFrame that span longitude zero will be normalized into a longitude range of -pi to +pi (otherwise they will be normalized into a range of 0 to 2.pi). .FALSE. causes each point to be normalised independently using AST_NORM.
NCOORD_OUT = INTEGER (Given)
The number of coordinates being supplied for each output point. This should be the same as the number of axes in the Frame.
OUTDIM = INTEGER (Given)
The number of elements along the first dimension of the OUT array (which will contain the output coordinates). This value is required so that the coordinate values can be correctly located if they will not entirely fill this array. The value given should not be less than NPOINT.
OUT( OUTDIM, NCOORD_OUT ) = DOUBLE PRECISION (Returned)
An array into which the coordinates of the output (normalised) points will be written. These will be stored such that the value of coordinate number COORD for output point number POINT will be found in element OUT(POINT,COORD).
STATUS = INTEGER (Given and Returned)
The global status.

Notes:

Handling of Huge Pixel Arrays

If the number of points to be normalised exceeds the largest value that can be represented by a 4-byte integer, then the alternative " 8-byte" interface for this function should be used. This alternative interface uses 8 byte integer arguments (instead of 4-byte). Specifically, the arguments NPOINT, INDIM and OUTDIM are changed from type INTEGER to type INTEGER8. The function name is changed by appending the digit " 8" to the name. Thus, AST_NORMPOINTS becomes AST_NORMPOINTS8.