next up previous
Next: astPlot - Create a Plot
Up: AST Function Descriptions
Previous: astPermMap - Create a PermMap

   
astPickAxes - Create a new Frame by picking axes from an existing one

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.

Returned Value:
astPickAxes()
A pointer to the new Frame.

Notes:
  • 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.
  • 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.



next up previous
Next: astPlot - Create a Plot
Up: AST Function Descriptions
Previous: astPermMap - Create a PermMap

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
R.F. Warren-Smith & D.S. Berry
30th April 2003
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2003 Central Laboratory of the Research Councils