- ←Prev
- AST
A Library for Handling
World Coordinate Systems
in Astronomy - Next→
- TOC ↑
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:
-
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
2pi 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 "
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
Copyright (C) 2021 East Asian Observatory
- ←Prev
- AST
A Library for Handling
World
Coordinate Systems
in Astronomy - Next→
- TOC ↑