Help for MARSINT

NOTE
====
THIS PROGRAM IS NOW OBSOLETE.  Its functionality has been replaced with
MARSMAP with the OVR_OUT parameter.
Grid, footprint, and numbering has been removed, due to API changes in those
routines.  Not worth adapting this obsolete program to them, when those
functions are not needed for the primary purpose of the program anyway.


PURPOSE:

To compute a table containing the intensities of overlap regions. The table
becomes the second output file. The first output is the mosaic used to 
compute the overlaps. See the level2 help on OUT for the file format.
HORIZON can be used to cut off the sky.

This is a multimission program derived from Mars Pathfinder's mpfmap.
It supports and mission, instrument, and camera model supported by the
Planetary Image Geometry (Pig) software suite.

Best results are obtained if the images are all taken from the same camera
at approximately the same position.

The program will optionally put azimuth and elevation (Cylindrical, Polar)
or X and Y (Vertical) lines and annotation on the image.  These can either
appear "on top of" or "underneath" the image.  See GRID, GRID_SPACING, GRID_DN,
and GRID_ZOOM.

In addition, the program will optionally place an image number at the center of
each image in the output, to aid in identification of the images.  See NUMBER,
NUMBER_DN, NUMBER_ZOOM, and NUMBER_START.  It will also optionally draw a
"footprint" border around each image.  See FOOTPRT and FOOT_DN.

The program can accept a navigation file written by marsnav which will improve
the accuracy of the mosaic.

Radiometric correction is performed on the inputs by default; this may be
turned off via the RAD keyword parameter.

EXECUTION:

There are two ways to present input images:

marsint inp=(a.img,b.img,c.img,...) out=(map.img,overlap.txt)
or
marsint inp=ascii_listoffiles out=(map.img,overlap.txt)

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, marsnav may be used:

marsnav inp=ascii_listoffiles out=navtab search=25
marsint inp=ascii_listoffiles out=map.img,overlap.txt navtable=navtab

PARALLEL EXECUTION:

Warning: Cannot be run in parallel at moment.

MARSINT can be run in parallel on multiple machines.  This dramatically
improves the wall-clock execution time of the program.  The MPI (Message
Passing Interface) package is used for interprocess communication.  This is
intended for Beowulf-style clusters, but can be used on any set of machines.
Each node processes a strip of the output mosaic, extending the entire width
and 1/n of the height (where n is the number of parallel nodes).

If parallel execution is not desired, nothing special need be done.
The program will work as before on one node with no extra parameters.
The program can be recompiled without using the MPI library by removing
the LIB_MPI definition from the imake file.  However, this is not
necessary - the MPI-linked version will work in serial fashion just fine.

Consult the MPI documentation for details on parallel execution.  However,
for the simplest case, the following can be done:

First, make sure all involved machines can be accessed via ssh from the
main node (the one on which you start the program).  It is convenient
to set up ssh to work without a password (consult your local System
Administrator), but that is not required.

Second, make sure that any required setups are done in your .cshrc file
on each machine.  This includes environment variables and generally
involves source'ing vicset1.csh and vicset2.csh.  The following is
recommended for a .cshrc file:

if ($?V2TOP == 0) then
    setenv V2TOP /usr/local/vicar/dev    (or wherever your VICAR resides)
    source $V2TOP/vicset1.csh
endif
source $V2TOP/vicset2.csh

Third, make sure all pathnames are absolute and accessible from all
machines.  The current directory is not transferred to the remote machines,
so relative pathnames will not work.

Finally, set up a file containing the node name of each machine to use.
Node names can be repeated, in which case multiple processes will be started
on each machine.  The first one becomes the master machine, and is often
(but not necessarily) the one on which the program is being started.  The
nodes should be of the same architecture (e.g. solaris vs. linux).
For example:

lowe% cat machines.solaris 
# Change this file to contain the machines that you want to use
# to run MPI jobs on.  The format is one host name per line, with either
#    hostname
# or
#    hostname:n
# where n is the number of processors in an SMP.  The hostname should
# be the same as the result from the command "hostname"
lowe
pinatubo
potato
wind

