Add a Frame to a FrameSet to define a new coordinate system astAddFrame
’
s current
Frame.
This function may also be used to merge two FrameSets, or to append extra axes to every Frame in a FrameSet.
"
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. 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).
Deep copies of the supplied "
mapping"
and "
frame"
objects are stored within the
modified FrameSet. So any changes made to the FrameSet after calling this method will
have no effect on the supplied Mapping and Frame objects.
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 Current 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
Nin 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 Nout 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 CmpFrame containing the original Frame and the Frame specified by
parameter "
frame"
. In addition, each Mapping in the FrameSet is replaced by a CmpMap
containing the original Mapping and a UnitMap 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 astSimplify before being stored in the FrameSet.