This attribute can be used to change the Mapping that connects the current Frame to the other Frames in the FrameSet. By default, each Frame in a FrameSet is connected to the other Frames by a single Mapping that can only be changed by using the astRemapFrame method. However, it is also possible to associate multiple Mappings with a Frame, each Mapping having an identifying name. If this is done, the " Variant" 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 " SKY" . That is, instead of searching for Frames that have a class of " SkyFrame" , such software searches for Frames that have a Domain of " SKY" . 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 " Variant" 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 SkyFrames.

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 " Variant" 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 " Variant" 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.

Clearing the " Variant" attribute will have the effect of removing all variant Mappings (except for the currently selected Mapping) from the current Frame.

Testing the " Variant" 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.

FrameSet