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 or astConvert) to match another Frame. If the ActiveUnit flag is set in both template and target Frames then the returned Mapping takes into account any differences in axis units. 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 either 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 both Frames 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).

A range of common non-standard variations of unit names and multiplier prefixes are also allowed, such as adding an " s" to the end of Angstrom, using a lower case " a" at the start of " angstrom" , " micron" instead of " um" , " sec" instead of " s" , etc.

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 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).

void astSetActiveUnit( AstFrame $\ast$this, int value )

this

value

SkyFrame

SpecFrame

FluxFrame

CmpFrame

Region:

• 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.