- ←Prev
- AST
A Library for Handling
World Coordinate Systems
in Astronomy - Next→
- TOC ↑
Description:
This function creates a new
Frame whose axes are copied from
an existing Frame along with other Frame attributes, such as its
Title. Any
number (zero or more) of the original Frame
’
s axes may be copied, in any order,
and additional axes with default attributes may also be included in the new
Frame.
Optionally, a Mapping that converts between the coordinate systems
described by the two Frames will also be returned.
Synopsis
AstFrame
astPickAxes(
AstFrame this,
int naxes, const int axes[], AstMapping
map
)
Parameters:
this
Pointer to the original Frame.
naxes
The number of axes
required in the new Frame.
axes
An array, with "
naxes"
elements, which lists the
axes to be copied. These should be given in the order required in the new Frame,
using the axis numbering in the original Frame (which starts at 1 for the first
axis). Axes may be selected in any order, but each may only be used once. If
additional (default) axes are also to be included, the corresponding elements
of this array should be set to zero.
map
Address of a location in which
to return a pointer to a new Mapping. This will be a
PermMap (or a
UnitMap
as a special case) that describes the axis permutation that has taken place
between the original and new Frames. The Mapping
’
s forward transformation
will convert coordinates from the original Frame into the new one, and vice
versa.
If this Mapping is not required, a NULL value may be supplied for this parameter.
Applicability
Frame
This function applies to all Frames. The class of Frame
returned may differ from that of the original Frame, depending on which axes are
selected. For example, if a single axis is picked from a
SkyFrame (which must
always have two axes) then the resulting Frame cannot be a valid SkyFrame,
so will revert to the parent class (Frame) instead.
Using this
function on a FrameSet is identical to using it on the current Frame in the
FrameSet. The returned Frame will not be a FrameSet.
If this function
is used on a Region, an attempt is made to retain the bounds information on
the selected axes. If succesful, the returned Frame will be a Region of some
class. Otherwise, the returned Frame is obtained by calling this function on
the Frame represented by the supplied Region (the returned Frame will then
not be a Region). In order to be succesful, the selected axes in the Region
must be independent of the others. For instance, a
Box can be split in this
way but a
Circle cannot. Another requirement for success is that no default
axes are added (that is, the
"
axes
"
array must not contain any zero values.
Returned Value
astPickAxes()
A pointer to the new Frame.
Notes:
-
The new Frame will contain a "
deep"
copy (c.f. astCopy) of all the data selected from
the original Frame. Modifying any aspect of the new Frame will therefore not affect the
original one.
-
A null Object pointer (AST__NULL) will be returned if this function is invoked with the
AST error status set, or if it should fail for any reason.
Copyright (C) 2021 East Asian Observatory
- ←Prev
- AST
A Library for Handling
World
Coordinate Systems
in Astronomy - Next→
- TOC ↑