astGetMappingastGetMapping - Obtain a Mapping that converts between two Frames in a FrameSet

Description:
This function returns a pointer to a MappingMapping that will convert coordinates between the coordinate systems represented by two Frames in a FrameSetFrameSet.
Synopsis:
AstMapping $*$astGetMapping( AstFrameSet $*$this, int iframe1, int iframe2 )
Parameters:
this
Pointer to the FrameSet.
iframe1
The index of the first FrameFrame in the FrameSet. This Frame describes the coordinate system for the "input" end of the Mapping.
iframe2
The index of the second Frame in the FrameSet. This Frame describes the coordinate system for the "output" end of the Mapping.
Returned Value:
astGetMapping()
Pointer to a Mapping whose forward transformation converts coordinates from the first coordinate system to the second one, and whose inverse transformation converts coordinates in the opposite direction.
Notes:
  • The returned Mapping will include the clipping effect of any Regions which occur on the path between the two supplied Frames (this includes the two supplied Frames themselves).

  • The values given for the "iframe1" and "iframe2" parameters should lie in the range from 1 to the number of Frames in the FrameSet (as given by its NframeNframe attribute). A value of AST__BASE or AST__CURRENT may also be given to identify the FrameSet's base Frame or current Frame respectively. It is permissible for both these parameters to have the same value, in which case a unit Mapping (UnitMapUnitMap) is returned.

  • It should always be possible to generate the Mapping requested, but this does necessarily guarantee that it will be able to perform the required coordinate conversion. If necessary, the TranForwardTranForward and TranInverseTranInverse attributes of the returned Mapping should be inspected to determine if the required transformation is available.

  • A null ObjectObject pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.