"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 of
" . 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 AST_ADDFRAME method. By default, the Mapping supplied to AST_ADDVARIANT is assigned a name equal to the Domain name of the Frame. To assign a different name to it, the AST_ADDVARIANT method should then be called specifying the required name and a NULL Mapping. The AST_ADDVARIANT 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 AST_MIRRORVARIANTS routine 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
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 .TRUE. if the current Frame contains any variant Mappings,
and .FALSE. 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 AST_REMAPFRAME method, the currently selected variant Mapping is used by AST_REMAPFRAME and the other variant Mappings are removed from the Frame.