astNormPoints

Normalise a collection of points

Description:

This function 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 function astNorm 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.

Synopsis

void astNormPoints( AstFrame this, int npoint, int ncoord_in, int indim, const double in, int contig, int ncoord_out, int outdim, double out )

Parameters:

this
Pointer to the Frame.
npoint
The number of points to be normalised.
ncoord_in
The number of coordinates being supplied for each input point. This should be the same as the number of axes in the Frame.
indim
The number of elements along the second 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
The address of the first element in a 2-dimensional array of shape " [ncoord_in][indim]" , 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[coord][point]" .
contig
Indicates the way in which the normalised axis values are to be calculated. A non-zero value 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). A zero value causes each point to be normalised independently using astNorm.
ncoord_out
The number of coordinates being supplied for each output point. This should be the same as the number of axes in the Frame.
outdim
The number of elements along the second 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
The address of the first element in a 2-dimensional array of shape " [ncoord_out][outdim]" , 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[coord][point]" .

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 " int" to type " int64_t" (defined in header file stdint.h). The function name is changed by appending the digit " 8" to the name. Thus, astNormPoints becomes astNormPoints8