Help for MARSMCAULEY

PURPOSE:
To generate a Mcauley projection.
This is a hybrid cylindrical-perspective projection made by pointing the
output camera at the center of each vertical column of pixels, and projecting
that column only.  Each output pixel column thus represents the center column
(only) of a camera pointed in exactly that direction.  This has the advantage
of allowing stereo viewing (epipolar lines are preserved) in a panoramic
format, without the extreme distortion seen on the edges of a perspective
mosaic.  Stereo separation is maintained because the output cameras describe
a ring in space, which mimics the input camera baseline and preserves the
stereo disparity.

The purpose of this program is to make stereo panoramas.  In order to do this
without vertical disparity or distortion, spacecraft tilt must be maintained,
meaning that the horizon will not be level if the spacecraft is not level.
Basically the baseline between the eyes is horizontal in the output, meaning
that the horizon is tilted.

It is also possible to flatten the horizon via the "untilt" keyword.  This
works by rotating the ring of output cameras so they are parallel to the
horizon.  This has the effect of removing tilt without introducing vertical
disparity.   However, it is not perfect; to the extent the terrain does not
match the surface model, parallax effects will cause some distortions while
untilting.  But it works well in many cases.

Unlike previous versions of marsmcauley, only the natural instrument frame
("ROVER" for MER/MSL) can be used as a projection frame.  However, the untilt
option (or direct control via the ring_axis parameter) provides similar
functionality to the old "site frame" mosaics, while also reducing vertical
disparity.

As a result, all parameters are interpreted in the instrument ("rover") frame
except for START_AZ.  START_AZ is interpreted in the frame specfied by COORD
(defaults to SITE).  This allows the mosaic to be easily oriented in the
most common cases (e.g.  start_az=0 means North is on the edge of the image).
This is the only use of the COORD frame in this program.

The old untilt method (via point_method=untilt) is no longer supported and
should not be used.

Complete control over the ring described by the output cameras is now available
via the BASELINE, RING_AXIS, and RING_CENTER parameters.  Of these, only
BASELINE is particularly useful.  It allows the baseline between the output
cameras to be changed, which effectively changes the overall disparity.
This allows the apparent depth of the foreground to be changed without
affecting the background (contrast with DISP_PIX, which changes the
disparity a constant amount everywhere, moving everything in or out -
BASELINE changes apparent depths via a ratio, with close-in things changing
a lot and distant things very little)).  This can be used for example
to tone down the 30cm disparty of the MER pancam, which is too large for
comfortable viewing close-up.  Baseline adjustment is not perfect and can
introduce parallax distorions a la the untilt mode if the actual surface does
not match the surface model.

The others should rarely be used.  RING_AXIS is what the UNTILT parameter
actually changes, setting it appropriately based on the spacecraft tilt.  It
could be used to change the tilt in other ways.  RING_CENTER changes the
center of the ring (and also the center of RING_AXIS rotation); changes in
this are unlikely to be useful.

Note that the projection elevation and projection line apply *before* any
untilt (ring_axis) rotation.  After rotation, they are sinusoids across the
mosaic.

Marsmcauley 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 extent to which images from different
points of view work together depends in large part on how close the actual
surface is to the surface model.  Variations will introduce parallax errors,
which become extreme at very different points of view.  A perfect match of
surface to surface model (not achievable in reality) should allow combination
of images from any location.

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.

Marsmcauley 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:
 
marsmcauley inp=(a.img,b.img,c.img,...) out=mos.img
or
marsmcauley  inp=ascii_listoffiles out=mos.img

where ascii_listoffiles is a text file containing the list of filenames to
include in the mosaic, one per record.  Up to 1000 input images can be listed.

Additionally, marsnav may be used:

marsnav inp=ascii_listoffiles out=navtab ...
marsmcauley inp=ascii_listoffiles out=mos.img navtable=navtab

A new mode allows both left and right list files (or individual images) to be
provided at runtime, with a flag to select which to use.  See below for
details.

marsmcauley inp=left.lis out=left.out rinp=right.lis -left
marsmcauley inp=left.lis out=right.out rinp=right.lis -right

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

OPERATION:
The program uses the appropriate camera model for each input image and
outputs a mosaic using camera models 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 column causes the output camera model to be recomputed,
   pointing to this azimuth.
