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 astSet on the FrameSet, as follows:
astSet( frameset, "Equinox=J2010" );
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
astRemapFrame had been used--) in response to
the use of astSet. One way of illustrating this process is as follows:
AstSkyFrame *skyframe; ... skyframe = astSkyFrame( "" ); frameSet = astFrameSet( skyframe ); astAddFrame( frameset, 1, astUnitMap( 2, "" ), skyframe );
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 ICRS coordinates, so the FrameSet implements a unit Mapping. We can change the coordinate system on the current end of this pipe as follows:
astSet( frameset, "System=Ecliptic, Equinox=J2010" );
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:
astInvert( frameset ); astSet( frameset, "System=Galactic" ); astInvert( frameset );
The FrameSet would then convert between galactic and ecliptic coordinates.
Note that astSet is not the only function which has this effect:
astClear behaves similarly, as also does astPermAxes
(). 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 = astGetFrame( frameset, AST__CURRENT ); astSet( skyframe, "Equinox=J2010" ); skyframe = astAnnul( skyframe );
Here, astSet 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
astRemapFrame.
AST A Library for Handling World Coordinate Systems in Astronomy