next up previous
Next: astAddFrame - Add a Frame to a FrameSet to define a new coordinate system
Up: AST Function Descriptions
Previous: AST Function Descriptions

   
astSetActiveUnit - Specify how the Unit attribute should be used

Description:
This function sets the current value of the ActiveUnit flag for a Frame, which controls how the Frame behaves when it is used (by astFindFrame) as a template to match another (target) Frame, or is used as the "to" Frame by astConvert. 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 zero, 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 non-zero, 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 non-zero, 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 non-zero value is set for the ActiveUnit flag, then changing a 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).

Synopsis:
void astSetActiveUnit( AstFrame *this, int value )

Parameters:
this
Pointer to the Frame.
value
The new value to use.

Class Applicability:
SpecFrame
The ActiveUnit flag for a SpecFrame is always 1 (any value supplied using this function 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 astGet<X> and astSet<X> functions.
  • The astGetActiveUnit function can be used to retrieve the current value of the ActiveUnit flag.



next up previous
Next: astAddFrame - Add a Frame to a FrameSet to define a new coordinate system
Up: AST Function Descriptions
Previous: AST Function Descriptions

AST A Library for Handling World Coordinate Systems in Astronomy
Starlink User Note 211
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