next up previous
Next: AST_SETREFPOS - Set the reference position in a specified celestial coordinate system
Up: AST Routine Descriptions
Previous: AST_SET<X> - Set an attribute value for an Object

   
AST_SETACTIVEUNIT - Specify how the Unit attribute should be used

Description:
This routine sets the current value of the ActiveUnit flag for a Frame, which controls how the Frame behaves when it is used (by AST_FINDFRAME) as a template to match another (target) Frame, or is used as the TO Frame by AST_CONVERT. It determines if the Mapping between the template and target Frames should take differences in axis units into account. The default value for simple Frames is zero, which preserves the behaviour of versions of AST prior to version 2.0.

If the ActiveUnit flag of the template Frame is .FALSE., then the Mapping will ignore any difference in the Unit attributes of corresponding template and target axes. In this mode, the Unit attributes are purely descriptive commentary for the benefit of human readers and do not influence the Mappings between Frames. This is the behaviour which all Frames had in older version of AST, prior to the introduction of this attribute.

If the ActiveUnit flag of the template Frame is .TRUE., then the Mapping from template to target will take account of any difference in the axis Unit attributes, where-ever possible. For instance, if corresponding target and template axes have Unit strings of "km" and "m", then the FrameSet class will use a ZoomMap to connect them which introduces a scaling of 1000. If no Mapping can be found between the corresponding units string, then an error is reported. In this mode, it is assumed that values of the Unit attribute conform to the syntax for units strings described in the FITS WCS Paper I "Representations of world coordinates in FITS" (Greisen & Calabretta). Particularly, any of the named unit symbols, functions, operators or standard multiplier prefixes listed within that paper can be used within a units string. A units string may contain symbols for unit which are not listed in the FITS paper, but transformation to any other units will then not be possible (except to units which depend only on the same unknown units - thus "flops" can be transformed to "Mflops" even though "flops" is not a standard FITS unit symbol).

If the ActiveUnit flag is .TRUE., setting a new Unit value for an axis may also change its Label and Symbol attributes. For instance, if an axis has Unit "Hz" and Label "frequency", then changing its Unit to "log(Hz)" will change its Label to "log( frequency )". In addition, the Axis Format attribute will be cleared when-ever a new value is assigned to the Unit attribute.

Note, if a .TRUE. value is set for the ActiveUnit flag, then changing a Unit value for the current Frame within a FrameSet will result in the Frame being re-mapped (that is, the Mappings which define the relationships between Frames within the FrameSet will be modified to take into account the change in Units).

Invocation:
CALL AST_SETACTIVEUNIT( THIS, VALUE, STATUS )

Arguments:
THIS = INTEGER (Given)
Pointer to the Frame.
VALUE = LOGICAL (Given)
The new value to use.
STATUS = INTEGER (Given and Returned)
The global status.

Class Applicability:
SpecFrame
The ActiveUnit flag for a SpecFrame is always .TRUE. (any value supplied using this routine is ignored).

Notes:
  • The ActiveUnit flag resembles a Frame attribute, except that it cannot be tested or cleared, and it cannot be accessed using the generic AST_GET<X> and AST_SET<X> routines.
  • The AST_GETACTIVEUNIT routine can be used to retrieve the current value of the ActiveUnit flag.



next up previous
Next: AST_SETREFPOS - Set the reference position in a specified celestial coordinate system
Up: AST Routine Descriptions
Previous: AST_SET<X> - Set an attribute value for an Object

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