When constructing a FrameSet, you are provided with a framework into which you can place any combination of Frames and Mappings that you wish. There are relatively few constraints on this process and no checks are performed to see whether the FrameSet you construct makes physical sense. It is quite possible, for example, to construct a FrameSet containing two identical SkyFrames which are inter-related by a non-unit Mapping. AST will not object if you do this, but it makes no sense, because applying a non-unit Mapping to any set of celestial coordinates cannot yield positions that are still in the original coordinate system. If you use such a FrameSet to perform coordinate conversions, you are likely to get unpredictable results because the information in the FrameSet is corrupt.
It is, of course, your responsibility as a programmer to ensure the validity of any information which you insert into a FrameSet. Normally, this is straightforward and simply consists of formulating your problem correctly (a diagram can often help to clarify how coordinate systems are inter-related) and writing the appropriate bug-free code to construct the FrameSet. However, once you start to modify an existing FrameSet, there are new opportunities for corrupting it!
Consider, for example, a FrameSet whose current Frame is a SkyFrame. We can set a new value for this SkyFrame's Equinox attribute simply by using AST_SET on the FrameSet, as follows:
CALL AST_SET( FRAMESET, 'Equinox=J2010', STATUS )
The effect of this will be to change the celestial coordinate system which the current Frame represents. You can see, however, that this has the potential to make the FrameSet corrupt unless corresponding changes are also made to the Mapping which relates this SkyFrame to the other Frames within the FrameSet. In fact, it is a general rule that any change to a FrameSet which affects its current Frame can potentially require corresponding changes to the FrameSet's Mappings in order to maintain its overall integrity.
Fortunately, once you have stored valid information in a FrameSet, AST
will look after these details for you automatically, so that the
FrameSet's integrity is maintained. In the example above, it would do
this by appropriately re-mapping the current Frame (as if
AST_REMAPFRAME had been used--) in response to
the use of AST_SET. One way of illustrating this process is as
follows:
INTEGER SKYFRAME
...
SKYFRAME = AST_SKYFRAME( ' ', STATUS )
FRAMESET = AST_FRAMESET( SKYFRAME, STATUS )
CALL AST_ADDFRAME( FRAMESET, 1, AST_UNITMAP( 2, ' ', STATUS )
: SKYFRAME, STATUS )
This constructs a trivial FrameSet whose base and current Frames are both the same SkyFrame connected by a UnitMap. You can think of this as a ``pipe'' connecting two coordinate systems. At present, these two systems represent identical FK5 (J2000) coordinates, so the FrameSet implements a unit Mapping. We can change the coordinate system on the current end of this pipe as follows:
CALL AST_SET( FRAMESET, 'System=Ecliptic, Equinox=J2010', STATUS )
and the Mapping which the FrameSet implements would change accordingly. To change the coordinate system on the base end of the pipe, we might use:
CALL AST_INVERT( FRAMESET )
CALL AST_SET( FRAMESET, 'System=Galactic', STATUS )
CALL AST_INVERT( FRAMESET )
The FrameSet would then convert between galactic and ecliptic coordinates.
Note that AST_SET is not the only function which has this effect:
AST_CLEAR behaves similarly, as also does AST_PERMAXES
(). If you need to circumvent this mechanism
for any reason, this can be done by going behind the scenes and
obtaining a pointer directly to the Frame you wish to modify. Consider
the following, for example:
SKYFRAME = AST_GETFRAME( FRAMESET, AST__CURRENT, STATUS )
CALL AST_SET( SKYFRAME, 'Equinox=J2010', STATUS )
CALL AST_ANNUL( SKYFRAME, STATUS )
Here, AST_SET is applied to the SkyFrame pointer rather than the FrameSet pointer, so the usual checks on FrameSet integrity do not occur. The SkyFrame's Equinox attribute will therefore be modified without any corresponding change to the FrameSet's Mappings. In this case you must take responsibility yourself for maintaining the FrameSet's integrity, perhaps through appropriate use of AST_REMAPFRAME.
AST A Library for Handling World Coordinate Systems in Astronomy