In versions of AST prior to version 2.0, the Unit attribute was nothing more than a descriptive string intended purely for human readers--no part of the AST system used the Unit string for any purpose (other than inclusion in axis labels produced by the Plot class). In particular, no account was taken of the Unit attribute when finding the Mapping between two Frames. Thus if the conversion between a pair of 1-dimensional Frames representing velocity was found (using astConvert ) the returned Mapping would always be a UnitMap, even if the Unit attributes of the two Frames were ``km/h'' and ``m/s''. This behaviour is referred to below as a passive Unit attribute.
As of AST version 2.0, a facility exists which allows the Unit attribute to be active; that is, differences in the Unit attribute may be taken into account when finding the Mapping between two Frames. In order to minimise the risk of breaking older software, the default behaviour of simple Frames and SkyFrames is unchanged from previous versions (i.e. they have passive Unit attributes). However, the new functions astSetActiveUnit and astGetActiveUnit allow this default behaviour to be changed. The SpecFrame and TimeFrame classes always have an active Unit attribute (attempts to change this are ignored).
For instance, consider the above example of two 1-dimensional Frames describing velocity. These Frames can be created as follows:
AstFrame *frame1, *frame2; frame1 = astFrame( 1, "Domain=VELOCITY,Unit=km/h" ); frame2 = astFrame( 1, "Domain=VELOCITY,Unit=m/s" );
By default, these Frames have passive Unit attributes, and so an attempt to find a Mapping between them would ignore the difference in their Unit attributes and return a unit Mapping. To avoid this, we indicate that we want these Frames to have active Unit attributes, as follows:
astSetActiveUnit( frame1, 1 ); astSetActiveUnit( frame2, 1 );
If we then find the Mapping between them as follows:
AstFrameSet *cvt; ... cvt = astConvert( frame1, frame2, "" );
the Mapping contained within the FrameSet returned by astConvert will be a one-dimensional ZoomMap which simply scales its input (a velocity in ) by a factor of 0.278 to create its output (a velocity in ).
In fact we need not have set the Unit attribute active in ``frame1'' since the behaviour of astConvert is determined by its ``to'' Frame (the second Frame parameter).
AST A Library for Handling World Coordinate Systems in Astronomy