Doing it the ARD Way

To mask a region or a series of regions within an NDF, you can create an ASCII Region Definition (ARD) text file. ARD has a powerful syntax for combining regions and supplying WCS information, described fully in SUN/183. An ARD file comprises keywords that define a region, such as RECT to specify a rectangular box; operators that enable regions to be combined, for instance .AND. that will form the intersection of two regions; and statements to define the world co-ordinate system and dimensionality.

Here is an example of the creation of an ARD file.

     % cat myard.ard
     COFRAME(PIXEL)
     PIXEL( 23.5, -17.2 )
     ELLIPSE( 75.2, 296.6, 33, 16, 78 ) 
     POLYGON( 109.5, 114.5, 122.5, 131.5, 199.5, 124.5 )
     CIRCLE( 10, 10, 40 ) .AND. .NOT. CIRCLE( 10, 10, 30 )
     COFRAME(SKY,SYSTEM=FK5,EQUINOX=2000)
     CIRCLE( 10:09:12.2, -45:12:13, ::40 ) 
     CTRL/D

The COFRAME statements indicate the co-ordinate system in which subsequent positions are supplied. Its first argument is the domain. Here the first COFRAME(PIXEL) refers to pixel co-ordinates. Note that these are not the same as pixel indices, as they are displaced by -0.5 with respect to pixel indices. The second COFRAME selects a SKY domain using the FK5 system, so that regular equatorial co-ordinates may be supplied as arguments to subsequent keywords. Other possible values for System  include ECLIPTIC and GALACTIC. If no COFRAME or WCS statement is present, the default co-ordinate system is pixel co-ordinates transformed by any COEFFS, OFFSET, TWIST, STRETCH, SCALE statements. Note that the ARDMASK application, used to mask data with an ARD file, has a DEFPIX parameter where you can choose whether the default co-ordinates are pixel or those of the current WCS Frame. if there is no COFRAME or WCS statement in your ARD file. Still you are recommended to supply a COFRAME or WCS statement in your ARD files to avoid accidentally selecting the wrong regions.

In this example, the regions are: the single pixel at co-ordinates (23.5, -17.2); an ellipse centred at (75.2, 296.6) with semi-major axis of 33 pixels and semi-minor axis of 16 pixels, at orientation 78$^\circ$ clockwise from the x axis; a triangle with vertices at pixel indices (110, 115), (123, 132), (200, 125); an annulus centred on pixel co-ordinates (10.0, 10.0) between radius 30 and 40 pixels; and a circle centred on RA 10:09:12.2, and DEC -45:12:13 of radius 40 arcseconds.

Operators combine regions using a Fortran-like logical expression, where each keyword acts like a logical operand acted upon by the adjoinning operators. Statements are ignored in such logical expressions. There is an implicit .OR. operator for every keyword on a new line. Thus pixels that lie in any of the above regions (the union) are selected.

Where a keyword (such as CIRCLE, RECT, POLYGON) defines an area or volume a pixel is deemed to be part of that region if its centre lies on or within the boundary of the region. For regions of zero volume (such as keywords PIXEL, LINE, COLUMN), the pixel is regarded as part of the region when the locus of the region passes through that pixel. So for example, a PIXEL region will be the pixel emcompassing the supplied co-ordinates; and for a LINE, the selected pixels are all that intersect with the line's locus.

Here are some more examples of ARD files.

     COFRAME(GRID)
     ROTBOX( 12, 15, 20, 10, 36.3 ) .AND. .NOT. ( COLUMN( 13 ) .OR. ROW( 8 ) )

Now the co-ordinates are Grid co-ordinates. This selects all the pixels with a rotated box except those in thirteenth column or eighth row. Note the use of parentheses to adjust or clarify the precedence. The box is centred on grid pixel (12, 15) has sides of length 20 and 10 pixels. The first side of the box--the one with length 20--is at an angle of 36 $\hskip-0.12em\hbox{$^\circ$}\hskip-0.08em$3 measured anticlockwise from the X axis.

     DIMENSION(3)
     CIRCLE( 10.3, 21.6, 32.9, 10.4 )
     LINE( 1.1, 2.2, 3.3, 4.4, 5.5, 6.6 )

This defines a sphere centred at pixel co-ordinates (10.3, 21.6, 32.9) with radius 10.4 pixels, and a line from (1.1, 2.2, 3.3) to (4.4, 5.5, 6.6).

     CIRCLE( 10.3, 21.6, 32.9, 10.4 )

This defines a sphere centred at pixel co-ordinates (10.3, 21.6, 32.9) with radius 10.4 pixels.

     .NOT. ELLIPSE( 75.2, 296.6, 33, 16, 78 )

This selects the whole array except for the ellipse defined as before. Something like this might be useful for excluding a galaxy image before fitting to the background around the galaxy.

There are more details and further ARD facilities described in SUN/183. If you do not wish to read SUN/183, you'll be relieved to learn that there are shortcuts for two-dimensional data...

The first is is provided by GAIA by its Image Analysis $\rightarrow$ Image Regions... tool. Here you can select region types and interactively adjust the region locations and shapes, and then record the selected regions in an ARD file. However, it does not provide the boolean operators other than .OR. to combine a series of regions, or use co-ordinates other than pixel.

KAPPA offers its own interactive graphical tool for generating ARD files. To use ARDGEN you must first display your data on a device with a cursor, such as an X-terminal. DISPLAY with a grey-scale lookup table is probably best for doing that. The grey lets you see the coloured overlays clearly. The following example assumes that the current co-ordinate Frame  in the NDF is PIXEL (i.e. pixel co-ordinates). Consequently all positions are shown below in pixel co-ordinates. If the current co-ordinate Frame in the NDF was not PIXEL but (say) SKY, then ARDGEN would produce positions in SKY co-ordinates. The ARD file generated by ARDGEN always contains a description of the co-ordinate system in which positions are specified, allowing later applications to interpret them correctly, and convert them (if necessary) into other co-ordinate systems.

     % ardgen demo.ard
     Current picture has name: DATA, comment: KAPPA_DISPLAY.
     SHAPE - Region shape /'CIRCLE'/ >

At this point you can select a shape. Enter ? to get the list. Once you've selected a shape you'll receive instructions.

     SHAPE - Region shape /'COLUMN'/ > ellipse

 Region type is "ELLIPSE".  Identify the centre, then one end of the semi-major
 axis, and finally one other point on the ellipse.

    To select a position press the space bar or left mouse button
    To exit press "." or the right mouse button

Once you have defined one ellipse, you can define another or exit to the OPTION prompt. In addition to keyboard 1, pressing the right-hand mouse button has the same effect. Thus in the example, the new shape is a rotated box.

     Region completed. Identify another 'ELLIPSE' region...
     OPTION - Next operation to perform /'SHAPE'/ > shape
     SHAPE - Region shape /'ELLIPSE'/ > rotbox


     Region type is "ROTBOX". Identify the two end points of any edge and then give
     a point on the opposite edge.
     Region completed. Identify another 'ROTBOX' region...

If you make a mistake, use the `Undo' option. Alternatively, enter List at the OPTION prompt to see a list of the regions. Note the `Region Index' of the region(s) you wish to remove, and select the Delete option. At the REGION prompt, give a list of the regions you want to remove. If you change your mind, enter ! at the prompt for Parameter REGIONS, and no regions are deleted.

Now suppose you want to combine or invert regions in some way, you supply Combine at the OPTION prompt. So suppose we have created the following regions in $KAPPA_DIR/ccdframe.

       Region          Region Description
       Index
 
         1   -  ELLIPSE( 174.1, 234.4, 82.2, -43.5, 65.64783 )
         2   -  ELLIPSE( 168.1, 209.1, 29.4, -19.7, 9.441798 )
         3   -  ELLIPSE( 42.2, 244.1, 13, -10.3, 111.8452 )
         4   -  ROTBOX( 40.5, 219.2, 63.8, 38.3, 37.24281 )
         5   -  RECT( 141.5, 1.4, 143.9, 358.8 )
         6   -  POLYGON( 229.8, 247.7,
                         233.4, 247.7,
                         233.4, 258.6,
                         231, 267,
                         229.8, 265.8,
                         228.6, 256.2 )

We want to form the region inside the first ellipse but not inside the second. This done in two stages. First we invert the second ellipse, meaning that pixels are included if they are not inside this ellipse, by combining with the NOT operator.

     OPTION - Next operation to perform /'SHAPE'/ > comb
     OPERATOR - How to combine the regions /'AND'/ > not  
     OPERANDS - Indices of regions to combine or invert /6/ > 2

This removes the original Region 2, decrements the region numbers of the other regions following 2 by one, so that Region 3 becomes 2, 4 becomes 3, and so on. A new Region 7 is the inverted ellipse. The renumbering makes it worth listing the regions before combining regions. The second stage is to combine it with Region 1, using the AND operator. This includes pixels if they are in both regions. In this example, that means all the pixels outside the second ellipse but which lie within the first.

    OPTION - Next operation to perform /'SHAPE'/ > com
    OPERATOR - How to combine the regions /'AND'/ > 
    OPERANDS - Indices of regions to combine or invert /[6,7]/ > 1,6

Here is another example of combination. This creates a region for pixels are included provided they are in one of two regions, but not in both. Here we apply the .XOR. operator to the small ellipse and the first rotated box.

     OPTION - Next operation to perform /'SHAPE'/ > comb
     OPERATOR - How to combine the regions /'AND'/ > xor
     OPERANDS - Indices of regions to combine or invert /[4,5]/ > 1,2

Here is the final set of regions.

     OPTION - Next operation to perform /'SHAPE'/ > list


       Region          Region Description
       Index
 
         1   -  RECT( 141.5, 1.4, 143.9, 358.8 )
         2   -  POLYGON( 229.8, 247.7,
                         233.4, 247.7,
                         233.4, 258.6,
                         231, 267,
                         229.8, 265.8,
                         228.6, 256.2 )
 
         3   -  ( ELLIPSE( 174.1, 234.4, 82.2, -43.5, 65.64783 )
                  .AND.
                  ( .NOT. ELLIPSE( 168.1, 209.1, 29.4, -19.7, 9.441798 ) ) )
 
         4   -  ( ELLIPSE( 42.2, 244.1, 13, -10.3, 111.8452 )
                  .XOR.
                  ROTBOX( 40.5, 219.2, 63.8, 38.3, 37.24281 ) )

Once you are done, enter "Exit" at the OPTION prompt, and the ARD file is created. "Quit" also leaves the programme, but the ARD file is not made.

Having created the ARD file it is straightforward to generate a masked image with ARDMASK²³:

     % ardmask $KAPPA_DIR/ccdframec demo.ard ardccdmask

Figure 13: Masking of $KAPPA_DIR/ccdframec. To the left shows the original ARDMASK regions, and to the right shows the final masked regions after some have been combined.

Figure 13 shows the image with the original regions outlined to the left. Note only the section (:270, :360) is displayed. To see where you have masked, use DISPLAY, which lets you define a colour for bad pixels using the BADCOL parameter.

     % display ardccdmask badcol=red \\

To the right of Figure  13 is the final masked image.