tvtie Documentation

The TVTIE program is able to operate in two basic modes: TIE
point mode and MATCH point mode.  MATCH point mode is selected
by including "/MATCH" as one of the parameters in the command
line that invokes the program.  (This can be abreviated as
"/M".)  If "/MATCH" is omitted, then the program operates in
TIE point mode.


TVTIE PARAMETERS

The TVTIE program has two positional IDL parameters.  These are
string values that specify two input cube files.  (A default
file extension of '.cub' is assumed if none is specified.)
TVTIE will update the label information of the first file, which
is called "Image A."  The second file is called "Image B" and
is never modified by the program.  Image B is optional when
TIE point mode is selected.  The following are the optional
keyword IDL parameters:

    SFROM1 - String that contains the input subcube specifier
	for Image A.  A single band must be selected.  If a
	spatial subarea is specified, then it must be a
	contiguous area, i.e., increments in the sample and
	line dimensions are not permitted.  If SFROM1 is not
	specified, then the default value '::1' is used.
    SFROM2 - String that contains the input subcube specifier
	for Image B.  If not specified, then the value of
	SFROM1 will be used as the default value.
    RANGE1 - A two element array that specifies the range of
	pixel values in Image A that is to be mapped into
	the available display intensities.  If not specified,
	then a default value of [0.0,255.0] is used.
    R1OPTION - Option for determining the RANGE1 values to be 
	used:
	R1OPTION=1 specifies that the specified (or default) 
	values of RANGE1 are to be used.
	R1OPTION=2 specifies that the RANGE1 values are to be
	automatically computed by examining the image data and
	applying the LOSAT1 and HISAT1 factors.
	If not specified, then a default value of R1OPTION=2 
	is used.
    LOSAT1 and HISAT1 - When selected by R1OPTION=2, these 
	values specify the percent of image pixels on the low 
	and high sides that are to be saturated by the automatic 
	RANGE1 computation.  If one of these values is not 
	specified, then a default value of 0.5 is used.
	If a zero value for LOSAT1 (or HISAT1) is specified,
	then the RANGE1 minimum (or maximum) that is computed 
	will be the lowest (or highest) pixel value that occurs.
    RANGE2 - Range of pixel values for Image B.  If not
	specified, then the value of RANGE1 will be used as
	the default.
    R2OPTION - Option for determining the RANGE2 values to be 
	used:
	R2OPTION=1 specifies that the specified (or default) 
	values of RANGE2 are to be used.
	R2OPTION=2 specifies that the RANGE2 values are to be
	automatically computed by examining the image data and
	applying the LOSAT2 and HISAT2 factors.
	R2OPTION=3 specifies that the RANGE2 values are to be 
	the same as the values used for RANGE1, which could be 
	automatically computed (R1OPTION=2) or explicitly 
	specified (R1OPTION=1).
	If not specified, then a default value of R2OPTION=2 
	is used.
    LOSAT2 and HISAT2 - When selected by R2OPTION=2, these values
	specify the percent of image pixels on the low and high
	sides that are to be saturated by the automatic RANGE2
	computation.  If one of these values is not specified,
	then a default value of 0.5 is used.
	If a zero value for LOSAT2 (or HISAT2) is specified,
	then the RANGE2 minimum (or maximum) that is computed 
	will be the lowest (or highest) pixel value that occurs.
    OPTION - Option to use in computing camera angle updates.
	OPTION=1 allows only translation of the image.
	OPTION=2 allows both translation and rotation of the
	image.
	If not specified, then a default value of 2 is used.
    CTOLERANCE - Error tolerance (pixels) to use in updating
	the camera angles.  If the error in lines or samples
	is greater than the tolerance set, then the CAMERA_ANGLES
	keyword in the label will not be updated.  If this
	parameter is not specified, then a default value of 5
	is used.
    STOLERANCE - Error tolerance (pixels) to use in performing
	the subpixel registration operation.  If the computed
	adjustment exceeds the STOLERANCE value, then the
	Sample,Line coordinate for Image A is not updated.  
	This parameter value is also used to expand the size of
	the search area to BOX+(STOLERANCE*2).  If this parameter
	is not specified, then the value of CTOLERANCE will be
	used as the default value.
    EQORDER - The equation order to be used for computing the
	subpixel registration operation.  This must be in the
	range 1 through 8.  If this parameter is not specified,
	then a default value of 1 is used.
    SRANGE - A two element array that specifies the range of
	pixel values that are to be used for the subpixel
	registration operation.  If not specified, then a default
	value of [-3.4E38, +1.7E38] is used.  (Special pixel
	values are never used in computing the subpixel
	registration.)
    BOX - Size of the search area to be used for the subpixel
	registration operation.  (The actual search area box
	size will be BOX+(STOLERANCE*2).)  If not specified,
	then a default value of BOX=25 will be used.
    /MATCH - Selects MATCH mode rather than the default TIE
	mode.


OVERVIEW OF TIE POINT MODE

TIE point mode allows the user to interactively display and
define TIE points and record them on the label of a cube file.
Each TIE point consists of a set of five values: Latitude,
Longitude, Sample, Line, and Height.  The Sample and Line values
are the spatial coordinates of the point within the cube file.
Height is an optional local radius of the planet.  Each TIE
point is recorded in the label using a keyword named
RAW_TIE_POINTn, where "n" is the TIE point number.  TIE points
are numbered from 1 to 9.  The TVTIE program also allows
using the set of currently defined TIE points to update the
camera angles recorded in the label.

When setting (or updating) the Sample and Line spatial
coordinate, the desired point is specified by positioning the
cursor on the desired location.  The Latitude and Longitude
information can be specified in three different ways:
numerical values typed by the user, values computed from a
specified spatial location on Image A (the image being
processed), or values computed from a specified spatial location
on the optional Image B.  The interactive commands are described
below.


OVERVIEW OF MATCH POINT MODE

MATCH point mode allows the user to interactively display two
images and define pairs of spatial coordinates that "match"
on the two images.  Each MATCH point is stored in the label
of a cube file using keywords named MATCH_POINTn, where "n" is
the MATCH point number.  MATCH points are numbered from 1 to 20.
Each MATCH point stored in the label of Image A consists of the
Sample and Line coordinate for Image A, the Sample and Line
coordinate for Image B, and an integer value called the FSC that
identifies Image B.  Different MATCH points can refer to images
with different FSC identifiers.


DISPLAY OF IMAGES AND TIE/MATCH POINTS

Image A is always displayed on the left side of the screen.
This is the image whose label is being updated.

Three views of each image are displayed.  The upper display
window shows a full-resolution view of the image.  This will
have scroll bars if the selected spatial area will not fit in
the window.  The lower left window shows a subsampled version
of the entire selected spatial area.  Clicking ANY mouse button
in the subsampled view will change the scroll on the
full-resolution view so that the selected point is visible.
The lower right window shows a zoomed view of a selected area
of the image.  Clicking the MIDDLE mouse button in either the
zoomed view or the full-resolution view will move the cursor
to the corresponding location in the other view.  This will
also adjust the scroll so that the selected point is visible.

Each of the displayed images (A, B, or both) can be rotated
clockwise 90, 180, or 270 degrees by selecting the desired
option in the "CW Rotation" buttons.  Selecting a different
rotation amount will change all three views of the image.  Note
that the rotation amounts are specified as rotations relative
to the original non-rotated image.  Thus, if "90" has been
selected, selecting "90" a second time will not cause an
additional 90 degree rotation to a total of 180 degrees rotation.  
Instead, selecting "180" will cause an additional 90 degree
rotation to the final 180 orientation.  The cursor Sample,Line
coordinates are always reported as coordinates in the original
non-rotated image.


In TIE point mode, the TIE points recorded in the label of
Image A are drawn on Image A using "X" symbols.  Note that
the location of each symbol is the Sample,Line coordinate that
is recorded for the point.  This is not necessarily the same
as the Sample,Line that corresponds to the recorded Latitude,
Longitude.  The scrolling list also shows the numerical values
of the TIE points.

In MATCH point mode, ALL the MATCH points recorded in the label
of Image A are drawn on Image A using "X" symbols.  If the FSC
of the point does NOT match the currently displayed Image B,
then a small "X" is drawn.  If the FSC does match, then a large
"X" is drawn on both Image A and Image B.  The locations of the
symbols are the Sample,Line coordinates recorded for the MATCH
points.  Also, the MATCH points recorded in the label of Image B
are examined and drawn on Image B using box symbols.  If the FSC
does NOT match Image A, then a small box is draw.  If the FSC
DOES match, then a large box is drawn on both Image B and Image A.

When the user selects a point from the scrolling list to be
modified or defined, the data for the selected point are
copied into a TEMPORARY point (if the selected point is defined).
The current numerical values for the TEMPORARY point are
displayed below the scrolling list.  In addition, the current
sample and line coordinate of the TEMPORARY point is marked
on the images with a "+" symbol.  When a point on Image B has
been used to define the Latitude,Longitude of the TEMPORARY
TIE point, the location is marked on Image B with a "+" symbol.

Menu buttons allow the user to enable or disable the drawing of
each of the five types of tie point or match point markers.
Clicking the left mouse button while the cursor is on a menu
button will toggle whether or not the markers are displayed.


INTERACTIVE COMMANDS

Clicking the LEFT or RIGHT mouse buttons in the zoomed view of
an image has the same effect as clicking in the full-resolution
view.  The following describes the actions performed for LEFT
and RIGHT mouse button clicks:

  TIE Mode, Image A
    LEFT - Put the current Sample,Line coordinate into the
	TEMPORARY point
    RIGHT - Compute the Latitude,Longitude of the current
	point and put it into the TEMPORARY point

  TIE Mode, Image B
    LEFT - Not applicable
    RIGHT - Compute the Latitude,Longitude of the current
	point and put it into the TEMPORARY point

  MATCH Mode, Image A
    LEFT - Put the current Sample,Line coordinate into the
	TEMPORARY point for the Image A value
    RIGHT - Compute the Latitude,Longitude of the current
	point and move cursor to the Sample,Line on Image B
	that corresponds to the same Latitude,Longitude

  MATCH Mode, Image B
    LEFT - Put the current Sample,Line coordinate into the
	TEMPORARY point for the Image B value
    RIGHT - Compute the Latitude,Longitude of the current
	point and move cursor to the Sample,Line on Image A
	that corresponds to the same Latitude,Longitude

Positioning the cursor on the small rectangle located between 
the zoomed image and the zoom factor increment/decrement buttons 
allows changing the location of the TEMPORARY point by one pixel 
at a time.  Clicking the middle mouse button toggles bewteen 
controlling the horizontal (sample) or vertical (line) coordinate 
of the TEMPORARY point.  Clicking the left/right mouse button 
increments/decrements the horizontal or vertical position.


The following describes the actions performed by the
function buttons:

Tools - Allows loading display color tables and/or modifying
	the display stretch.  There are three interactive 
        stretch options.  "Stretch (Percent)" shows the Stretch
	Bottom and Stretch Top values in terms of percent of the
	range of pixel values that is being displayed. The other 
	two perform the same stretch operations, but the Stretch 
	Bottom and Stretch Top are labelled in terms of the actual
	ISIS pixel values that are being displayed in Image A 
	or Image B.  You cannot have both Image A and Image B 
	stretch functions active at the same time.  If you want to 
	see stretch values in terms of the other image, then you 
	must exit the current stretch function.  (You can have the 
	percent stretch function active at the same time as one of 
	the image stretch functions.  However, when you change the 
	sliders on one stretch function, the sliders on the other 
        are not dynamically updated.)  Note that both images are
        always displayed with the same color table and stretch.
        You cannot apply different stretches or color tables to
        the two images.
Save - Move the TEMPORARY point values into the currently
	selected point and write the values to the label of
	Image A.
Delete - Delete the currently selected point from the label
	of Image A.
Lat/Lon - Allows typing in numerical values for Latitude,
	Longitude and Height.  Click any mouse button in the
	type-in area to select the item.  Use the backspace
	key to correct typing errors.
Subpixel Register - Use the subpixel registration algorithm
	to update the TEMPORARY point Sample,Line coordinates
	for Image A.  The marker displayed on Image A will be
	moved to show the updated TEMPORARY point Sample,Line
	coordinates.  (The marker on the zoomed image is always
	displayed on the center of a selected pixel.  The
	selected pixel coordinate is determined by ROUNDING
	the fractional pixel coordinate computed by the
	subpixel registration algorithm.  Thus, for example,
	a pixel coordinate of 23.6 will select the pixel at
	intger coordinate 24.)
Draw Limb - Draw the limb of the planet.
Erase Limb - Erase the drawn limb of the planet.
Camera Angles - Compute new camera angles using the currently
	defined set of TIE points.  Write the updated angles
	to the label of Image A.
A Image - Move the cursor to Image A.  In MATCH mode, the
	cursor goes to the Sample,Line coordinate recorded
	in the TEMPORARY point.  In TIE mode, the cursor goes
	to the Sample,Line coordinate computed from the
	recorded Latitude,Longitude (which might be different
	from the recorded Sample,Line)
B Image - Move the cursor to Image B.  In MATCH mode, the
	cursor goes to the Sample,Line coordinate recorded
	in the TEMPORARY point.  In TIE mode, the cursor goes
	to the Sample,Line coordinate computed from the
	recorded Latitude,Longitude (which might be different
	from the recorded Sample,Line)
Marker Color - Change the color that is being used for drawing
	the markers and drawing the planet's limb
Special Pixel Colors - Create control panel that allows 
	changing the colors used for displaying special pixels

Programmer:  Jim Torson, U.S. Geological Survey, Flagstaff