Help for MARSMOS

PURPOSE:
To assemble multiple frames into a mosaic, using an output camera model
(derived from the input).  Thus the output will appear as though it was
taken by a similar camera with a much wider field of view.
Stereo pair mosaics will be rotated with epipolar lines coinciding with
picture lines, making them easy to view.  However, this means that spacecraft
tilt will be maintained, meaning that for pan/tilt lander cameras, the
horizon will not be level if the spacecraft is not level.

This is a multimission program derived from Mars Pathfinder's mpfmos.
It supports any 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 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.

The program will work with color images if such are given as input and the
BAND parameter is not specified; 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 (so you can mix bw and
color images).  If BANDS is specified, only that one single band is
processed and output.

EXECUTION:
There are two ways to present input images:
 
marsmos inp=(a.img,b.img,c.img,...) out=mos.img
or
marsmos inp=ascii_listoffiles out=mos.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
marsmos inp=ascii_listoffiles out=mos.img navtable=navtab

USAGE:
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.

This mosaic program compensates for parallax and for lander 
translation and rotation.

OPERATION:
The program uses the appropriate camera model for each input image and
outputs a mosaic using a camera model derived from the first input (aligned
for stereo viewing).  Each pixel in the output is transformed from output
to input camera models in the following steps:
1. Each output pixel defines a unit vector.
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).

ALTERNATE POINTING:

Normally, marsmos "points" the output camera based on the first input.  Thus
the camera is related to that input.  This can be overridden via the
OUTPOS and AZOUT/ELOUT/TWIST parameters.  However, this gives somwhat
limited control and can lead to strange results in some cases.

The ALT_* parameters provide an alternate pointing mechanism.  Rather than
specifying pointing via az/el/twist, the camera is directly moved to the
specified position (ALT_POS) and orientation (ALT_QUAT or ALT_AXIS and
ALT_ANGLE).  This provides more control, but should be used cautiously
as the pose depends on how the camera was calibrated - you are moving
the camera from the current C point and identity quat directly to the
specified pose.  So it is ignoring the calibration quaternion.

If any alternate pointing is used, set -USE_ALT_POINT.  It is not
required that ALT_POS be set.  If a pos is not given, the camera C point is
used.  A quaternion (either via ALT_QUAT or ALT_AXIS/ALT_ANGLE) is required.

The use case for alternate pointing is the M20 PIXL trapezoid correction.
It may or may not be useful in other contexts.


HISTORY:
  1994-04-30 J Lorre - Initial mpfmos
  1998-08    B. Deen - Multimission conversion
  2017-03-15 mjl,rgd - Added color support
  2020-05-01 wlb - Replaced sprintfs, initialized vars, removed unused vars.
  2020-05-05 youlu - Added -zenith_scaled_rad capabilities
                     Added DNSCALE_IN, DNSCALE_OUT, and TAU parameters
  2020-11-17 E. Sarkissian - Added ICM_OUT and IDX_OUT parameters
  2021-08-06 rgd	Added ALT_* parameters

COGNIZANT PROGRAMMER:  Bob Deen

PARAMETERS: