
SAOimage cursor mode

intro

SAOimage provides a variety of "software" cursors to identify or delineate
areas of the image.  These are not to be confused with the workstation's
"mouse cursor" (the icon which moves as you move the physical mouse on the
mouse-pad or desk top).  The software cursors are selected and manipulated
while in cursor mode, which is activated by selecting the "Cursor" button
in the main button menu.  In this section, software cursors will be
referred to as "cursors" and the mouse cursor (also called the pointer)
will be called "the mouse".  Special cursor interactions which work in
conjunction with IRAF are discussed in the section on IRAF.

There are five basic cursor shapes: point, polygon, rectangular box, circle,
and ellipse.  The cursor type is selectable by the corresponding button in
the cursor button submenu (see the button menu section).  The latter three
cursor types can be used to make "annuli" of concentric equivalent cursors.
Only one active cursor can exist at any given time.  However, cursors can
be stored, written to disk, and recalled using the "region" features (see
the Region section).  The cursor is always displayed, even when it is not
active (not in cursor mode).  Since the active point cursor has no visible
component, select it when you do not wish to have a cursor visible in your
display.

When a cursor is selected, its position, size, and orientation are
manipulated by using the mouse (see the mouse control section).  As a
general rule, the left mouse button controls the position of the cursor,
the middle mouse button controls the shape or size of the cursor, and
the right mouse button controls the angular orientation of the cursor (if
it has one).  You may either "click" or "drag" the mouse.  Positions,
dimensions, and angles (where applicable) are shared among the latter
three cursors.  The point and polygon cursors pose special cases to the
rule; read about them separately, below.

When SAOimage is in its verbose mode (see the "etc" section), each time
a cursor manipulation is completed, a message is sent to SAOimage's
associated terminal window, giving the cursor coordinates and
dimensions, in units of image file pixels.

positioning

To position the cursor by clicking, move the mouse to the pixel where
you want to center the cursor and then click the left mouse button.
To position the cursor by dragging, press and continue holding down
the left mouse button while moving the mouse.  When the cursor is
positioned where you want it to be, release the left mouse button.
Note that you can use the magnifier "tracking" feature to aid in
positioning the cursor (see the "etc" section) and you can use the
keyboard arrow keys to aid in fine positioning the mouse (see the
mouse control or keyboard sections).

sizing

To adjust the size or shape of the cursor, the same clicking or dragging
procedure is used with the middle mouse button to position the cursor's
edge while its center stays fixed.  When sizing the box or ellipse,
certain restrictions apply, depending on the position of the mouse when
you first press the middle mouse button.  If you are near to a line
through the center and one corner of the box, you will be controlling the
location of the corners of the box (adjusting both dimensions).  If you
are not near one of the diagonals, you will control only the width or
height, depending on the side to which the mouse is closest.  The ellipse
is adjusted by controlling an imaginary box which encloses the ellipse,
having the dimensions of its major and minor axes.  When adjusting the
size of a cursor annuli, since the ratio of width to height is fixed,
the mouse controls the actual edge of the cursor, regardless of its type.

rotation angle

The right mouse button is used to control the rotation angle of boxes
and ellipses.  When the right mouse button is pressed or held down, the
angle is determined by a line from the center of the cursor to the mouse.
The initial angle (0 degrees) points toward the top of the screen.  To
reset the angle to 0 degrees, click on the "ortho" button in the Cursor
submenu.  For the circle cursor, the right button has no function, while
for points and polygons it performs a special delete function (see below).

point cursor

The point cursor is used to flag particular image pixels or coordinate
points.  Its position is defined as that of the mouse.  No active cursor
is drawn.  The mouse buttons are mapped directly to region functions (see
regions).  The left mouse key stores a point include region (to flag a
pixel or coordinate of interest).  The middle mouse button stores a point
exclude region (to flag a bad pixel).  With the mouse positioned to point
at the first character in the label of a saved point, pressing the right
mouse button deletes that saved point.

Saved points are represented by a label giving either its pixel coordinates
or an index number.  By default, the label is stenciled over the image.
However, if the label is too hard to read, the background around the label
can be made solid by selecting the appropriate command line option.  The
point is at the left edge of the point label, and on a line with the
bottom of the characters (not at the lowest edge of the background).  When
making hard copies, SAOimage always fills in the label backgrounds.


