Help for MARSINVERTER

PURPOSE:
To reverse the 12->8 bit compression in an image file by shifting or processing
it through an Inverse Look-Up Table (ILUT).

This is a multimission program.  It supports any mission, instrument,
and camera model supported by the Planetary Image Geometry (Pig) software
suite and its associated Radiometry models (mars_radiometry).

Images are often compressed in dynamic range via a 12->8 bit conversion.
This conversion takes one of two forms:  bit shifting, which simply shifts
the bits some specified amount, and a Look-Up Table (LUT), which can implement
nonlinear conversions.  This program recovers the original DN values (or
at least approximations thereof) by reversing this scaling.

EXECUTION:

The inputs and outputs may be presented in two ways:
1) Normal file parameters, e.g. inp=(a.img,b.img,c.img...)
2) A file list, e.g. inp=filelist.txt

The file list is a simple ASCII text file containing one filename per line.

If only one value is given for the INP or OUT parameter, it is assumed that
the value is the name of a file list file.  However, if the file appears to
be a VICAR image, or if it doesn't exist (OUT only), then it is treated as
an actual image name.  This means that you can simply correct a single image:

marsinverter inp=a.img out=a.out

without having to create file lists.

The number of input filenames must match the number of output filenames, but
it is okay if one is a file list and the other is directly entered in the
parameter.  Up to 20 images can be inverted in a single call.

OPERATION:

The program looks for inverse LUT files in the calibration directories,
as specified by the CONFIG_PATH parameter.  It looks for files of the
form:

	ilut/<host_id>_.txt

where host_id is the name of the mission (e.g. MER1, MER2, MSL) and lut_name
is the name of the lookup table as specified in the label.

The lookup table itself is simply a text file with (nominally) 256 lines.
Each line contains the 8-bit value followed by the expanded value, separated
by spaces.

A few of the LUT names are special cases, with the ILUT generated
programmatically.  The name "NONE" is a no-op (no conversion is done).
The names "MSB_BIT7" through "MSB_BIT15" indicate a bit shift, shifing
0 to 8 bits respectively to create a 12-bit output.

The output is normally expected to be 12 bits, but the program will support
any number of bits up to 16 using the BITS parameter (in reality this just
affects the SAMPLE_BIT_MASK label; the actual size of the outputs is controlled
by the ILUT file itself).  However, if the ORIGINAL_SAMPLE_BITS label exists
(in INSTRUMENT_STATE_PARMS), that value will be used as the default for BITS
(the parameter will still override).

Although normally used for 8->12 bit expansion, in reality the program is
more flexible, accepting anything that will fit in a (signed) integer for
both input and output.  The ILUT file can contain more or less than 256
entries.  However, the bit-shift special modes assume 8->12.

HISTORY:

	Jan 2004	Initial merinverter, Hyun Lee
	Oct 2010	Complete rewrite as marsinverter, Bob Deen

COGNIZANT PROGRAMMER:  Bob Deen

PARAMETERS: