-  ←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 ↑