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

##### 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

##### 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