- ←Prev
- AST
A Library for Handling
World Coordinate Systems
in Astronomy - Next→
- TOC ↑
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:
-
For some classes of Frame, whose coordinate values are not constrained, this function will never modify
the values supplied. However, for Frames whose axes represent cyclic quantities (such as angles or
positions on the sky), coordinates will typically be wrapped into an appropriate standard range, such as
zero to 2∗pi
or -pi to +pi
(depending on the normalisation method used).
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
INTEGER∗8.
The function name is changed by appending the digit "
8"
to the name. Thus, AST_NORMPOINTS
becomes AST_NORMPOINTS8.
Copyright (C) 2021 East Asian Observatory
- ←Prev
- AST
A Library for Handling
World Coordinate
Systems
in Astronomy - Next→
- TOC ↑