Help for MARSUNLINEARIZE

PURPOSE:

Very hacky program, help needs writing.

Converts a linearized Disparity (DIL) into an equivalent unlinearized
disparity (DIS).  Only 2-band disparity files are supported at the moment.
This happens by back-projecting the pixels from the linear into the raw
camera model (the inverse of marscahv), and then taking the pixel *value*,
and back-projecting that through the right-side (non-reference) camera models
in the same way.  Thus both the left (geometric) and right (pixel value)
coordinates get transformed.

See rgd for questions.

Based on marscahv.

Always use -nointerp and point=cm=label with this program.


THE REST OF THIS HELP IS BOGUS AND APPLIES TO THE SOURCE MARSCAHV PROGRAM!
Needs to be fixed up....  rgd 2006-10-07

--

To convert images from distorted (CAHVOR/CAHVORE) to linear (CAHV) coordinates.

This is a multimission program derived from marsmos.
It supports any mission, instrument, and camera model supported by the
Planetary Image Geometry (Pig) software suite.

The program can accept a navigation file written by marsnav(for example).
This will cause the output camera model to include the updated pointing,
but in most cases will have no effect on the output pixels. Only CAHVORE
input images using a surface model other than the default SPHERE may show
differences in pixels due to the presence of a nav file.

Radiometric correction is turned off by default; this may be turned on via 
the RAD keyword parameter.

EXECUTION:

marscahv inp=input.img out=output.img
where input.img is a VICAR file and output.img is the resulting VICAR
output file.

marscahv inp=left.img out=output.img stereo_partner=right.img
If stereo_partner is not present, the program tries to find stereo partner
of the input image based on mission, instrument etc. info of the input image.
The presence of stereo_partner input parameter is an unconditional overwrite of
that process.
Note that for a generic camera, there is absolutely no way to tell what the
stereo partner might be, or even if there is one.  Thus using stereo_partner
input parameter is the ONLY way to specify stereo pair for generic image.

marscahv inp=sub.img out=output.img fullsize='('1024, 1024')'
The presence of the fullsize input parameter tells marscahv that the input
image is the subframe and the full frame size is specified by "fullsize".  
This parameter is only necessary if the camera model specified in subframe is
for a full frame image.
Note that for MER this parameter is not necessary, since every subframe has
it's own camera model, specific to it's size and location within full frame.


USAGE:
The purpose of marscahv is to remove geometric distortion inherent in the 
camera instruments, or "linearize" image data. This is usually necessary to 
facilitate correlation process, to line up stereo pair for viewing etc.

In order to linearize an image, the 2D image coordinate must be projected
into 3D space using the non-linear model, then projected back into 2D space
using the linear model(and interpolated from there).  For CAHVOR-based 
cameras(MER:pancam, navcam, MI), this process creates a linearized(CAHV-based)
image which is mathematically perfect according to the camera models(with 
the exception of interpolation noise). It is perfect since any point in 
CAHVOR image along the 3D projected line will back-project to the same point
on the CAHV image since they both project through the same C point. 
For CAHVORE-based cameras(MER: hazcams), however, that is not the case.  The
moving entrance pupil means that the program has to pick a specific point
along the projected ray, and which point is picked will make a difference in
the output.
The only way to pick that specific point is to use some kind of 
"surface model".  For example, sphere, picking the point at some radius
(default is 1unit = 1 meter) from the camera center.  So, depending on what
surface model program uses, the linearization process will provide different
results, and will always be an approximation.  The only "exact" solution is
to model the actual surface.  But we generate approximation of the actual 
surface using linearized images obtained by marscahv, thus we don't have
actual surface.
For MER hazcams, the entrance pupil moves only about 1mm over the usable
range of hazcams, which is not very much.  And, the effect decreases toward 
the center of the image, becoming 0 at the axis.  But, since the ground is
only ~0.5 meters away at the closest point, the "moving entrance pupil" effect
could be noticeable.

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.


OPERATION:
The program uses the appropriate camera model for input image and
outputs an image using a camera model 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
   by default a unit sphere(not exactly, see notes below) with the center 
   at unit vector's origin.
Note that in CAHVORE case the process doesn't actually project the rays out
to a sphere.  It projects them from the ray's origin which could not coinside
with the location of C-vector.  As a result, we are actually projecting onto a
sort of ovoid-shaped surface, slightly elongated in the direction the entrance
pupil moves.
3. Then this ground point is ray traced back into the input camera images.
4. The DN value in the selected input image is bilinearly interpolated
   and placed into the output location

HISTORY:
  1994-04-30 J Lorre - Initial mpfmos, mpfcahv
  1998-08    B. Deen - Multimission conversion of mpfmos to marsmos
  2002-09    O. Pariser - Adaptation to marscahv
  2017-08-15 W. Bunch - Removed DEBUG from imake

COGNIZANT PROGRAMMER:  O. Pariser

PARAMETERS: