next up previous 264
Next: The Base and Current Frames
Up: Coordinate System Networks (FrameSets)
Previous: Creating a FrameSet


Adding New Frames to a FrameSet

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:

      INTEGER FRAME2, MAPPING12

      ...

      FRAME2 = AST_FRAME( 2, 'Domain=B', STATUS )
      MAPPING12 = AST_ZOOMMAP( 2, 10.0D0, ' ', STATUS )

To add the new Frame into our FrameSet, we use the AST_ADDFRAME routine:

      CALL AST_ADDFRAME( FRAMESET, 1, MAPPING12, FRAME2, STATUS )

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 AST_COPY ([*]) 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:

      CALL AST_ADDFRAME( FRAMESET, 1,
     :                   AST_ZOOMMAP( 2, 5.0D0, ' ', STATUS ),
     :                   AST_FRAME( 2, 'Domain=C', STATUS ),
     :                   STATUS )

Here, we have avoided storing unnecessary pointer values by using function invocations directly as arguments for AST_ADDFRAME. This assumes that we are using AST_BEGIN and AST_END ([*]) 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.
\includegraphics[scale=0.9]{sun210_figures/fsexample.eps}


next up previous 264
Next: The Base and Current Frames
Up: Coordinate System Networks (FrameSets)
Previous: Creating a FrameSet

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
24th May 2011
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2009 Science \& Technology Facilities Council