Help for MARSMAP

Purpose
-------

To assemble multiple frames into a mosaic in one of three projections:

  Cylindrical
  Polar
  Vertical

Cylindrical and Polar use spherical coordinates; Vertical uses rectangular.
In addition an experimental Sinusoidal projection is implemented, but is
not yet fully tested or validated.

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.

Marsmap can also be used to analyze image overlaps for use with brightness
correction.  This subsumes the functionality of the old "marsint" program.

Marsmap will handle color images automatically if the BAND parameter is not
specified. For mixed color and black-and-white inputs, the number of output
bands will equal the maximum number of bands across all inputs. Images with
less than that number of bands will simply repeat the last available band i.e.,
black-and-white images can be mixed with color images. If BAND is specified,
only that single band (in the multi-banded images) is processed, and black-and-
white images remain unaffected.

Execution
---------

There are two ways to present input images:

marsmap inp=(a.img,b.img,c.img,...) out=map.img
or
marsmap inp=ascii_listoffiles out=map.img

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
marsmap inp=ascii_listoffiles out=map.img navtable=navtab

Parallel Execution
------------------

MARSMAP can be run in parallel in two different ways: across multiple machines
using MPI, and across cores on a single machine using OMP.  The OMP method
is far simpler to use.  Both can be used simultaneously (in which case it
could take up all cores on all machines).

OMP Parallel Processing (multiple cores, single machine)
-----------------------

This program has been parallelized using Open MP (OMP), which is built in
to the g++ compiler.

By default the number of threads used equals the number of cores on the machine
where the program is being run.  Each image line is processed sequentially, but
each sample in the line is assigned to a different core, with "guided,16"
scheduling to keep the workload for each core similar.

Parallel processing can be disabled via the -OMP_OFF keyword.  The number
of threads can be controlled by setting the OMP_NUM_THREADS environment
variable before running the program.  There are numerous other OMP variables
that can be set; see the OMP documentation.  However, the number of threads
is the only one that is likely to be useful in most cases.

MPI Parallel Processing (multiple machines)
-----------------------

MARSMAP 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
-----------

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

With two exceptions, 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.  The exceptions are that the
surface model can optionally be expressed in a different frame using
SURF_COORD or SURF_CSFILE, and the PROJ_ORIGIN parameter can optionally be 
expressed in a different frame using PO_COORD.

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

Marsmap 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 MINX,
MINY, MAXX, MAXY for Vertical.

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

"SINUSOIDAL"
This experimental projection is like Cylindrical except the image scale in
the azimuth direction is reduced based on the cosine of the latitude.  This
helps reduce the distortion of cylindrical when near the zenith or nadir.  It
is not fully implemented or tested.  The CENTER_AZ and CENTER_EL parameters
define the azimuth and elevation of maximum extent.  These default to the
center of the mosaic and 0 degrees elevation, respectively.

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 the
mission SIS for details on what the label items mean.

Overlap Brightness Analysis
---------------------------

If an output filename is given via the OVR_OUT parameter, then marsmap
will additionally create a file containing image overlap information.
Each output pixel is analyzed to see which input images could overlap it.
Then for each unique set of overlapping images, statistics are gathered
on the mean, standard deviation, and number of pixels in the overlapping
area.  This replaces the functionality of the old "marsint" program.
Optionally, statistics can be gathered about the image as a whole ("overall"
overlaps).

This file can then be given to the "marsbrt" program, which will compute
brightness adjustments.  These adjustments can then be supplied back to
marsmap (or any of the mosaic programs) via the BRTCORR parameter.

Normally the statistics are gathered on the given image data (after
radiometric correction, if specified).  USE_HSI can change this to convert
the data to Hue-Saturation-Intensity (HSI) space, gathering statistics on
the Intensity channel.  This is better for correcting color images.  If the
image is not color, the HSI flag is quietly ignored for that image (thus
allowing mixtures of color and BW images).

The RADIUS parameter can be used to control the size of the overlap areas;
setting this to a non-0 value causes all pixels within an overlap to be
within a circle of that radius (centered on the first pixel found).
Pixels outside that area become part of a different overlap.  This makes
the analysis of the data easier and enables things like outlier rejection
to deal with sun glints or parallax isues.

When overlap mode is used, the mosaic overlap is different.  Instead of
the first image coming out on top, in this mode the *last* image in the file
list is on top.  This is simply a side effect of how the overlap analysis
mode works (the output mosaic is rarely actually used in this mode), but the
effect could be useful in certain situations.  The -reverse flag can be used
to get the reverse (last on top) effect without having to use overlap.

In overlap mode, ALL inputs must be loaded into memory simultaneously,
with only one pass through the mosaic.  This means that you may not be able
to handle mosaics that are as large as can be handled without overlap mode
being on, depending on your machine.

