next up previous
Next: Managing Object Pointers
Up: An AST Object Primer
Previous: Testing, Clearing and Defaulting Attributes

Transforming Coordinates  

We now have the necessary apparatus to start using our ZoomMap to show what it is really for. Here, we will also encounter a routine that is a little more fussy about the type of pointer it will accept.

The purpose of a ZoomMap is to multiply coordinates by a constant zoom factor. To witness this in action, we will first set the Report attribute for our ZoomMap to a non-zero value:

      CALL AST_SET( ZOOMMAP, 'Report=1', STATUS )

This boolean (integer) attribute, which is present in all Mappings (and a ZoomMap is a Mapping), causes the automatic display of all coordinate values that the Mapping converts. It is not a good idea to leave this feature turned on in a finished program, but it can save a lot of work during debugging.

Our next step is to set up some coordinates for the ZoomMap to work on, using two arrays XIN and YIN, and two arrays to receive the transformed coordinates, XOUT and YOUT. Note that these arrays are double precision, as are all coordinate data processed by the AST library:

      DOUBLE PRECISION XIN( 10 ), YIN( 10 ), XOUT( 10 ), YOUT( 10 )
      DATA XIN / 0D0, 1D0, 2D0, 3D0, 4D0, 5D0, 6D0, 7D0, 8D0, 9D0 /
      DATA YIN / 0D0, 2D0, 4D0, 6D0, 8D0, 10D0, 12D0, 14D0, 16D0, 18D0 /

We will now use the routine AST_TRAN2 to transform the input coordinates. This is the most commonly-used (2-dimensional) coordinate transformation routine. If you look at its description in [*], you will see that it requires a pointer to a Mapping, so we cannot supply just any old Object pointer, as we could with the routines discussed previously. If we passed it a pointer to an inappropriate Object, an error message would result.

Fortunately, a ZoomMap is a Mapping ([*]), so we can use it with AST_TRAN2 to transform our coordinates, as follows:

      CALL AST_TRAN2( ZOOMMAP, 10, XIN, YIN, .TRUE., XOUT, YOUT, STATUS )

Here, 10 is the number of points we want to transform and the fifth argument value of .TRUE. indicates that we want to transform in the forward direction (from input to output).

Because our ZoomMap's Report attribute is set to 1, this will cause the effects of the ZoomMap on the coordinates to be displayed on the standard output stream:

(0, 0) --> (0, 0)
(1, 2) --> (5, 10)
(2, 4) --> (10, 20)
(3, 6) --> (15, 30)
(4, 8) --> (20, 40)
(5, 10) --> (25, 50)
(6, 12) --> (30, 60)
(7, 14) --> (35, 70)
(8, 16) --> (40, 80)
(9, 18) --> (45, 90)

This shows the coordinate values of each point both before and after the ZoomMap is applied. You can see that each coordinate value has been multiplied by the factor 5 determined by the Zoom attribute value. The transformed coordinates are now stored in the XOUT and YOUT arrays.

If we wanted to transform in the opposite direction, we need simply change the fifth argument of AST_TRAN2 from .TRUE. to .FALSE.. We can also feed the output coordinates from the above back into the routine:

      CALL AST_TRAN2( ZOOMMAP, 10, XOUT, YOUT, .FALSE., XIN, YIN, STATUS )

The output would then look like:

(0, 0) --> (0, 0)
(5, 10) --> (1, 2)
(10, 20) --> (2, 4)
(15, 30) --> (3, 6)
(20, 40) --> (4, 8)
(25, 50) --> (5, 10)
(30, 60) --> (6, 12)
(35, 70) --> (7, 14)
(40, 80) --> (8, 16)
(45, 90) --> (9, 18)

This is termed the inverse transformation (we have converted from output to input) and you can see that the original coordinates have been recovered by dividing by the Zoom factor.



next up previous
Next: Managing Object Pointers
Up: An AST Object Primer
Previous: Testing, Clearing and Defaulting Attributes

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