Extracting a Mapping from a FrameSet

Although it is very convenient to use a FrameSetFrameSet when a MappingMapping is required (§13.6), a FrameSet necessarily contains additional information and sometimes this might cause inefficiency or confusion. For example, if you wanted to use a Mapping contained in one FrameSet and insert it into another, it would probably not be efficient to insert the whole of the first FrameSet into the second one, although it would work.

In such a situation, the astGetMappingastGetMapping function allows you to extract a Mapping from a FrameSet. You do this by specifying the two Frames which the Mapping should inter-relate using their indices within the FrameSet. For example:


\begin{terminalv}
map = astGetMapping( frameset, 2, 3 );
\end{terminalv}

would return a pointer to a Mapping that converted between Frames 2 and 3 in the FrameSet. Its inverse transformation would then convert in the opposite direction, i.e. between Frames 3 and 2. Note that this Mapping might not be independent of the Mappings contained within the FrameSet—i.e. they may share sub-Objects—so astCopyastCopy should be used to make a copy if you need to guarantee independence (§4.13).

Very often, the Mapping returned by astGetMapping will be a compound Mapping, or CmpMapCmpMap (§6). This reflects the fact that conversion between the two Frames may need to be done via an intermediate coordinate system so that several stages may be involved. You can, however, easily simplify this Mapping (where this is possible) by using the astSimplifyastSimplify function (§6.7) and this is recommended if you plan to use it for transforming a large amount of data.