Zooming out has relatively little effect on the brightness statistics
and speeds things up considerably.

The HORIZON parameter is generally only useful in overlap mode, to cut off
the horizon so sky pixels are not included in the statistics.

Note:  if the BRTCORR or BIAS parameters are supplied, these are applied
*before* overlaps are computed.  That means, from this program's point of
view, the input images are the corrected ones; the original DN values are not
seen.  Thus the statistics file will include the effects of the BRTCORR or BIAS
implicitly.  This means the same BRTCORR or BIAS parameters must be supplied as
inputs to "marsbrt", or the effects of the input BRTCORR/BIAS will not be taken
into account in the correction file output by "marsbrt".

Sophisticated users could take advantage of this effect to build in a difference
that remains even after correction (by supplying BRTCORR/BIAS here but not to
marsbrt), but that is beyond the scope of this help.

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.
Input images are loaded into memory 20 at a time.

Index Files
-----------
Optionally, index (IDX and ICM) files can be output.  These collectively
identify what pixel from which input was used for each point in the mosaic.

The index file (IDX_OUT parameter) contains, for each pixel, a halfword
integer (16 bit signed) identifying which image the pixel came from.
0 indicates no value (black in the mosaic).  Numbers from 1-n match the
order of files in the input list file (or INP parameter, if a list file
isn't given).  For most mosaics, the file could be converted to byte using
CFORM (half is used to support more than 255 input files).

The ICM file (ICM_OUT parameter) is an Image Coregistration Map.  It is a
two-band float file containing the line, sample coordinate of the input
pixel used for the point.  This is the same basic format as correlation
maps such as MARSCOR3 produces, except that multiple images are involved
(thus the need for the index file).

Overlays
--------
Marsmap can put a number of overlays on the image.  In general, each overlay
type has its own DN value to use for the overlay.  These can be in color if
the output mosaic is color.

* Grids.  Coordinate grids can be plotted on top of the mosaic, or underneath
(showing through only where the mosaic is black).  Labels identify the grid
lines.  See GRID, GRID_SPACING, GRID_DN, GRID_ZOOM.

* Scale bar.  A scale bar can be plotted on the image.  Since scale varies
across the image it is only valid for the location it is plotted.  Still, it
can give some indication of the scale.  Getting the range right is critical
to sizing the bar properly.  By default, it computes range using the surface
model.  However, this can be very inaccurate in some cases.  If possible,
supply the range using BAR_RANGE.  See BAR, BAR_POS, BAR_SIZE, BAR_DN,
BAR_ZOOM, BAR_HEIGHT, BAR_SPACE, BAR_RANGE, BAR_APPROX.

* Numbers.  Image numbers can be plotted at the center of the image.  This is
useful to show which image is which.  See NUMBER, NUMBER_DN, NUMBER_ZOOM,
NUMBER_START.

* Footprints.  Footprints (image outlines) can be plotted, showing the extent
of the images.  -FOOTPRINT draws the outline in the input images, so you see
the image edges (with some aliasing) but not overlaps.  More useful is -OVERLAP
which draws an outline along the entire image border, including where the image
goes "underneath" its neighbor.  See FOOTPRT, FOOT_DN, MAX_FOOT.

* Tiepoints.  If given a tiepoint file (e.g. from marstie), marsmap can plot
the tiepoint locations on the mosaic in varying ways.  This can be useful
during mosaic production but should generally not be used in a production
mosaic.  See TIEPOINTS, TIE_TYPE, TIE_DN.
Limitations
-----------

This program only looks at azimuth & elevation, or X and Y. It has no concept
of parallax.  For parallax-corrected mosaics, see marsortho.

For perspective corrected mosaics use marsmos or marsmcauley.

History
-------
  1994-04-30 jjl - Initial mpfmap by J Lorre. 
  1998-11    rgd - Multimission conversion by B. Deen
  2010-01    rgd - Added overlap support for brt corr (replacing old marsint)
  2012-11-07 rgd - Added experimental sinusoidal projection
  2013-04-02 rgd - Added support for HSI space overlaps
  2015-07-13 rgd - Added OMP-based parallelization
  2016-11-30 rgd - Added IDX and ICM output files
  2019-10-17 wlb - Initialized some variables; cleaned up some -Wall warnings
  2020-03-26 rgd - Added scale bar support
  2020-04-30 wlb - Replaced sprintf calls
  2020-05-05 youlu - Added -zenith_scaled_rad capabilities
                     Added DNSCALE_IN, DNSCALE_OUT, and TAU parameters
  2020-06-10 rgd - Added -reverse

COGNIZANT PROGRAMMER:  Bob Deen

PARAMETERS: