next up previous
Next: AST_GETREFPOS - Return the reference position in a specified celestial coordinate system
Up: AST Routine Descriptions
Previous: AST_GETLINE - Obtain text to be written by a Channel sink routine

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

Description:
This function returns a pointer to a Mapping that will convert coordinates between the coordinate systems represented by two Frames in a FrameSet.

Invocation:
RESULT = AST_GETMAPPING( THIS, IFRAME1, IFRAME2, STATUS )

Arguments:
THIS = INTEGER (Given)
Pointer to the FrameSet.
IFRAME1 = INTEGER (Given)
The index of the first Frame in the FrameSet. This Frame describes the coordinate system for the "input" end of the Mapping.
IFRAME2 = INTEGER (Given)
The index of the second Frame in the FrameSet. This Frame describes the coordinate system for the "output" end of the Mapping.
STATUS = INTEGER (Given and Returned)
The global status.

Returned Value:
AST_GETMAPPING = INTEGER
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 values given for the IFRAME1 and IFRAME2 arguments should lie in the range from 1 to the number of Frames in the FrameSet (as given by its Nframe 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 arguments to have the same value, in which case a unit Mapping (UnitMap) 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 TranForward and TranInverse attributes of the returned Mapping should be inspected to determine if the required transformation is available.
  • A null Object pointer (AST__NULL) will be returned if this function is invoked with STATUS set to an error value, or if it should fail for any reason.



next up previous
Next: AST_GETREFPOS - Return the reference position in a specified celestial coordinate system
Up: AST Routine Descriptions
Previous: AST_GETLINE - Obtain text to be written by a Channel sink routine

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 210
R.F. Warren-Smith & D.S. Berry
30th April 2003
E-mail:ussc@star.rl.ac.uk

Copyright (C) 2003 Central Laboratory of the Research Councils