Handling coordinate systems directly

CCDPACK provides the routine

• WCSEDIT

for direct manipulation of the coordinate system information attached to an image or a group of images. It can examine, add, remove or modify coordinate systems, and select the coordinate system to be regarded as Current.

To examine the coordinate systems attached to an image, you can use WCSEDIT with the parameter MODE set to SHOW; for example:

% wcsedit obs1 show

    WCSEDIT
    =======
  1 NDF accessed using parameter IN

    Index Cur  Domain            Title
    ----- ---  ------            -----

obs1:
      1        GRID              Data grid indices; first pixel at (1,1)
      2        PIXEL             Pixel coordinates; first pixel at (0.5,0.5)
      3        AXIS              Axis coordinates; first pixel at (0.5,0.5)
      4    *   SKY               FK5 equatorial coordinates; mean equinox...
      5        CCD_REG           Alignment by REGISTER

This shows that there are five coordinate systems in the image and that number 4, labelled `SKY' is the Current one. Note that the first three coordinate systems attached to an image are always GRID, PIXEL and AXIS. SKY is not always present but if it is, it should always represent a celestial coordinate system. GRID and PIXEL always have units the same size as that of a pixel (the difference is that GRID is guaranteed to start at (1,1)).

For the other modes (add, remove, current and set) of WCSEDIT you need to specify a given coordinate system, the `target', for WCSEDIT to work with. This is given using the FRAME parameter, and you can use one of the following formats:

• The null value (`!'), indicating the Current coordinate system
• The domain (name) of the coordinate system
• An integer giving the index of the coordinate system
• A "Sky Co-ordinate System" (SCS) value such as EQUAT(J2000) (see section ``Sky Co-ordinate Systems'' in SUN/95).

The first two options are usually the most appropriate. As you can see above, the output of `wcsedit show' will show you what domains there are, what the index of each is, and which coordinate system is Current for a given image.

To change the coordinate system to be used as the Current one therefore, simply write something like:

% wcsedit in='image*' mode=current frame=pixel

or just

% wcsedit 'image*' current pixel

which will set the Current coordinate system of all the image files indicated to pixel coordinates. Since the PIXEL coordinates are in some sense the native ones, if you set Current to PIXEL in this way the images will behave in most respects as if they had no attached coordinate systems at all.

Syntax for removing coordinate systems is much the same:

% wcsedit image remove 4

will remove the fourth (as listed by wcsedit show) coordinate system from file image.

When adding a new coordinate system you must give the transformation which connects it to the target coordinate system. The transformation can be one of the following types:

UNIT:

No coordinate transformation is performed in this case. A copy of an existing coordinate system, but with a new domain (label), can thus be added in this way.

LINEAR:

A general linear tranformation can be specified by giving six coefficients $C_{1-6}$:

$$\begin{eqnarray*} x^\prime & = & C_1 + C_2 x + C_3 y \\ y^\prime & = & C_4 + C_5 x + C_6 y \end{eqnarray*}$$

PINCUSHION:

A pincushion-type transformation, which is a common optical distortion, can be specified by giving three coefficients $C_{1-3}$, the magnitude of the distortion followed by the coordinates of its centre:

$$\begin{eqnarray*} x^\prime = x \left( 1 + C_1 \left[ \left( x - C_2 \right)^2 ... ...t( x - C_2 \right)^2 + \left( y - C_3 \right)^2 \right] \right) \end{eqnarray*}$$

A positive $C_1$ corresponds to a pincushion distortion and a negative $C_1$ corresponds to a barrel distortion.

MATH:

An arbitrary algebraic transformation. In this case you will be asked to specify the mapping between coordinate systems using a FORTRAN-like syntax.

So the following command would add a new coordinate system, labelled `SQUASHED', representing a barrel distortion of the coordinates labelled `FOCAL' having a magnitude of $7\times 10^{-6}$ and an optical centre at coordinates (1000,1000):

% wcsedit 'image*' add frame=focal domain=squashed maptype=pincushion
          coeffs='[-7e-6,1000,1000]'

It's also possible to make fine adjustments to the coordinate systems attached to an image using the SET mode, for example:

% wcsedit file1 set frame='!' set='domain=obs1'

changes the name of the Current coordinate system to `OBS1'. For more sophisticated use of this feature, see the documentation of WCSEDIT in appendix §, and of the AST_SET routine in SUN/210.

When run, WCSEDIT will log what it has done, giving the domain of the altered coordinate system where appropriate (even if it was specified in some other way). If it could not perform the requested action on any of the images in the list, an appropriate message will be written, but this does not consitute a fatal error. However, it does write an list to an output file (by default called WCSEDIT.LIS), giving the names of only those images which were successfully accessed, which normally means those which had a coordinate system matching that given by the FRAME parameter. So it's easy to find out which images were successfully modified:

% wcsedit 'data?' current focal

    WCSEDIT
    =======
  4 NDFs accessed using parameter IN

data1: Current frame set to domain FOCAL

data2: Target frame 'focal' not found
       NDF not modified

data3: Current frame set to domain FOCAL

data4: Current frame set to domain FOCAL

% cat WCSEDIT.LIS
data1
data2
data4

This name list file can be used as an indirection file to pass to the input of another CCDPACK task. For instance, if you want to do an interactive alignment of only those files which have coordinate systems with the name ``FOCAL'', you could follow the above command with this:

% pairndf '^WCSEDIT.LIS'