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.

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.
FrameSet
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.
Region
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

AST_PICKAXES = INTEGER
A pointer to the new Frame.

Notes:

Copyright (C) 2021 East Asian Observatory