FrameSet Attributes

AllVariants

A list of the variant Mappings associated with the current Frame. (string, read only)

This attribute gives a space separated list of the names of all the variant Mappings associated with the current Frame (see attribute Variant). If the current Frame has no variant Mappings, then the list will hold a single entry equal to the Domain name of the current Frame.

Base

Index of base Frame, starting from 1. (int)

This attribute gives the index of the Frame which is to be regarded as the "base" Frame within a FrameSet. The default is the first Frame added to the FrameSet when it is created (this Frame always has an index of 1).

When setting a new value for this attribute, a string may be supplied instead of an integer index. In this case a search is made within the FrameSet for a Frame that has its Domain attribute value equal to the supplied string (the comparison is case-insensitive). If found, the Frame is made the base Frame. Otherwise an error is reported.

Notes

The Inverse of a FrameSet has the values of its Base and Current attributes interchanged.

Current

Index of current Frame, starting from 1. (int)

This attribute gives the index of the Frame which is to be regarded as the "current" Frame within a FrameSet. The default is the most recent Frame added to the FrameSet (this Frame always has an index equal to the FrameSet's NFrame attribute).

When setting a new value for this attribute, a string may be supplied instead of an integer index. In this case a search is made within the FrameSet for a Frame that has its Domain attribute value equal to the supplied string (the comparison is case-insensitive). If found, the Frame is made the current Frame. Otherwise an error is reported.

Notes

The Inverse of a FrameSet has the values of its Base and Current attributes interchanged.

NFrame

Number of Frames in a FrameSet. (int, read only)

This attribute gives the number of Frames in a FrameSet. This value will change as Frames are added or removed, but will always be at least one.

Variant

Indicates which variant of the current Frame is to be used. (string)

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 FrameSet::remapFrame. 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 FrameSet::addFrame. By default, the Mapping supplied to FrameSet::addFrame is assigned a name equal to the Domain name of the Frame. To assign a different name to it, call FrameSet::renameVariant. The FrameSet::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 FrameSet::mirrorVariants 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 FrameSet::remapFrame, the currently selected variant Mapping is used by FrameSet::remapFrame and the other variant Mappings are removed from the Frame.