Help for MARSRAD

PURPOSE:
To radiometrically correct an image, usually an EDR.

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).

The output file will have the same labels as the input, with the addition
of the radiometric correction scale factors (RADIANCE_SCALING_FACTOR and
RADIANCE_OFFSET).

Multiple images can be given to the program, in which case each is corrected
independently.  The number of outputs must match the number of inputs.

The program will work with color images if such are given as input and
the BAND parameter is not specified; the number of output bands will equal
the number of input bands.  If BANDS is specified, only that one single band
is processed and output.

NOTE: currently the SAME rad correction is applied to ALL bands.  This
should probably be fixed.

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:

marsrad inp=a.img out=a.out

without having to create file lists.

The number of input filename 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.

The default is to create a short int (HALF) format file, with radiometric
values scaled to short int using DNSCALE.  However, specifying FORMAT=REAL
will create a floating point file, in actual physical units.  Note that
DNSCALE=1.0 should be used in this case.

If BITS is specified (and FORMAT=REAL is not), then the results are clamped
to have that many bits, e.g. if BITS is 12 then the results will be in the
range 0-4095.  The sample bit mask in the label will be set appropriately.
As a backward compatibility feature, if BITS is not set then there is no
clamping but the sample bit mask is still set to 15 bits.  BITS is ignored
for floating-point files.

OPERATION:

The specific algorithm used for radiometric correction depends on the mission
type, but most are similar.

MARS PATHFINDER / MARS 98
-------------------------

The absolute radiance S of a single pixel (at a location (i,j) in an image)
is given by

S(i,j) = DN(i,j)/(t * R(lambda,temperature) * G(i,j))

where
DN(i,j) is the instrument signal (in units of DN) from the input image
G(i,j) is the normalized flat field of the camera system (which corrects
    for the pixel to pixel sensitivity variations)
t is the exposure time of the image (in seconds)
R(lambda,temperature) is the responsivity curve defined by a quadratic
    function in temperature.
temperature is the camera head temperature in degrees C.
lambda is the wavelength in nm, which is derived from the filter.

t, temperature, and filter are derived from the image label.  G depends
on the filter and eye (left or right), which are also derived from the
image label.

Flat field files are obtained via the CONFIG_PATH parameter.

The responsivity function R is embedded in the source code; refer to
mars_radiometry.com if details are required.

The dark current of the camera (i.e., the signal that does not correspond
to photons incident onto the detector) is insignificant at the low Martian
temperatures experienced by the lander cameras and is not subtracted for
the calculations presented here.  (During Mars Pathfinder surface operations,
the largest dark current of the camera (2 PM local solar time, camera
temperature = -9 degrees C) was < 2 counts/sec (less than 0.5 % in radiance
for well-exposed pixels)).

For more information, see Maki et al., 1999 (JGR).

HISTORY:
Apr. 99  Initial version
2017-03	mjl, rgd	Support for multiple bands
COGNIZANT PROGRAMMER:  Bob Deen

PARAMETERS: