4 Coordinate Systems

ARD_WORK needs to be able to locate pixels within the given pixel mask. To do this, every position supplied in an ARD description must be converted into pixel coordinates. The position of the origin of pixel coordinates within the mask is fixed by the upper and lower bounds of the mask supplied to ARD_WORK. The conventions for pixel coordinates used by Starlink software are described in Starlink System Note (SSN) 22.

However, it is not always appropriate for an ARD description to describe a region in terms of pixel coordinates. For instance, in a mosaic image a given position on the sky may have different pixel coordinates in each image. To describe a given region in pixel coordinates would therefore require a separate description for each image. In this case, we would ideally like to use a single ARD description in which the region was defined in terms of RA and Dec. positions. This can be done, so long as ARD_WORK knows how to transform an RA/Dec position into pixel coordinates within each of the specified pixel masks.

There are two schemes supported by the ARD library to allow the ARD description to include positions in a coordinate system other than pixel coordinates. As of version 2 of the ARD library, the facilities of the AST library (see SUN/210) can be used to specify positions within generalised non-linear coordinate systems. Prior to version 2, positions needed to be supplied in a coordinate system which was linearly related to pixel coordinates in the mask supplied to ARD_WORK. The version 1 scheme is still available in version 2 of the library, but is deprecated.

4.1 World Coordinate Systems in ARD Version 2

ARD version 2 uses the facilities of the AST library to manage coordinate systems. An AST “FrameSet” describes a collection of related coordinate systems (also called “Frames”), together with the mappings which allows positions to be transformed from one Frame to another. The calling application will always know how to locate a point within the mask if the point is specified in pixel coordinates. If, in addition, it can also locate points specified in one or more other coordinate systems, then it should create a FrameSet describing all the coordinate systems which it knows about, one of which must be pixel coordinates within the mask¹. It then passes this FrameSet to the ARD system by calling routine ARD_WCS (this must be done prior to calling ARD_WORK)². This FrameSet is known as the “Application FrameSet”, and encapsulates knowledge of all the coordinate systems known to the application.

If ARD_WCS is not used, then a default application FrameSet containing a single Frame describing pixel coordinates is generated automatically.

The ARD description must then include statements describing the coordinate system in which positions are given within the ARD description. This can be done in one of three ways:

(1)

By including a COFRAME statement before any keywords. A COFRAME statement describes a single coordinate system, namely that in which positions are given within the ARD description.

ARD_WORK will determine if there is any way of converting positions given within this coordinate system into any of the coordinate systems included in the Application FrameSet, and thus into pixel coordinates. If there is, then the corresponding transformation is used to locate positions within the pixel mask. Otherwise, an error is reported.

(2)

By including a WCS statement before any keywords. A WCS statement specifies a FrameSet describing all the coordinate system known to the user. Positions within the ARD description are then assumed to be given within the “current” Frame of this FrameSet. This FrameSet is known as the “User FrameSet” to distinguish it from the “Application FrameSet”.

ARD_WORK will search both FrameSets looking for a coordinate system which is present in both. If such a Frame is found, the User FrameSet is used to convert positions included in the ARD description into the common Frame, and the Application FrameSet is then used to convert positions from the common Frame into pixel coordinates. If no common Frame is found, then an error is reported. It may be that there is more than one common Frame, in this case priority is given to Frames describing celestial coordinate systems, followed by pixel coordinate Frames, followed by Frames with Domain GRID, followed by Frames with Domain ARDAPP. The highest priority Frame found within this list is used as the common Frame.

(3)

If there is neither a WCS nor a COFRAME statement in the ARD description, then it is assumed that positions are supplied in a default coordinate system. This default is determined as follows:

• If an application FrameSet has been specified using ARD_WCS, then the default coordinate system is the current Frame of the application FrameSet. In this case, the $TR$ argument for routine ARD_WORK is ignored.
• If no application FrameSet has been specified using ARD_WCS, then the default coordinate system is obtained by transforming the pixel coordinate system according to the values supplied for argument $TR$ when calling ARD_WORK. This is the system which was used prior to ARD version 2 (see the next section for more details).

In addition, the deprecated version 1 statements COEFFS, OFFSET, TWIST, STRETCH, SCALE can be used to modify the relationship between the coordinate system used within the ARD description and the default coordinate system describe above. If any of these statements are found, then any earlier COFRAME or WCS statements are ignored, and the requested operation (stretch, twist, offset, etc) is applied to the default coordinate system described above.

An ARD description can contain zero, one or more of the above WCS-related statements. The positions, etc, defining a given region in the description are interpreted using the most recent WCS-related statement. Thus, WCS information given later in an ARD description over-rides any given earlier.

