"attribute can be set to indicate the name of the Mapping that is to be used with the current Frame.
A possible (if unlikely) use-case is to create a FrameSet that can be used to describe
the WCS of an image formed by co-adding images of two different parts of the sky. In
such an image, each pixel contains flux from two points on the sky.and so the WCS for
the image should ideally contain one pixel Frame and two SkyFrames - one describing
each of the two co-added images. There is nothing to prevent a FrameSet containing two
explicit SkyFrames, but the problem then arises of how to distinguish between
them. The two primary characteristics of a Frame that distinguishes it from
other Frames are its class and its Domain attribute value. The class of a Frame
cannot be changed, but we could in principle use two different Domain values to
distinguish the two SkyFrames. However, in practice it is not uncommon for
application software to assume that SkyFrames will have the default Domain value
" . That is, instead of searching for Frames that have a class of
" , such software searches for Frames that have a Domain of
" . To
alleviate this problem, it is possible to add a single SkyFrame to the FrameSet,
but specifying two alternate Mappings to use with the SkyFrame. Setting the
" attribute to the name of one or the other of these alternate Mappings
will cause the SkyFrame to be remapped within the FrameSet so that it uses the
specified Mapping. The same facility can be used with any class of Frame, not just
To use this facility, the Frame should first be added to the FrameSet in the usual manner using the astAddFrame method. By default, the Mapping supplied to astAddFrame is assigned a name equal to the Domain name of the Frame. To assign a different name to it, the astAddVariant method should then be called specifying the required name and a NULL Mapping. The astAddVariant method should then be called repeatedly to add each required extra Mapping to the current Frame, supplying a unique name for each one.
Each Frame in a FrameSet can have its own set of variant Mappings. To control the Mappings in use with a specific Frame, you need first to make it the current Frame in the FrameSet.
The astMirrorVariants function allows the effects of variant Mappings associated with a nominated Frame to be propagated to other Frames in the FrameSet.
Once this has been done, setting a new value for the
" attribute of a FrameSet
will cause the current Frame in the FrameSet to be remapped to use the specified
variant Mapping. An error will be reported if the current Frame has no variant Mapping
with the supplied name.
Getting the value of the
" attribute will return the name of the variant
Mapping currently in use with the current Frame. If the Frame has no variant Mappings,
the value will default to the Domain name of the current Frame.
" attribute will have the effect of removing all variant Mappings
(except for the currently selected Mapping) from the current Frame.
" attribute will return a non-zero value if the current Frame
contains any variant Mappings, and zero otherwise.
A complete list of the names associated with all the available variant Mappings in the current Frame can be obtained from the AllVariants attribute.
If a Frame with variant Mappings is remapped using the astRemapFrame method, the currently selected variant Mapping is used by astRemapFrame and the other variant Mappings are removed from the Frame.