Help for MARSUNMOSAIC

PURPOSE:

This program will "unmosaic" a mosaic by extracting a single frame.
This frame will be such that it could have been an input to the mosaic.
The intent is to create simulated input frames using different cameras
and/or pointings than the original mosaic used.

Only Cylindrical projections are supported.  The parameters of the
cylindrical projection are extracted from the label.

There are two parts necessary to define the input: a camera model for the
output frame, and the pointing of that camera model.  Each of these can be
specified in multiple ways.

Radiometric correction is not reversed; what you get in the output are
the DN's in the mosaic.

Camera Model
------------

The most straightforward way to provide the camera model is to provide a
sample image (via <A HREF="marsunmosaic_level2.html#example">EXAMPLE) that is recognized by the PIG library.  For
<A HREF="marsunmosaic_level2.html#example">example, to make an image look like it came from the MER pancam, provide a
MER pancam image.  The output label will be copied from this input so it
will appear to be a complete label - although since only a few items are
updated, most of the fields will be wrong (referring still to the original
image).  The fields necessary for further use with the PIG library will be
updated.  Note that you can create a blank image with a .cahv (or .cahvor
or .cahvore) file to use this method with the PIG "generic" mission.

**** TBD:  Currently only the camera model is updated in the output label.
The pointing is NOT updated.  This means that camera-model based pointing
must be used; kinematics are unavailable.  For MER, that's specified by
point_method=cm=label to any other PIG program.

The second way is to explicitly provide the camera model numbers via
parameters.  The CAHV, CAHVOR, and CAHVORE models are supported (note
that CAHVORE also requires T and P parameters).  <A HREF="marsunmosaic_level2.html#model_type">MODEL_TYPE must be
supplied in this case.  If there is no input image, NL and NS must
also be provided (XOFF and YOFF are optional and default to NS/2
and NL/2, respectively).  The COORD parameter specifies the coordinate
system in which the <A HREF="marsunmosaic_level2.html#c">C, A, etc. vectors are expressed.

If both a file and explicit parameters are provided, the file's labels
will be transferred to the output, but the parameters will specify the
camera model.  Note that in this case, the pointing parameters in the
label will not be updated, so only label pointing can be used (i.e.
further use of that image will require the camera model be extracted from
the label; recomputation of the model from pointing is no longer available).
This mode is useful for e.g. defining a set of coordinate systems via
the <A HREF="marsunmosaic_level2.html#example">example file, yet still defining the camera model explicitly.

Camera Pointing
---------------

The pointing of the camera can be changed via the PPARAM argument, which
contains the pointing parameters needed for the pointing model in use.

The interpretation of these parameters depends on the mission.  For the
Generic mission (or if no file is given), the first two pointing parameters
are used to adjust the camera pointing directly (az, el).  For a mission
that PIG knows about, <A HREF="marsunmosaic_level2.html#normal">normal PIG pointing models are used.

For instruments that use Azimuth and Elevation as the first two pointing
parameters (which includes most mast cameras, such as MER navcam and pancam,
PHX SSI, and generic with the 2dof model), the pointing may alternatively
be specified using the AZIMUTH and ELEVATION parameters.  The key difference
here is that AZIMUTH and ELEVATION are expressed in the coordinate system
specified by COORD.  They are internally converted to the instrument coordinate
system, and then put into the first two slots of the PPARAM parameter.
This allows e.g. a MER pancam to be pointed in the Site or Local Level frame.
Note that if one of AZIMUTH or ELEVATION are specified, both must be.

If the pointing model does NOT have azimuth and elevation as the first two
pointing parameters, the results will be undefined and likely nonsensical.

Finally, if POSITION is specified, that is an absolute override of the
camera position (for CAHV models, the <A HREF="marsunmosaic_level2.html#c">C vector).  This is most useful for
Generic (or no file) models to make the cameras describe an arc to preserve
stereo separation.  While it is possible to use POSITION with a PIG pointing
model, it is not recommended.  The coordinate system in which POSITION is
expressed is defined by COORD.

Coordinates
-----------

The standard PIG COORD parameter set is used to specify the coordinate system
in which the camera model vectors, AZIMUTH and ELEVATION, and POSITION are
specified.  This need not be the same as the natural instrument coordinate
system (Rover for MER), which is used to express pointing parameters via
PPARAM.  It also need not be the same as the coordinate system in which
the mosaic was taken.  In fact, for MER it could be common to have the mosaic
in Site frame, the instrument frame be Rover, and COORD=LOCAL_LEVEL to specify
the camera pointing.

EXECUTION:

marsunmosaic cyl.img <A HREF="marsunmosaic_level2.html#out">out.img example=frame.img az=45.0 el=-3.0
or
marsunmosaic cyl.img <A HREF="marsunmosaic_level2.html#out">out.img -cahvor c=(1,2,3) a=(4,5,6) h=(7,8,9)
   v=(0,1,2) o=(3,4,5) r=(6,7,8)

OPERATION:

The program uses the appropriate camera model for the output image and
Cylindrical projection parameters from the input.
Each pixel in the output is transformed from output picture coordinates to
input azimuth and elevation in the following steps:
1. Each output pixel defines a unit vector based on the camera model of the
   output image.
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 "<A HREF="marsunmosaic_level2.html#ground">ground" can be above or below the
   origin).
3. Then this <A HREF="marsunmosaic_level2.html#ground">ground point is ray traced back into the input mosaic's
   projection origin, creating another vector.
4. This vector is decomposed into azimuth and elevation, which are then
   converted to line/sample in the cylindrically projected mosaic.
5. The DN value in the input image is bilinearly interpolated and placed
   into the output location.


HISTORY:
  1994-04-30 J Lorre - Initial mpfmap
  1998-11    B. Deen - Multimission conversion
  2005-08    marsmap algorithm inverted to become marsunmosaic
  2019-12-10 W. Bunch - Initialized some variables; cleaned up all -Wall warnings; added unit test.
  2020-05-21 W. Bunch - Replaced sprintf calls.

COGNIZANT PROGRAMMER:  Bob Deen

PARAMETERS: