astAddFrameastAddFrame - Add a Frame to a FrameSet to define a new coordinate system

Description:
This function adds a new FrameFrame and an associated MappingMapping to a FrameSetFrameSet so as to define a new coordinate system, derived from one which already exists within the FrameSet. The new Frame then becomes the FrameSet's current Frame.

This function may also be used to merge two FrameSets, or to append extra axes to every Frame in a FrameSet.

Synopsis:
void astAddFrame( AstFrameSet $*$this, int iframe, AstMapping $*$map, AstFrame $*$frame )
Parameters:
this
Pointer to the FrameSet.
iframe
The index of the Frame within the FrameSet which describes the coordinate system upon which the new one is to be based. This value should lie in the range from 1 to the number of Frames already in the FrameSet (as given by its NframeNframe attribute). As a special case, AST__ALLFRAMES may be supplied, in which case the axes defined by the supplied Frame are appended to every Frame in the FrameSet (see the Notes section for details).
map
Pointer to a Mapping which describes how to convert coordinates from the old coordinate system (described by the Frame with index "iframe") into coordinates in the new system. The Mapping's forward transformation should perform this conversion, and its inverse transformation should convert in the opposite direction. The supplied Mapping is ignored if parameter "iframe"is equal to AST__ALLFRAMES.
frame
Pointer to a Frame that describes the new coordinate system. Any class of Frame may be supplied (including Regions and FrameSets).

This function may also be used to merge two FrameSets by supplying a pointer to a second FrameSet for this parameter (see the Notes section for details).

Notes:
  • A value of AST__BASE or AST__CURRENT may be given for the "iframe" parameter to specify the base Frame or the current Frame respectively.

  • This function sets the value of the CurrentCurrent attribute for the FrameSet so that the new Frame subsequently becomes the current Frame.

  • The number of input coordinate values accepted by the supplied Mapping (its NinNin attribute) must match the number of axes in the Frame identified by the "iframe" parameter. Similarly, the number of output coordinate values generated by this Mapping (its NoutNout attribute) must match the number of axes in the new Frame.

  • As a special case, if a pointer to a FrameSet is given for the "frame" parameter, this is treated as a request to merge a pair of FrameSets. This is done by appending all the new Frames (in the "frame" FrameSet) to the original FrameSet, while preserving their order and retaining all the inter-relationships (i.e. Mappings) between them. The two sets of Frames are inter-related within the merged FrameSet by using the Mapping supplied. This should convert between the Frame identified by the "iframe" parameter (in the original FrameSet) and the current Frame of the "frame" FrameSet. This latter Frame becomes the current Frame in the merged FrameSet.

  • As another special case, if a value of AST__ALLFRAMES is supplied for parameter "iframe", then the supplied Mapping is ignored, and the axes defined by the supplied Frame are appended to each Frame in the FrameSet. In detail, each Frame in the FrameSet is replaced by a CmpFrameCmpFrame containing the original Frame and the Frame specified by parameter "frame". In addition, each Mapping in the FrameSet is replaced by a CmpMapCmpMap containing the original Mapping and a UnitMapUnitMap in parallel. The Nin and Nout attributes of the UnitMap are set equal to the number of axes in the supplied Frame. Each new CmpMap is simplified using astSimplifyastSimplify before being stored in the FrameSet.