FrameSetFrameSet - Set of inter-related coordinate systems

Description:
A FrameSet consists of a set of one or more Frames (which describe coordinate systems), connected together by Mappings (which describe how the coordinate systems are inter-related). A FrameSet makes it possible to obtain a MappingMapping between any pair of these Frames (i.e. to convert between any of the coordinate systems which it describes). The individual Frames are identified within the FrameSet by an integer index, with Frames being numbered consecutively from one as they are added to the FrameSet.

Every FrameSet has a "base" FrameFrame and a "current" Frame (which are allowed to be the same). Any of the Frames may be nominated to hold these positions, and the choice is determined by the values of the FrameSet's BaseBase and CurrentCurrent attributes, which hold the indices of the relevant Frames. By default, the first Frame added to a FrameSet is its base Frame, and the last one added is its current Frame.

The base Frame describes the "native" coordinate system of whatever the FrameSet is used to calibrate (e.g. the pixel coordinates of an image) and the current Frame describes the "apparent" coordinate system in which it should be viewed (e.g. displayed, etc.). Any further Frames represent a library of alternative coordinate systems, which may be selected by making them current.

When a FrameSet is used in a context that requires a Frame, (e.g. obtaining its TitleTitle value, or number of axes), the current Frame is used. A FrameSet may therefore be used in place of its current Frame in most situations.

When a FrameSet is used in a context that requires a Mapping, the Mapping used is the one between its base Frame and its current Frame. Thus, a FrameSet may be used to convert "native" coordinates into "apparent" ones, and vice versa. Like any Mapping, a FrameSet may also be inverted (see astInvertastInvert), which has the effect of interchanging its base and current Frames and hence of reversing the Mapping between them.

Regions may be added into a FrameSet (since a RegionRegion is a type of Frame), either explicitly or as components within CmpFrames. In this case the Mapping between a pair of Frames within a FrameSet will include the effects of the clipping produced by any Regions included in the path between the Frames.

Constructor Function:
astFrameSetastFrameSet
Inheritance
The FrameSet class inherits from the Frame class.
Attributes
In addition to those attributes common to all Frames, every FrameSet also has the following attributes:

  • BaseBase: FrameSet base Frame index

  • CurrentCurrent: FrameSet current Frame index

  • NframeNframe: Number of Frames in a FrameSet

Every FrameSet also inherits any further attributes that belong to its current Frame, regardless of that Frame's class. (For example, the EquinoxEquinox attribute, defined by the SkyFrameSkyFrame class, is inherited by any FrameSet which has a SkyFrame as its current Frame.) The set of attributes belonging to a FrameSet may therefore change when a new current Frame is selected.
Functions
In addition to those functions applicable to all Frames, the following functions may also be applied to all FrameSets:

  • astAddFrameastAddFrame: Add a Frame to a FrameSet to define a new coordinate system

  • astGetFrameastGetFrame: Obtain a pointer to a specified Frame in a FrameSet

  • astGetMappingastGetMapping: Obtain a Mapping between two Frames in a FrameSet

  • astRemapFrameastRemapFrame: Modify a Frame's relationship to the other Frames in a FrameSet

  • astRemoveFrameastRemoveFrame: Remove a Frame from a FrameSet