##
Maintaining the Integrity of FrameSets

When constructing a FrameSetFrameSet, 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 MappingMapping. 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 FrameFrame is a SkyFrameSkyFrame. We can set a new value for this SkyFrame's EquinoxEquinox attribute simply by using astSetastSet on the FrameSet, as follows:

221#221

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 astRemapFrameastRemapFrame had been used—§14.4) in response to the use of astSet. One way of illustrating this process is as follows:

222#222

This constructs a trivial FrameSet whose base and current Frames are both the same SkyFrame connected by a UnitMapUnitMap. 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:

223#223

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:

224#224

The FrameSet would then convert between galactic and ecliptic coordinates.

Note that astSet is not the only function which has this effect: astClearastClear behaves similarly, as also does astPermAxesastPermAxes (§7.9). 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:

225#225

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.