If any of the deprecated version 1 statements (COEFFS, OFFSET, TWIST, STRETCH, SCALE) are found, then any earlier COFRAME or WCS statements are ignored, and the requested operation (stretch, twist, offset, etc) is applied to the default coordinate system described above. For this reason, you should not normally mix the old and the new statements.

4.2 Coordinate Handling in ARD Prior to Version 2

ARD version 1 required the transformation between “user coordinates” (i.e. the coordinate system in which positions are supplied in the ARD description) to pixel coordinates to be linear. This linear transformation was split up into two components; the application specified a linear transformation from pixel coordinates to “application coordinates” when calling ARD_WORK, and the ARD description included statements which defined a linear transformation from application coordinates to user coordinates (by default, user coordinates were assumed to be identical with application coordinates). These two components were concatenated to get the total transformation from pixel to user coordinates.

4.2.1 Application Coordinates

Version 1 applications use the TRCOEF argument of the ARD_WORK routine to define the application coordinate system. TRCOEF would be supplied holding the coefficients of the linear mapping from application coordinates to pixel coordinates. For instance, if a 2-dimensional application coordinates system $\left(x_a,y_a\right)$ is required to be equal to pixel coordinates $\left(x_p,y_p\right)$, but with the origin shifted to pixel coordinates $\left(10,20\right)$, then the linear mapping from $\left(x_a,y_a\right)$ to $\left(x_p,y_p\right)$ is: $$\begin{array}{rcll}{x}_p& =& 10+1.x_a+0.y_a& \\ y_p& =& 20+0.x_a+1.y_a& \end{array}$$

In this case TRCOEF would be supplied holding the 6 coefficient values (10,1,0,20,0,1). In general, if ($Y_1$, $Y_2$, $Y_3$, ..., $Y_N$) are a set of application coordinates in $N$ dimensions, and ($Z_1$, $Z_2$, $Z_3$, ..., $Z_N$) are the corresponding pixel coordinates, then the application supplies a set of constants $C_1$ to $C_{N\ast \left(N+1\right)}$, where: $$\begin{array}{rcll}{Z}_1& =& C_1+C_2.Y_1+C_3.Y_2+...+C_{N+1}.Y_N& \\ Z_2& =& C_{N+2}+C_{N+3}.Y_1+C_{N+4}.Y_2+...+C_{2.\left(N+1\right)}.Y_N& \\ ....& & & \\ Z_N& =& C_{N.N}+C_{N.\left(N+1\right)}.Y_1+C_{N.\left(N+2\right)}.Y_2+...+C_{N.\left(N+1\right)}.Y_N& \end{array}$$

These constants can be supplied to ARD_WORK as a 1-dimensional vector $C$ with N.(N+1) elements, or as a 2-dimensional array $T$ with dimensions ( 0:N, N ) where: $$\begin{array}{rcll}{Z}_1& =& T\left(0,1\right)+T\left(1,1\right).Y_1+T\left(2,1\right).Y_2+...+T\left(N,1\right).Y_N& \\ Z_2& =& T\left(0,2\right)+T\left(1,2\right).Y_1+T\left(2,2\right).Y_2+...+T\left(N,2\right).Y_N& \\ ....& & & \\ Z_N& =& T\left(0,N\right)+T\left(1,N\right).Y_1+T\left(2,N\right).Y_2+...+T\left(N,N\right).Y_N& \end{array}$$

The order in which the coefficient values are stored is the same in both cases.

There will be many cases in which application coordinates are required to be just equal to pixel coordinates. In this case the diagonal elements of the T array ( T(1,1), T(2,2), etc.) would be set to one and all other elements of T would be set to zero. This is likely to be a common requirement, and so ARD_WORK has a special facility for creating such a “unit” mapping. If the first coefficient ( C(1) or T(0,1) ) is set equal to the symbolic constant VAL__BADR (defined in include file PRM_PAR), then ARD_WORK will ignore the supplied values of TRCOEF and use a unit mapping instead.

4.2.2 User Coordinates

The positions and displacements within a Version 1 ARD description are interpreted as application coordinates by default. To supply positions and displacements in some other linearly-related coordinate system, the ARD description would contain statement fields defining the mapping from user coordinates to application coordinates. Such mappings were set up using the statements COEFFS, OFFSET, SCALE, TWIST and STRETCH.

For instance, if the application expects coordinates to be given in arc-seconds but the user wishes to give them in arc-minutes, then the statement SCALE( 60 ) should be included in the ARD description before the first keyword. This mapping is then concatenated with the mapping supplied by the application to get the mapping from user coordinates to pixel coordinates.

The user coordinate system may be changed at any point within an ARD description using suitable statement (COEFFS, etc.), and the new mapping will be used to interpret all further positions until the user coordinate system is modified again.

Arguments which specify distances (such as the radius of a circle for instance) are subject to the current mapping. Thus, for instance, a circle may be transformed into an ellipse if the coordinate axes have different scales.