polygon cursor

A polygon is defined by straight lines connecting a set of vertices.  For
the active polygon cursor, each vertex is represented by a tiny box.  To
add additional vertex points, drag or click with the middle mouse button.
The next vertex is always added to the side nearest the mouse pointer when
the middle button is depressed.  To move an existing vertex, point the
mouse directly at it when depressing the middle mouse button.  To delete an
unwanted vertex, point the mouse at the unwanted vertex and click the right
mouse button.

The entire polygon can be be moved at any time by using the left mouse
button.  When the left button is depressed, the polygon is moved such that
the nearest vertex has the same position as the mouse pointer.

Clicking on any cursor type submenu button, including the "poly", causes
the polygon to be reduced back to a single point.  In other words, if you
switch cursor types, you cannot return to the polygon which you had been
constructing, unless you saved it as a region.

cursor annuli

Annuli of box, circle, and ellipse cursors are available by selecting the
annuli button from the cursor submenu.  Set the cursor to the desired shape
and angle before selecting the annuli feature, as these cannot be changed
once the annuli feature has been selected.  (The annuli selection changes
the functioning of the middle mouse button and disables any angle control.)

Annuli are sized by clicking or dragging with the middle mouse button.
The center, angle, and width to height ratio remain unchanged while sizing.
When the middle mouse button is first depressed, three possible events may
occur, enabling the user to a) create an annulus with an arbitrary radius,
b) create annuli with fixed radius increments, or c) change the size of an
existing annulus.
  a) If the mouse is between existing annuli or not too far from an
     existing annulus, a new annulus will be created sized by the mouse
     position.
  b) If the mouse is well outside the existing cursor annuli, a new cursor
     is create which radius is initially incremented from the outer annulus
     by the same increment as that between the outer two annuli (or the
     annulus and the center if there is only one annulus).  A comparable
     situation applies when the mouse is well inside the innermost annulus.
     However, once the annulus is created, if you proceed to drag the mouse
     with the middle mouse button down, the size of the new annulus reverts
     to being controlled by the mouse.
  c) If the mouse is pointing at the edge of an existing annulus, that
     annulus will be "grabbed" for sizing.

To delete an unwanted annulus, point the mouse at or near the unwanted
annulus and click the right mouse button.  The innermost or outermost
annulus can be deleted simply by clicking the right mouse button while
the mouse is inside of outside all of the annuli.

All of the annuli are forgotten when any cursor submenu button is
selected, or reselected.  The "annuli" button itself toggles between on
and off.


cursor coloring

Tracking a cursor means updating the displayed cursor as its shape, size,
or location is being manipulated, enabling the user to see the effect of
the manipulation.  Tracking a visible cursor across the display poses a
special problem; how to quickly draw and undraw the cursor as it moves
without wiping out the image underneath.  SAOimage uses two alternative
mechanisms to do this.

On halftone workstations, the tracking cursor is drawn simply as the
opposite color (exclusive or) of the image.  Black pixels appear white
and white pixels appear black, as the the cursor tracks across them.
When the tracking action is completed (when the mouse button is
released), the entire display is redrawn, along with the new cursor.

The same mechanism, as that used on halftone systems, is used on color
workstations when a large number (>100) of display color levels is needed.
During tracking, the inverse of the display pixels may not result in very
noticeable colors, but at least the "shimmering" of the display as the
cursor moves makes it possible to see where the cursor is.

When much cursor manipulation is to be performed, a better alternative is
available.  One bit in each color value is reserved for the cursor.  Then
the cursor may be drawn and undrawn without affecting the display.  This
results in a smooth, continuous display of the cursor throughout any
tracking interaction, with no need to redraw the image at the completion
of the action.  The disadvantage is that the number of available colors
for the image is cut by a factor of two (plus two more colors for the
saved regions and other overlay-like displays).

On color workstations, one may switch freely between the overlay and non-
overlay modes by using the "ovlay" toggle button in the "Color" submenu.
See color section for more details.