2. Each output pixel defines a unit vector.
3. 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).
4. Then this ground point is ray traced back into the input camera images.
   We take the input images in order of input.
5. The first image is selected which can see the ground point.
6. 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.

See the MSL SIS for a full writeup of how to interpret the images.

LEFT AND RIGHT IMAGE LISTS:

Historically, left and right images (to make stereo) had to be run
independently.  This required the user to obtain the geometry parameters
from the first (usually, left) run and supply them to the right run, so the
geometries would match for stereo viewing.  Needless to say, this was
difficult... and broke down entirely when dealing with disparate inputs (see
next section).

Although it can still be used in this mode, the preferred method is to supply
both left and right list files when the program is run, with a -left or -right
option saying which will actually be mosaicked.  This way, the program has
access to the entire set of files and can thus more accurately set the geometry
(this also fixes problems where the mosaic image would be shifted, often to
the right, in the output).

It is important to note that "left" and "right" here are completely arbitrary.
The -LEFT flag simply says to mosaic what's in INP, while the -RIGHT flag
says to mosaic what's in RINP.  You can in fact supply the right eye to INP
and the left eye to RINP.  There's rarely a need to do this, but it is
possible.

There's one way in which the "left" image list is special - the first item
from the left list is used to define the natural size of the output pixels.
If you wish to use the first item from the right list instead, use
-MASTER_RIGHT.  For example, when doing MSL Mastcam mosaics, the left camera
is about 1/3 the resolution of the right.  By default (with no zooming), the
output mosaic will be rendered at the left Mastcam resolution.  If you use
-MASTER_RIGHT, it will be rendered at the right Mastcam resolution.  Note that
in order to use -MASTER_RIGHT, you have to supply both lists.

DISPARATE INPUTS:

The traditional (single-list) mode of marsmcauley implicitly assumes that
the left and right eye cameras are stereo pairs - it uses the PIG library
to create the alternate-eye camera model, which is necessary for epipolar
alignment of the mosaic.  This is similar to "nominal" linearization (marscahv)
in which the stereo partner is predicted from the input.

However, that does not work if the cameras are dissimilar.  Importantly, it
also does not work for the MSL Mastcam case with focus-adjusted camera models.
This is because it is impossible to predict what the "partner"s focus will be,
so the partner model cannot be created.  (this is the same reason ACTUAL
linearization is required with focus-interpolated camera models).

This was the motivation behind adding the RINP mechanism.  With both actual
lists of input images, the output camera model can be constructed the same
way for both the left and right mosaics.  Furthermore, the entire extent of
*both* eyes is considered when laying out the geometry of the mosaic - meaning
the mosaic should no longer be cropped in nominal use.

It should be noted that the first image of each list is special; those are
the ones used to create the output camera model.  The rest of the images are
ignored for this purpose.

Even with the RINP parameter, however, there is an assumption that the
cameras share a calibration geometry.  Normally, the program throws away
pointing information for these prototype cameras, going back to the calibration
camera model, for simplicity.  But, this only works if the calibration models
share the same pointing - for example, both cameras are mast-mounted cameras.
If one is an arm camera and the other a mast camera, this assumption is
violated, and you may get strange results.  In this case, the -USE_POINTING
option can be tried.  This option causes it to use the actual pointed camera
models, rather than the calibration ones.  Note that this has not been well
tested, and may or may not work - and in any case, trying to make a stereo
mosaic from an arm and mast camera is dicey at best.  But, at least the option
is there.


HISTORY:
  1994-04-30  jjl	Initial mcauley, based on inspiration from Myche McAuley. 
  1998-09     rgd	Multimission conversion
  2011-02     rgd	Major revision for untilt, ring control, remove site frame
  2017-04     jryan	Revised to process color imagery with a single call
  2019-09-06  rgd	Added RINP et al, zoom, fixed centering
  2020-04-30  wlb       Replaced sprintf calls
  2020-05-04  youlu     Added -zenith_scaled_rad capabilities
                        Added DNSCALE_IN, DNSCALE_OUT, and TAU parameters
  2020-11-17  esarkiss  Added ICM_OUT and IDX_OUT parameters

COGNIZANT PROGRAMMER:  Bob Deen

PARAMETERS: