
SAOimage cursor regions

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.

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).

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.

