Coordinate transformations

The default coordinate system used by AGI is an orthogonal linear system of world coordinates that increase from left to right and bottom to top. If the data coordinate system used by an application complies with these rules then a basic picture saving operation will store sufficient information to recreate these coordinates at a later stage.

If the transformation between data coordinates and the world coordinates of a rectangular piece of the display screen is more complicated than this simple system then a separate transformation has to be stored in the database to define the relationships. AGI uses the TRANSFORM facility described in SUN/61 to define the transformations. AGI does not offer the full flexibility of the TRANSFORM package as it is only interested in the limited case of transforming from the data coordinates into the flat, world coordinates of the display device.

There are two types of transformation to be defined, the first is the transformation from data to world coordinates, and the second is the transformation from world to data coordinates. Usually both will be defined, although this is not a necessity. The present implementation only allows for 2-dimensional data coordinates, and an error will be returned if the number of data variables differs from this.

The transformations are defined as character strings which describe the mathematical formulas as if they appeared in a piece of FORTRAN code. Therefore the description of the formulas should follow all the FORTRAN rules for operators and functions. As an example the case of data coordinates in polar coordinates will be used. The transformation from polar coordinates $(r,\theta)$ to Cartesian world coordinates (x,y) is defined by the equations $x = r \cos( \theta )$ and $y = r \sin( \theta )$. The inverse transformation is defined by the equations $r = \sqrt{x^2+y^2}$ and $\theta = \tan^{-1}(y/x)$. These are formulated in a program in the following way.

    *   Define the number of input ( data ) and output ( world ) variables
    *   Note: This should be 2 for each transformation.
          INTEGER NCD, NCW
          PARAMETER ( NCD = 2, NCW = 2 )

    *   Declare arrays for the two sets of transformations
          CHARACTER * 32 DTOW( NCW ), WTOD( NCD )

    *   Assign the data to world transformation functions
          DTOW( 1 ) = 'X = R * COS( THETA )'
          DTOW( 2 ) = 'Y = R * SIN( THETA )'

    *   Assign the world to data transformation functions
          WTOD( 1 ) = 'R = SQRT( X * X + Y * Y )'
          WTOD( 2 ) = 'THETA = ATAN2( Y, X )'

The transformation is then stored in the database using the routine AGI_TNEW.

If a transformation already exists in an HDS structure which converts the data coordinates into the two dimensional world coordinates of the display screen then the transformation can be copied into the database using the routine AGI_TCOPY.

The AGI interface has four routines which will perform transformations that have been stored in the database. The routine AGI_TDTOW will transform data coordinates into world coordinates, and the routine AGI_TWTOD will perform the inverse. The argument list for these routines includes a picture identifier which indicates the picture containing the transformation. If the identifier is negative then the current picture is searched. The routines take two arrays containing the x and y coordinates of the points to be transformed and returns two arrays containing the new x and y coordinates. In this context x and y need not mean a Cartesian system when used for the data coordinates, they are simply names for the first and second coordinate of the data system. In the above example r and $\theta$ correspond to the x and y coordinates of the data. If no transformation is found in the indicated picture then the identity transformation (output = input) is used. The transformations can be executed with double precision by calling the equivalent routines AGI_TDDTW and AGI_TWTDD.