next up previous
Next: AST_ANGLE - Calculate the angle subtended by two points at a third point
Up: AST Routine Descriptions
Previous: AST_SETACTIVEUNIT - Specify how the Unit attribute should be used

   
AST_ADDFRAME - Add a Frame to a FrameSet to define a new coordinate system

Description:
This routine adds a new Frame and an associated Mapping to a FrameSet so as to define a new coordinate system, derived from one which already exists within the FrameSet. The new Frame then becomes the FrameSet's current Frame.

This routine may also be used to merge two FrameSets.

Invocation:
CALL AST_ADDFRAME( THIS, IFRAME, MAP, FRAME, STATUS )

Arguments:
THIS = INTEGER (Given)
Pointer to the FrameSet.
IFRAME = INTEGER (Given)
The index of the Frame within the FrameSet which describes the coordinate system upon which the new one is to be based. This value should lie in the range from 1 to the number of Frames already in the FrameSet (as given by its Nframe attribute).
MAP = INTEGER (Given)
Pointer to a Mapping which describes how to convert coordinates from the old coordinate system (described by the Frame with index IFRAME) into coordinates in the new system. The Mapping's forward transformation should perform this conversion, and its inverse transformation should convert in the opposite direction.
FRAME = INTEGER (Given)
Pointer to a Frame that describes the new coordinate system.

This routine may also be used to merge two FrameSets by supplying a pointer to a second FrameSet for this argument (see the Notes section for details).

STATUS = INTEGER (Given and Returned)
The global status.

Notes:
  • A value of AST__BASE or AST__CURRENT may be given for the IFRAME argument to specify the base Frame or the current Frame respectively.
  • This routine sets the value of the Current attribute for the FrameSet so that the new Frame subsequently becomes the current Frame.
  • The number of input coordinate values accepted by the supplied Mapping (its Nin attribute) must match the number of axes in the Frame identified by the IFRAME argument. Similarly, the number of output coordinate values generated by this Mapping (its Nout attribute) must match the number of axes in the new Frame.
  • As a special case, if a pointer to a FrameSet is given for the FRAME argument, this is treated as a request to merge a pair of FrameSets. This is done by appending all the new Frames (in the FRAME FrameSet) to the original FrameSet, while preserving their order and retaining all the inter-relationships (i.e. Mappings) between them. The two sets of Frames are inter-related within the merged FrameSet by using the Mapping supplied. This should convert between the Frame identified by the IFRAME argument (in the original FrameSet) and the current Frame of the FRAME FrameSet. This latter Frame becomes the current Frame in the merged FrameSet.



next up previous
Next: AST_ANGLE - Calculate the angle subtended by two points at a third point
Up: AST Routine Descriptions
Previous: AST_SETACTIVEUNIT - Specify how the Unit attribute should be used

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