7 Statements

Statements are fields within an ARD description which modify the way in which keywords are interpreted. They are followed by an argument list giving various numerical or textual values. Statements can be abbreviated to three characters. The following statements are currently supported ($N$ represents the dimensionality of the ARD description):

DIMENSION( N )

- This establishes the number of coordinates (N) required to describe a single point in the ARD description. If no DIMENSION statement is found before the first keyword field, a value of 2 is assumed for N. The dimensionality may not be changed after the first keyword field, but multiple DIMENSION statements may be included (so long as they all specify the same value for N) to improve readability, and to allow the concatenation of multiple ARD descriptions which contain compatible DIMENSION statements. Note, N gives the number of dimensions in the user co-ordinate system; this may not necessaily be the saem as the number of pixel axes in the mask array.

COEFFS( C1, C2, ... )

- DEPRECATED. Use the COFRAME or WCS statement instead. This establishes a new linear mapping from user coordinates to application coordinates replacing any previous mapping (see Section 4). The statement must have $N\ast \left(N+1\right)$ arguments. If ($X_1$, $X_2$, $X_3$, ..., $X_N$) are a set of user coordinates in $N$ dimensions, and ($Y_1$, $Y_2$, $Y_3$, ..., $Y_N$) are the corresponding application coordinates, then the argument list should contain a set of constants $C_1$ to $C_{N\ast \left(N+1\right)}$, where:

$$\begin{array}{rcll}{Y}_1& =& C_1+C_2.X_1+C_3.X_2+...+C_{N+1}.X_N& \\ Y_2& =& C_{N+2}+C_{N+3}.X_1+C_{N+4}.X_2+...+C_{2.\left(N+1\right)}.X_N& \\ ....& & & \\ Y_N& =& C_{N.N}+C_{N.\left(N+1\right)}.X_1+C_{N.\left(N+2\right)}.X_2+...+C_{N.\left(N+1\right)}.X_N& \end{array}$$

The mapping established replaces any previous mapping, and is used to transform all following coordinates, until another mapping is established. The default mapping results in user coordinates being identical with application coordinates. The OFFSET, SCALE, TWIST and STRETCH statements allow complex mappings to be created without the use of COEFF statement in certain cases.

COFRAME(DOMAIN,...)

- Specifies the user coordinate system (i.e. the coordinate system in which positions are supplied within the remainder of the ARD description). The first argument is the Domain of the coordinate system. There are several special values that causes specialised AST objects to be created to descibe specific forms of coordinate systems:

• “SKY”: If the ARD description is 2-dimensional, an AST SkyFrame will be created.
• “TIME”: If the ARD description is 1-dimensional, an AST TimeFrame will be created.
• “SPECTRUM”: If the ARD description is 1-dimensional, an AST SpecFrame will be created.
• “DSBSPECTRUM”: If the ARD description is 1-dimensional, an AST DSBSpecFrame will be created.

Any other Domain value will cause a simple AST Frame to be created instead. Any subsequent arguments should be of the form <keyword>=<value> where <keyword> is the name of an AST attribute and <value> is the value to assign to the attribute.

OFFSET( X, Y, Z, ... )

- DEPRECATED. Use the COFRAME or WCS statement instead. This modifies the current mapping from user coordinates to application coordinates so that the origin of the user coordinate system is moved by the given offsets in application coordinates. The initial position for the origin of user coordinates is (0,0,0,..). In a 2-dimensional ARD description, the first statement OFFSET(10,15) would put the origin at (10,15) in the application coordinates system. A second statement OFFSET(2,3) would move it to (12,18). The statement must have $N$ arguments.

SCALE( F )

- DEPRECATED. Use the COFRAME or WCS statement instead. This modifies the current mapping from user coordinates to application coordinates so that the user coordinate system is magnified by the given factor F along all axes. The magnification is centred on the origin of the application coordinate system.

STRETCH( F1, F2, F3, ... )

- DEPRECATED. Use the COFRAME or WCS statement instead. This modifies the current mapping from user coordinates to application coordinates so that the user coordinate system is magnified by the given factor $F_i$ along axis $i$. Unlike the SCALE statement, the magnifications are centred on the origin of the user coordinate system (i.e. the position of the origin of the user coordinate system within the application coordinate system is not changed by this statement). The statement must have $N$ arguments.

TWIST( T )

- DEPRECATED. Use the COFRAME or WCS statement instead. This statement modifies the current mapping from user coordinates to application coordinates so that the user coordinate system is rotated by an angle T (in degrees). The rotation is about the origin of the application coordinate system. If the ARD description has more than 2 dimensions, then the rotation takes place in the X-Y plane. Rotation from the X axis to the Y axis is positive. “TWIST” is used rather than the more obvious “ROTATE” in order to avoid a name clash with the keyword ROTBOX.

WCS(...)

- Specifies an AST FrameSet in which the current Frame is the user coordinate system (i.e. the coordinate system in which positions are supplied within the remainder of the ARD description). The “argument list” should be a textual dump of an AST FrameSet as produced by the AST Channel class (e.g. using the AST_SHOW routine). Each line of the dump should be stored as a separate GRP element in the supplied ARD expression - the simplest way to do this is probably to supply the ARD description within a text file, and put each line of the dump on a separate line in the file:

     WCS(<!!
         Begin FrameSet
         IsA Frame
         Nframe = 6
         ...
         ...
         End FrameSet
     !!>)

The <!! and !!> strings tell GRP to treat the enclosed text as verbatim text. That is, any GRP control characters found within the body of the FrameSet dump are treated as literal characters.