Then the program can be run like this:

$MPILIB/bin/mpirun -np 4 -machinefile machines.solaris $MARSLIB/marsmap ...

where -np is the number of processor nodes, -machinefile is the name of
the file above (this pathname can be relative), and ... are the normal
parameters to marsmap (with absolute pathnames).

Each node sends its stdout/stderr output to the controlling terminal,
so messages from each node will be interleaved.  Specifically, the
"line n" status messages will be interleaved.  Careful examination should
show that all line numbers are eventually printed out.

COORDINATES:

All coordinates and angles are measured in the coordinate system specified
by the COORD parameter.  The default is the FIXED coordinate system.
Fixed coordinates are Surface Fixed for Pathfinder and Mars 98, and the
"special" Site frame for FIDO and MER.  The Instrument coordinates are
Lander for Pathfinder, MVACS for Mars 98, and Rover for FIDO and MER.  See
the COORD parameter for other options.  COORD_INDEX also applies for some
coordinate systems/missions.

This coordinate system applies to both the input parameter values, and all
values reported by the program to stdout.  It is also used for the mosaic
projection itself.

Pathfinder and MER Fixed have +x pointing North, and +z down (nadir).
Mars 98 Fixed has +x pointing North, and +z up (zenith).  Azimuth follows
the right-hand rule, meaning Clockwise for MPF and MER and Counterclockwise
for M98.

USAGE:

Mpfmap creates an output image large enough to contain the mosaic.
You may override input azimuth and elevation limits using keywords:
LEFTAZ, RIGHTAZ, TOPEL, BOTTOMEL for Cylindrical and Polar, and MAXX, MAXY
for Vertical.

Three types of output mosaics are available. These are:

"CYLINDRICAL"
The mosaic consists of lines of constant elevation and columns of constant
azimuth. An equal scale of pixels/degree exists everywhere. The user can
control the extent of the azimuth and elevation coverage.

The program will try to determine a window containing the input images and
only create enough of the output to contain the inputs. If the inputs are
all over the place, this may not succeed.
For large mosaics near 360 degrees, override the algorithm by specifying the
azimuth limits manually.

"POLAR"
The mosaic consists of radial lines of constant azimuth emanating from the
center of the output. Zero azimuth is up. The scale is only constant 
radially. Nadir is the center of the image.

"VERTICAL"
The mosaic consists of a vertical view assuming the landing site is a plane
surface.  The quaternion places North up and East to the right.  All pixels
have an equal X/Y scale.  Note that the scale is NOT specified via the
SCALE parameter; you must use VERT_SCALE instead.
TBD: Need to be able to specify the center, so you don't have to mosaic from
(0,0).

In all cases, labels will be written to the output image specifying all
parameters needed in order to reproject the image, and to convert pixel
coordinates into XYZ view rays in the output coordinate system.  See ????
for details on what the label items mean.

OPERATION:

The program uses the appropriate camera model for each input image and
outputs a mosaic in polar (Cylindrical, Polar) or rectangular (Vertical)
coordinates.  Each pixel in the output is transformed from output azimuth
and elevation (or X/Y location for Vertical) to input picture coordinates
in the following steps:
1. Each output pixel defines a unit vector based on the azimuth/elevation
   in the output (this vector is vertical and based on X/Y location for the
   Vertical projection)
2. We compute the intersection of this vector with a surface model.  This is
   normally a tilted plane, possibly with an offset from the origin of the
   spacecraft coordinate system (so the "ground" can be above or below the
   origin).
3. Then this ground point is ray traced back into the input camera images.
   We take the input images in order of input.
4. The first image is selected which can see the ground point.
5. The DN value in the selected input image is bilinearly interpolated
   and placed into the output location.
   

LIMITATIONS:

This program only looks at azimuth & elevation, or X and Y. It has no concept
of parallax.  For perspective corrected mosaics use marsmos or marsmcauley.

HISTORY:
4-30-94  Initial mpfmap by J Lorre. 
Nov. 98  Multimission conversion by B. Deen
COGNIZANT PROGRAMMER:  Bob Deen

PARAMETERS: