Image Region of Interest (region)

Most image-related tasks can process a subset of the pixels in an input image. Depending on the task, the selected pixels may either be a fairly arbitrary region, or only a regular subimage of the input image.

The task parameter, region, which gives the region-of-interest consists of a combination of subcommands. Each subcommand specifies either a subregion or the units of the coordinates used in subsequent sub-commands.

The subregions selected by multiple subcommands are effectively `OR-ed' together to form the overall region. That is, the overall region selected is the `union' (not intersection) of the subregions.

For comparatively simple regions, combining subcommands is quite adequate. However for complex regions, a cursor-based program, cgcurs, may be the most convenient for generating the subcommands.

Region specification is composed of one or more of the following subcommands. Each subcommand can be abbreviated to uniqueness, and subcommands are separated by a comma.

images(z1,z2)

This selects the image planes z1 to z2 inclusive. z2 is optional, defaulting to the same value as z1.

quarter(z1,z2)

This is somewhat like the images command, except that it selects only the central quarter of each plane. Both z1 and z2 are optional.

box(xmin,ymin,xmax,ymax)(z1,z2)

This subcommand selects the pixels within a box whose corners are xmin, ymin,xmax and ymax. z1 and z2 are optional, and are the same as in the image subcommand. If the (z1,z2) part is missing, a default is used (generally all planes are selected).

polygon(x0,y0,x1,y1,x2,y2,...)(z1,z2)

This gives the vertices of a polygon.

box(xmin,ymin,xmax,ymax)

is equivalent to

poly(xmin,ymin,xmax,ymin,xmax,ymax,xmin,ymax).

z1 and z2 are the same as with the images and boxes subcommands.

mask(name)

This selects pixels according to the mask given by the mask item in the dataset name.

The units used for the coordinates are controlled by the following subcommands:

abspixel

Subsequent coordinates are given as absolute pixel values (i.e. values ranging from 1 to NAXISi - see prthd or itemize). This affects image coordinates and the coordinates along the third dimension. This is also the default.

relpixel

Subsequent image coordinates are relative to the reference pixel, as defined by the header of the map of interest. Use prthd to see the reference pixel is (CRPIXi).

relcenter

Subsequent image coordinates are relative to the central pixel of the image. This is somewhat like the relpixel command, but used the image centre, rather than the reference pixel.

arcsec

Subsequent image coordinates are given in arcseconds, and are relative to the reference pixel of the map of interest.

kms

Subsequent coordinates in the third dimension are given in km/s.

For example, to specify a 21 by 21 region, centred on the reference pixel, use:

   region=relpix,box(-10,-10,10,10)

or to give a 10 by 10 region in the lower left corner of the image, use

   region=box(1,1,10,10)

If there are multiple maps in the file, use

   region=box(1,1,10,10)(1,2)

to select the first 2 maps.

The region-of-interest specifications can become rather involved, when complex regions are used. As with visibility data selection, @ files (see Section 2.5) are a convenient way to store these.

There are some warnings for those accustomed to the select visibility data selection method:

• The subcommands of a region of interest are logically OR'ed together, whereas in the visibility data selection it is a logically AND. For u-v select the logical OR must be explicitly given by use of the or subcommand.
• The subcommands do not allow a plus or minus prefix, like the visibility data selection does.