We can now add further Frames to the FrameSet created above
(). To do so, we must supply a new Frame
and an associated Mapping that relates it to any of the Frames that
are already present (there is only one present so far). To keep the
example simple, we will just use a ZoomMap that multiplies coordinates
by 10. The required Objects are created as follows:
AstFrame *frame2; AstMapping *mapping12; ... frame2 = astFrame( 2, "Domain=B" ); mapping12 = astZoomMap( 2, 10.0, "" );
To add the new Frame into our FrameSet, we use the astAddFrame function:
astAddFrame( frameset, 1, mapping12, frame2 );
Whenever a Frame is added to a FrameSet, it is assigned an integer
index. This index starts with 1 for the initial Frame used to create
the FrameSet () and increments by one
every time a new Frame is added. This index is the primary way of
identifying the Frames within a FrameSet.
When a Frame is added, we also have to specify which of the existing ones the new Frame is related to. Here, we chose number 1, the only one present so far, and the new one we added became number 2.
Note that a FrameSet does not make copies of the Frames and Mappings
that you insert into it. Instead, it holds pointers to them. This
means that if you retain the original pointers to these Objects and
alter them, you will indirectly be altering the FrameSet's
contents. You can, of course, always use astCopy
() to make a separate copy of any Object if
you need to ensure its independence.
We could also add a third Frame into our FrameSet, this time defining a coordinate system which is reached by multiplying the original coordinates (of ``frame1'') by 5:
astAddFrame( frameset, 1, astZoomMap( 2, 5.0, "" ), astFrame( 2, "Domain=C" ) );
Here, we have avoided storing unnecessary pointer values by using
function invocations directly as arguments for astAddFrame. This
assumes that we are using astBegin and astEnd () to
ensure that Objects are correctly deleted when no longer required.
Our example FrameSet now contains three Frames and two Mappings with the arrangement shown in the Figure below. The total number of Frames is given by its read-only Nframe attribute.
Figure: An example FrameSet, in which Frames 2 and 3 are related to Frame 1 by multiplying its coordinates by factors of 10 and 5 respectively. The FrameSet's Base attribute has the value 1 and its Current attribute has the value 3. The transformation performed when the FrameSet is used as a Mapping (i.e. from its base to its current Frame) is shown in bold.
AST A Library for Handling World Coordinate Systems in Astronomy