next up previous
Next: AST_PLOT - Create a Plot
Up: AST Routine Descriptions
Previous: AST_PERMMAP - Create a PermMap

   
AST_PICKAXES - 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.

A Mapping that converts between the coordinate systems described by the two Frames will also be returned.

Invocation:
RESULT = AST_PICKAXES( THIS, NAXES, AXES, MAP, STATUS )

Arguments:
THIS = INTEGER (Given)
Pointer to the original Frame.
NAXES = INTEGER (Given)
The number of axes required in the new Frame.
AXES( NAXES ) = INTEGER (Given)
An array 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 = INTEGER (Returned)
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.
STATUS = INTEGER (Given and Returned)
The global status.

Returned Value:
AST_PICKAXES = INTEGER
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. AST_COPY) 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 STATUS set to an error value, or if it should fail for any reason.



next up previous
Next: AST_PLOT - Create a Plot
Up: AST Routine Descriptions
Previous: AST_PERMMAP - Create a PermMap

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
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