Help for MARSINVRANGE

PURPOSE:
MARSINVRANGE is the inverse of marsrange - it takes a range file and
recomputes an XYZ file that closely matches the original.

The purpose of this is to recompute XYZ's modified by nav/RSF files
when the right eye is unavailable.  This happens, for example, if the
image was not a stereo pair but was repointed between the left and right
eyes.  In this case, the right eye cannot be repointed based on the left
eye's nav - but it must be repointed in order to compute a revised XYZ.
This program gets around that limitation by taking the original all the
way to range, which no longer depends on the specific pointing of the
camera.  It is then inverted to find XYZ.  The range origin point is taken
from the input camera model as modified by the nav/RSF files, so the new
XYZ file incorporates those pointing adjustments.  Of course in the example
case you are relying on pointing knowledge accuracy to establish the proper
baseline, but there's no reliable way to do otherwise - nav'ing the right
side is likely to introduce more systematic errors than simply assuming the
baseline is correct.

Even when no adjustment is made, the inversion is not perfect.  That's because
of a subtlety in how XYZ's are computed.  The marsxyz program projects rays
through both cameras, and picks an XYZ point halfway between these rays at
their closest point.  The XYZ point thus does not lie exactly on the projection
ray from the left camera.  The marsinvrange program has no knowledge of what
this offset might be - it assumes the point is actually ON the projection ray.
This subtle difference is unlikely to be an issue, but it should be noted.

One other subtlety has to do with CAHVORE cameras.  For these cameras, the
projection point (commonly called C) is not constant, but varies across the
image.  Marsrange ignores this effect, projecting from a single point (the
nominal C point) across the entire image.  Because marsinvrange is supposed
to be an inverse, we follow the same convention and ignore this effect, instead
projection from the single, nominal C point.

Note that input pixels with a range of 0.0 are assumed to be missing; the
output is set to (0,0,0) for these pixels.

EXECUTION:
marsinvrange inp=range_data.img out=xyz_data.img nav=adjust.nav
where:
range_data.img is an input 1-band image of type REAL where each value is 
a distance between reference point(by default camera position) and (x,y,z) 
point.
xyz_data.img is an output 3-band image of type REAL with the X,Y and Z values
at that pixel in meters.
adjust.nav is a nav file, such as from marsnav, containing pointing adjustments
that are incorporated into the XYZ values.


METHOD:
At each pixel, marsinvrange uses the camera model (as adjusted by nav/RSF
files) to compute a view ray.  This is normalized to assure it is a unit
vector, then it is multiplied by the range value at that pixel.  The result
is added to the origin (which is by default the adjusted nominal C point
for the camera, constant across all pixels - but can be overriden via the
ORIGIN parameter).  The resulting XYZ value is converted to the output
coordinate system and written to the file.


COGNIZANT PROGRAMMER: B. Deen

HISTORY:
  2010-03-01 B. Deen - Initial marsinvrange 
  2020-04-30 W. Bunch - Replaced sprintfs and removed unused variables

PARAMETERS: