Help for MARSTIE

PURPOSE:
To gather tiepoints for a set of overlapping images, either manually or
automatically.  The resulting tiepoints are output in OUT_TPT for use by
other programs such as MARSNAV.

This is a multimission program derived from Mars Pathfinder's mpfnav.
The functionality of mpfnav was split into two parts.  MARSTIE gathers
the tiepoints, and MARSNAV uses those tiepoints to generate a pointing
solution.

MARSTIE supports any mission, instrument, and camera model supported by the
Planetary Image Geometry (Pig) software suite.

EXECUTION:
There are two ways to present input images:

marstie inp=(a.img,b.img,c.img,...) out_tpt=tiepoints.tpt
or
marstie inp=ascii_listoffiles out_tpt=tiepoints.tpt

where ascii_listoffiles is a text file created by Sybase or an editor,
containing the list of filenames to include in the mosaic, one per record.
Up to 200 input images can be listed.

Additionally, an input tiepoint list may be provided:

marstie inp=files.lis in_tpt=tiepoint1.tpt out=tiepoint2.tpt

where: tiepoint1.tpt is a previously generated tiepoints list.

Then use MARSNAV to generate navigation solutions, and then one of the
mosaic programs:

marsnav inp=files.lis out=mosaic.nav in_tpt=tiepoints.tpt
marsmos inp=files.lis out=mosaic.img navtable=mosaic.nav

Note: there are two tiepoint file formats; "old" is the text-based list,
while "xml" is an XML-based format.  The FORMAT parameter controls which
one to use.  Over time "old" should be phased out and eventually the FORMAT
parameter will disappear.

The output file must not exist already, or the program will terminate.
This prevents accidental overwrites of a good tiepoint file.  Also, in
interactive mode, the tiepoint file will be saved after each invocation
of tp.

USAGE:
The program requires that enough overlap exists for at least one tiepoint
to be determined for each overlap pair (but see the the PAIRS parameter).
To operate in batch it is useful to set template and search small and
quality small in order to assure tiepoints (even if they are bad) for later
interactive editing.
 
It is important that all images be connected to each other via tiepoints.
If an image or block of images is not connected, the entire block can "drift"
as a unit out of alignment during the nav process.  The program will report
single unconnected images, but not blocks of them.

The program depends on having some initial pointing parameters in the
images, so that overlaps can be detected and tiepoints found... even though
the purpose of the program is to gather tiepoints to *correct* the pointing!
So the initial pointings (usually predicts) must be at least somewhat close
for the program to work.

METHOD:

1) Candidate points are selected around the picture border every nsw pixels.

2) the camera model is used to project candidate tiepoint locations near the
borders of each image into all of the other images.

3) The 10 points with the best pixel activity are selected 
from each overlap pair.

4) The image rotation is determined and the templates rotated before
correlation to match the search area.

5) the tiepoints are refined by correlating image areas using the Gruen
correlator, with linear correlation.

5.1) In batch, tiepoints with quality < the QUALITY keyword are rejected.

5.2) Tiepoints with excessive shifts > MAXSHIFT are rejected.

5.3) Tiepoints with shifts exceeding SIGMA*standard_deviation_shifts
for each pair are rejected one at a time until only 4 remain.

6) the best tiepoints (by correlation value) are selected for each image pair.
The number selected is controlled by the CULL parameter.  Any additional
tiepoints are rejected.

7) If the INTERACT keyword is specified then the tiepoints will be presented
for editing.

7.1) In SINGLE_EDIT mode (the default), each tiepoint whose correlation
quality is less than QUALITY is displayed using the "tp" program along with
its images. The user can change this point if desired.  Points are selected
using the left mouse button. This makes them green (the first point is
automatically selected for you).  Then you can adjust them using the middle
button.  See the help for tp or the section below.

7.2) In MULTI_EDIT mode, each pair with tiepoints is brought up in tp, with
ALL tiepoints for that pair displayed.  This allows you to edit the entire
set of tiepoints associated with each pair at once.  You have to be more
tp-savvy to do this (using it in multi-point mode) but it can be very helpful
when dealing with lots of tiepoints per image pair.

MARSTIE performs no correlation on interactively selected points, presuming
the user knows what s/he is doing, so be accurate!  However, tp has its own
correlator.  Select Edit/Auto Sync Points or ctrl-A to turn on the
auto-correlator.  As you adjust the point in one image, it will be
interactively correlated and moved in the other image.

Selecing File/Special Exit Status before exiting tp will cause MARSTIE to
save the existing points and exit (thus you can resume the interactive
session later).

Deleting a tiepoint in tp will cause the tiepoint to disappear in MARSTIE
as well.  If this is the only tiepoint in an image pair, this will cause the
pair to be disconnected, which could be bad news for MARSNAV.

TBD:  Some knowledge of the camera models would be useful in tp, for initial
guesses of tiepoint locations.  Might be difficult to implement.

TBD:  Auto Sync Points should be turned on by default.

WARNING: The parameters NORMAL, GROUND, SURF_COORD and SURFACE should be the same as
those used in MARSNAV and the mosaic program to get proper results (although
this is less critical with MARSTIE than with the other programs, because
once you have a tiepoint, the model doesn't matter - the surface is used
only to determine initial points before correlation).

Most stereo cameras (e.g. MPF IMP, M98 SSI) are *not* designed to have their
nodal surface at the azimuth axis.  This introduces LOTS of parallax if single
images contain objects both near and far that do not lie on the surface model.
Pick your points intelligently so you don't pick a near object in this pair
and a far one in that pair, and keep them as close as you can to the surface.

In interactive mode the tiepoints you'll see are already correlated. If there
is insufficient overlap the points will never correlate and will not appear.
You can correct this by reducing the TEMPLATE & SEARCH keywords to force
tiepoints to appear even if they are incorrect, thus giving you the ability to
set them interactively.  You can also use the ALL_PAIRS mode in conjunction
with MULTI_EDIT and INTERACTIVE to bring up all possible pairs without
regard to whether tiepoints were found or even if there's any overlap.

Note:  Only tiepoints with correlations less than QUALITY are presented for
interactive editing.  To force interactive editing of all points, set
QUALITY=1.0.  QUALITY is ignored in MULTI_EDIT mode.


USING TP:

This is not a complete help for tp; just some pointers for use with marstie
(and marsnav).

tp makes heavy use of the *middle* button.  That is how you adjust tiepoints
and the stretch.  The left button is for selecting menus and buttons, and
adjusting the scrollbars.  It is also used for selecting one of multiple
tiepoints in MULTI mode.  The right button is rarely used.

For SINGLE_EDIT mode, when tp comes up, the tiepoint is already selected
for you (it is green).  Use the middle button to adjust it on either side.
DO NOT use the left button!!  Doing so could define another tiepoint or
deselect the current one, which could be bad.  At that point you may need
to consult the general tp help.  If the point turns red, try double-clicking
the left button very carefully over the point.  You want to end up with only
ONE tiepoint (or zero if you delete it) when done.

For SINGLE_EDIT mode, if you mess up and want to start over, simply put more
than one point in, and marstie or marsnav will re-run with the original point.
To do this, middle-click in each image to get a pair of green points.  Select
Edit/Save Point (or the first of the "hidden" buttons, see below).  The point
should turn red.  Do this several times until you have several red points,
then save and exit.  tp will be run again with the original point (only).

For MULTI_EDIT mode, the above does not apply.  All tiepoints are brought
into tp.  The current point is in green; the others are in red.  If you
click with the middle button, the green tiepoint will be moved.  If there
is no green tiepoint, clicking the middle button adds a new one.  Make sure
to do Edit/Save Point (or the first of the "hidden" buttons") to save the
new point.  Save Point is not required for existing points.  The left
button can be used to select which point is green... DOUBLE-click on the
point to select it in both images.  The up and down arrows on the upper left
can also be used to select different tiepoints.

For MULTI_EDIT mode, the best policy is to make sure all tiepoints are red
before saving.  A new tiepoint that has not been saved (it's still green)
will be discarded when you exit... yet existing tiepoints that are green
are not discarded (don't ask, I'm sure there was a reason).  You're safe if
everything is in red.

Turning on the tp correlator (ctrl-A, or Edit/Auto Sync Points) is usually
helpful in either mode.  You can adjust the point on either side and the
opposite one will move in sync.  Note that it can bounce around a bit.  It
is often necessary to select the point you want on both images several times
until the correlator "locks in" to the right spot.  Sometimes you may have
to turn it off (ctrl-A again) to get the point you want.  Try turning it
back on again and tweaking one of the points, sometimes that makes it lock
in.  One might ask why bother; but when the correlator works, it gives you
subpixel accuracy that is difficult to obtain purely interactively.

In MULTI_EDIT mode, once you get two or more tiepoints, it will use an affine
transform to help you place additional ones.  If this works, it's a big help.
However, if there is a lot of parallax this might not work... in which case,
turn off "autofind" mode.

Use the middle button to adjust the stretch ("Contrast") at the bottom.
While the left button works, the middle one allows you to drag the limit
sliders.

The zoom display will automatically re-center around the point if you move
it.  Sometimes it's worth adjusting the point in the main display just because
you get "lost" in the zoom display.

If you do a mixed-mode panorama (say, MER navcam and pancam), the automatic
modes don't work as well (especially in marstie), so you almost have to use
interactive mode (it gets close, but not right on).  In this case it is
helpful to differentially zoom the images in tp.  For example, zooming the
navcam twice as big as the pancam makes the image scale approximately the
same, which should help in (manually) finding tiepoints.  That's one click
on zoom + in the top display and two clicks in the bottom display.

Ctrl-X is a shortcut for save-and-exit.  You should find yourself using
ctrl-X and ctrl-A a *lot*; it is much easier than finding them in the menus.
There is no shortcut for "special exit status"; use the menu.  As a reminder,
setting that before exiting causes marstie to save its results and quit.
Useful if you get tired, or decide you don't need to look at the rest.

Note that marstie prints out "n of m" before each marstie call so you know
how many more to expect.  However, that does NOT take into account the
quality setting, so the actual remaining tp sessions is likely to be fewer
(unless quality=1.0 is used).  It also prints out the image pair for reference,
and the correlation quality value (useful to fine-tune just what the quality
threshold should be).  In MULTI mode, it prints out the image pair #'s being
edited instead.  These will be in order, so you have some idea how far to
go.

Note that the tiepoint does not have to be anywhere near the initial tiepoint.
You can move it anywhere there is overlap.  Of course, it's more useful if
you stay away from where the other tiepoints in this image pair are, if there
are more than one.  Unfortunately marstie does not help you to do this in
SINGLE_EDIT mode; you must either remember where you put previous tiepoints,
or not worry about it.  This is one of the primary reasons for MULTI_EDIT mode.
Keep in mind that the best results are obtained when tiepoints are gathered
in the area you most want to have matched.  So for example if the foreground
is important, pick points in that area instead of on the rover or on the
horizon.  If you want a good horizon, pick points there instead of the
foreground.  You should avoid picking points on the rover itself, unless
the rover is what you want to match (in which case you might want to adjust
the GROUND parameter to match the rover deck).

If you can't find any useful tiepoints at all (say the overlap contains
nothing but sky), you can delete the tiepoint using Edit/Delete Point (or
ctrl-D), then save and exit (ctrl-X).

There are 5 buttons at the top of the tp window, between the arrows after
"No qualifier defined" and the "Autofind" menu.  There is a bug that prevents
the button imagery from being displayed.  For reference, the buttons are
(in order left to right):

SavePoint  DeletePoint  ListPoints  ShiftLeft  ShiftRight

Of these, only the first three will be useful in marstie/marsnav.  DeletePoint
is the most useful, while ListPoints will show the actual coordinate of the
point.  SavePoint can be used to define a bunch of bogus points to force a
restart of tp, as described earlier, and is critical when adding new points
in MULTI mode.

Keep in mind that tp has a *lot* of capabilities that are not being used
by marstie (or marsnav).  Explore if you want, but the above controls are
the only ones that you should need.


TBD:

 This is what should happen eventually:
 read tpts
 for each image pair
     auto-gen tiepoints if not enough currently exist
     if interactive and quality isn't good enough
 	present tpts to user... one at a time or many at once?
 	if special exit status
 	    break loop


COGNIZANT PROGRAMMER:  Bob Deen

HISTORY:
  1994-04-30 J Lorre - Initial mpfnav
  1998-09    B. Deen - Multimission conversion
  1999-07    Split of original MARSNAV into two parts:  MARSTIE and MARSNAV
  2019-12-10 W. Bunch - IDS-7926 - Initialized some variables; cleaned up some -Wall warnings; added unit test.

PARAMETERS: