Cursor Regions in SAOimage

A region is a cursor which has been stored. SAOimage cursors can be stored, recalled, written to disk, and read from disk using the "region" features. Region controls work only when SAOimage is in "cursor mode". Regions were designed for use with SAO's PROS/IRAF image analysis software, but they can be generally useful. Files in the same format can also be generated from source catalogs using the WCSTools imcat and imstar programs.

There are two classes of regions; include and exclude. When used by the PROS software, an include region indicates an area of interest for analysis (e.g. for counts within a region). An exclude region indicates areas or pixels to be excluded from analysis (e.g. bad pixels or areas affected by other phenomena such as an adjacent source).

Region Display from the Command Line

SAOimage can read and display a PROS region file from the command line using the -region region file name or -reg region file name command. Display of the cursors so read in can be toggled off and on using the ( key. Comments on each cursor line in the region file are used as labels and can be toggled off and on using the ) key. An example of the use of an imcat-generated region file to display a catalog over a FITS image can be seen here.

Source Catalogs and Regions

Centered circle, square, diamond, cross, and X shapes can be used to plot catalogs using the following self-explanatory centered formats, where the numeric parameters are image x and y and radius (or half-width of side) in pixels.

CIRCLE(624,75,15) # gsc 4383.1127
EX(688,703,21) # gsc 4383.0574
DIAMOND(852,504,21) # gsc 4383.0434
CROSS(770,879,21) # gsc 4383.0308
SQUARE(297,529,21) # gsc 4383.0565

Saving and Unsaving

To save the current cursor as a region, type the "S" key for in include region or the "E" key for an exclude region. To unsave the most recently saved region, type the "Delete" key. To unsave an arbitrary region, place the mouse within that region and type the "D" key. If the mouse is within two regions when the "D" key is typed, the smaller region is deleted. When a point cursor is the active cursor, the three mouse keys are mapped to perform the same functions as the "S" key (left mouse button), the "E" key (middle mouse button) and the "D" key (right mouse button). Only point regions can be deleted with the right mouse button. For purposes of deleting, the area of a point region is defined to be the area of the first character of its label.

Saved regions are normally drawn and labeled. On color workstations, include regions are drawn in yellow, while exclude regions are drawn in red. The label usually has three parts: the coordinates of the center, a line from the center to the edge along the region's positive Y axis, and the length of the radius along that line. The radius is followed by a "+" for include regions or a "-" to indicate an exlude region. Only the center coordinate is given for a point (followed by a "+" or "-"). The point is at the left edge of the label and on a line along the bottom of the label characters. Polygons have no labels.

Menu Controls

In the cursor submenu, the "Region" button toggles the cursor control page with the region submenu page. In the region submenu, the "Cursor" button restores the cursor submenu page.

In the region submenu, the "label" button suppresses labeling of the regions. The "view" button completely suppresses display of the regions. These buttons are both toggle buttons which are turned on or off when pressed.

The "cycle" button makes the cursor an exact copy of a region (recalling the cursor). The center of that region and its sequence number are displayed in the magnifier window. Repeatedly pressing "cycle", copies each region in turn (cycles through the regions). The cycled cursor is a normal cursor and can be manipulated. The copied region is unaffected by "cycle", however, the just copied region can be deleted by pressing the "omit" button. The "omit" button only works if the cursor has just been cycled to that region. Once you alter the cursor "omit" is disabled. To adjust a region, "cycle" the cursor to that region, "omit" the original region, adjust the cursor, and then save the cursor as a new region.

The "reset" button clears the memory of all regions (deletes all regions).

The "read" and "write" buttons read and write ascii descriptions of regions to or from a disk file.

Regions as ASCII Disk Files

After saving one or more regions, the stored regions can be written to a disk file. Normally the regions are written in a format which can be parsed by the PROS/IRAF software. If SAOimage is in -imtool mode, it mimics IRAF's Imtool output, which is simply a list of cordinates for the centers of cursors. Either type of file can be read at any time, regardless of the mode.

A PROS region consists of a leading space (include) or "-" sign (exclude) followed by the name of the region type, its center coordinates in file pixels, and then its radius on its X axis, its radius on its Y axis, and its angle in degrees (counter clockwise from straight up as per astronomical convention). Some regions don't have angles (or the angle 0 is not given), circles have only 1 radius, and points have no radii. Polygons are represented by pairs of coordinates (X,Y,X,Y,...). See the PROS region documentation for a full explanation.

# images/m51.fits
# Mon Jan 16 16:09:43 1989
# shape x, y, [x dimension, y dimension], [angle]
 BOX(135.67,213.00,18.00,10.67)
 BOX(504.00,538.00,16.96,106.53,290.714)
 CIRCLE(129.00,306.67,9.89)
-ELLIPSE(486.00,468.00,36.53,44.08,329.036)
-POINT(83.00,349.00)
 POLYGON(131.00,245.00,120.67,280.33,165.00,245.00,140.00,234.67)

Annuli of boxes and ellipses are not supported basic PROS region types. They are implemented as logical combinations of the basic PROS types.

 BOX(149.67,205.00,10.00,4.00)
 BOX(149.67,205.00,20.00,8.00) & !BOX(149.67,205.00,10.00,4.00)
 BOX(149.67,205.00,30.00,12.00) & !BOX(149.67,205.00,20.00,8.00)

The above example has two concentric rings and the center area.

When "write" is pressed, a popup window appears to prompt the user for the file name. The window may be initialized to a default, or the previously given file name. To select a different name name, edit the name in the window (see the Keyboard section). If the named file already exists, another popup window appears with the options to overwrite the existing file ('o'), append to the existing file ('a'), or quit without writing anything ('q').

PROS format files which were previously written can be read back in. Press the "read" button and give the name of the file. Reading does not support the full PROS region syntax (i.e. PIE slices are not supported), but much of the syntax is supported, including any syntax used by the "write". Regions read from disk are added to any regions already stored.

The output as an Imtool list, equivalent to the first example, would look like the following:

# images/m51.fits
# Fri Jan 20 13:35:36 1989
# (x, y)
136 213
504 538
129 307
486 468
83 349
131 245
149 205

If your environment has been properly initialized as for an IRAF Imtool user, the default list output filename will follow standard IRAF conventions. When read, the list coordinates are all read as exclude points.