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

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.

HISTORY:
4-30-94  Initial mcauley by J Lorre. 
Sep. 98  Multimission conversion by B. Deen
Feb 2011 Major revision for untilt, ring control, remove site frame - B. Deen
Apr. 17  Revised to allow color imagery to be processed with a single call - J. Ryan

COGNIZANT PROGRAMMER:  Bob Deen

PARAMETERS: