moccal Documentation

moccal - Radiometric correction of Mars Global Surveyor MOC images
moccal performs radiometric corrections to images acquired by the Mars
Global Surveyor (MGS) MOC camera.  MOC has one Narrow Angle (NA)
detector and 2 Wide Angle (WA) detectors.  It also has two camera
systems, A and B.  The B camera system is a backup and currently has
very little or no radiometric calibration information.  It is supported
to a very limited extent but is not in use at this time.

The MGS MOC NA detector has a total of 2048 pixels.  The WA Red and WA
Blue detectors have a total of 3456 pixels.  Images from MOC may or may
not include all pixels in the acquired image.  There are special summing
modes that are utilized on-board the spacecraft to average detector
pixels to combine them into a single output pixel value.  Both NA and WA
detectors can utilize crosstrack (sample) and downtrack (line) summing
modes.  The value of these modes indicate the number of samples and
lines, respectively, that were summed and averaged to result in the
pixel values stored in the input file to moccal specified in the FROM
parameter.  These values are stored in the ISIS labels as
CROSSTRACK_SUMMING and DOWNTRACK_SUMMING, respectively.  Note that this
will reduce the number of samples in the output image by a factor of at
most the crosstrack summing mode value.  The NA is restricted to modes
of 1 through 8 for both crosstrack and downtrack summing.  Furthermore,
the crosstrack and downtrack modes must be the same.  For both WA
detectors, crosstrack and downtrack modes range from 1 to 127.  Unlike
NA, WA crosstrack and downtrack summing modes can differ.  There are two
additional special WA crosstrack summing modes.  These modes are
indicated by crosstrack summing mode values of 13 and 27.  Both of these
modes use specially configured tables to indicate the relative detector
hardware pixels involved in computing the output pixel value.  These
modes are intended to maintain approximately equal spatial resolution
from nadir to limb.  Crosstrack summing mode 13 has a resolution of
7.5 km/pixel and maximum number of output pixels of 768; mode 27 has
a resolution of 3.75 km/pixel with the maximum number of output pixels
of 384.  moccal recognizes both these modes and applies appropriate
measures to radiometrically correct them.

The MOC camera has the ability to acquire images of differing sizes in
both line and sample.  The starting hardware detector pixel for the
acquired image is specified by the ISIS label keyword,
FIRST_LINE_SAMPLE.  The first pixel in the detector is indicated by a
value of 1.  (Note that in the original PDS image products this is the
EDIT_MODE_ID keyword and is 0-based.  In ISIS, FIRST_LINE_SAMPLE is a
PDS standard and is 1 plus this value, a 1-based numbering scheme.)
Note that all corrections are applied relative to the actual hardware
pixel.

moccal has a number of parameters required to process MGS MOC image
data.  Most of these parameters are read from an ISIS parameter defaults
file located in $ISISMGSDATA.  This file has the form:

  $ISISMGSDATA/moc_parameters.def.xxx

    where "xxx" is a positive number.

moccal will search for the parameter file with the highest number and
load all its default needed to process MOC images.  Note that the
caller may explicity provide an alternative ISIS parameter defaults
file name in the "PARMFILE" input parameter if they have their own
set of defaults that applies to MOC data.  See an existing defaults
file in $ISISMGSDATA for details on how to configure this file.

The MOC response equation (without pixel-to-pixel variation terms) is as
follows:

       dn = a * (r * ex + dc * ex + g) + (z - off)

  where r is the average signal being generated at the focal
  plane (in DN/msec at minimum gain), z is the fixed zero
  offset, off is the commanded variable offset, dc is the dark
  current term (in DN/msec at minimum gain), g is the gain-
  dependant offset (in DN at minimum gain), a is the commanded
  system gain (where minimum gain is 1 and all other gains
  are > 1) and ex is the exposure time in milliseconds.

moccal computes "r" from "dn" at every pixel in the input MOC image.
Hence, the actual equation moccal implements is as follows:

       r = ((dn - z + off) / a - g) / ex - dc

Note that moccal allows the user to explicitly provide some of these
variables that would override the defaults provided in MOC calibration
documents or through refinement via empirical evaluations.  The "DC"
parameter if provided by the user will be substituted for "dc" in the
above equation.  The "GAIN" parameter will be substituted for "g" in the
equation and "OFFSET" will be substituted for "z".

The MOC WA camera has an additional capability to change the commanded
gain state (a) and offset (off) at any time during image acquistion.
The approximate time these changes are made is provided in a file called
"wago.tab".  This file can be found on all MOC CDROM products under the
"index" directory.  This table, called a "WAGO" (Wide Angle Gain Offset)
table, contains one entry per line of four fields.  All fields are
double quoted.  The first field is the WA detector for which the gain
and offset change occurs, the second is the SCLK time of the change, the
third is the hexidecimal code of the new gain mode identifier and the
fourth is the offset mode identifier.  The WA detector will be either
"RED" or "BLUE".  The SCLK is the spacecraft clock count of the time at
which the command to change gain and offset was initiated.  The gain
mode identifier indicates a gain value that is stored in a table of
gain values.  The offset mode identifier is actually specified in
factors of 5 DN.  Hence, if the commanded offset mode is "5", then "off"
in the above calibration equation is set to 25 (5 * 5 = 25).  Any number
of these WAGO changes can occur during WA image acquisition.  WAGO
changes are apparent as an abrupt change in brightness at a particular
line.  Beware, not all changes are WAGOs as this is also a
characteristic of dropped data.

moccal gets WAGO tables from files read out of the MOC parameter
defaults file.  The default WAGO configuration is to read a WAGO
index file that records WAGO table file names, the filter contained
within that table and specifies starting and ending SCLK coverage
of WAGOs in that table.  Note that the files in the index can be the
same as most WAGO tables contain entries for both filters.  Only those
WAGO tables are read and searched for the particular filter.  There
is another keyword in the parameter file that allows the user to
explicitly provide the name of a WAGO table.  This can be used instead
of or augment the existing WAGO table index.  See the parameter file
for details.

moccal has gone the distance in ensuring that (1) the same WAGO table is
not read more than once, and (2) all redundant WAGOs are removed from
the resulting search.  This is critical because should redundant WAGOs
occur, subsequent WAGO changes can be missed.  Upon reading all WAGOs
that apply to the input (FROM) image, they are sorted by time and the
line that the WAGO occurs is computed.  Only one WAGO per line is
considered and this is the first occuring WAGO in the sorted list.  All
others that occur on the same line are discarded.

As the timing knowledge of the gain-offset changes is only accurate to
1/8 of a second, and the WA line rate is somewhat faster than this and
not an even multiple of 1/8 second, the line on which the brightness
discontinuity occurs may not match precisely the line computed from the
image start time, line rate, and known time of state change.  In
addition, changes in highly-summed images (such as global map swaths)
may result in summed output lines having been created in the instrument
from unsummed input lines taken in different states.  moccal attempts to
detect lines that exhibit this signature and corrects them using a
brightness matching algorithm.  With the WA line rate at 75ms, for a
downtrack summing mode of 1, the change should occur no more than two
lines before or after the computed line of the change.  moccal looks in
this window of transition lines and applies an averaging techinque to
correct them if NULLWAGO="NO".  If NULLWAGO="YES", then these lines are
assigned the ISIS NULL value and can be handled later using alternative
processing techniques.

Additional pixel-to-pixel variations are corrected by a detector
coefficient file also specified in the parameter defaults file.  This
file has been provided after analysis of the calibration data taken
prior to and after the launch of MGS.  Certain detectors may not have
these coefficients derived and thus will not have this correction
applied.  If these files do exist, they are typically taken from the
$ISISMGSDATA directory.  The file is expected to contain any number of
comments indicated by a '#' as the first character in a line.  The
first non-blank or uncommented line must contain the number of values
(i.e., one per line) of pixel coefficients for this detector.  This
must be the exact number of pixels in the given detector, 2048 for the
MOC NA detector and 3456 for the MOC WA Red and Blue detectors.  All
non-blank, uncommented lines after the detector count expects two values
per line.  The first is a multiplicative value followed by an additive
value.  These values are applied to the value "r" computed in the above
equation to correct for individual pixel variation.  Note that some
detectors, namely WA Blue, may not have a pixel variation correction
derived.  For these cases, moccal will report it and apply the
calibration equation without pixel-to-pixel variation applied.  The user
may also provide pixel-to-pixel variation correction file of their own,
or when one becomes available or is modified for a given detector in the
parameter defaults file.  This file must adhere to the expected format
for coefficient files as described above.

The user also has the option to request the output of moccal to be in
either units of percent reflectance (CONV="YES") or in average signal
level at the focal plane (CONV="NO") in DN/msec.  moccal has a set of
default I/F (percent reflectance) factors for each detector, NA and both
WA.  Should they not have this value, a W0 of 0.0 will be detected and
I/F cannot be generated.  moccal will detect occurances of W0=0.0 and
report this to the user whilst functioning as if CONV="NO" irregardless
of what may have been provided by the user for CONV.  Note the caller
also has the ability to specify their own value for W0 as an input
parameter to moccal.  Conversion to I/F takes place after calibration
and pixel-to-pixel variation correction.

If I/F values are requested by the user, moccal requires the distance
to the sun at the time the image was acquired.  This information is
provided in a file from the value of "DISTFILE" specified in the ISIS
parameter defaults file.  This file is a table that contains two values
per line the first being the day of the year, the second being the
distance to the Sun from Mars in IAU.

Prior to MGS MOC mapping phases, MOC NA downtrack summing modes
greater than 1 was implemented differently in onboard camera software.
A software patch was made at some point prior to normal mission
mapping phase that would be used throughout the mapping and extended
phases for the rest of the mission.  moccal applies the following
algorithm for all MOC NA images:  *ALL* NA images have the exposure
times multiplied by the downtrack summing mode.  All NA images prior
to mapping phases has the recoreded GAIN mode value divided by the
downtrack summing mode and a new GAIN value is looked up in the table
that is closest to this value.  It is substituted in the calibration
equation for the commanded gain value (a).  The critical piece of
information needed for this algorithm is the time (spacecraft clock
count or SCLK) when this patch was uploaded to the spacecraft.  This
time has been determined to be just prior to the first image acquired
in the normal mapping phase.  This is image m0000001.imq and its SCLK
is 607568463:128 which corresponds to April 3, 1999, 01:00:40.4405 UTC.
None of the MOC WA images are affected by this algorithm.

Programmer:  Kris Becker, USGS, Flagstaff, AZ

References:

"MOC2 Calibration Report, October 1997 [SCCS 10/17/97 version 1.3]"

"Software Interface Specification, Narrow Angle and Wide Angle
   Standard Data Products (September 1999 (revised for MGS)
   (formatted April 7, 2000))"

Input file name

NONE

Output file name

NONE

Convert to reflectance (I/F)

"YES"

Omega naught

--

Global dark current

--

Global gain

--

Global offset
YES, or NO

--

Alternate parameter defaults
file where to get program
parameters

--

For WA images that
have WAGOs, NULL
transition lines

"NO"

Output pixel type

3

Output pixel data range

--

User comment

" "

ADDITIONAL NOTES:

Parm	Description
FROM	Specify the input file to be corrected.
TO	Specify the output file. The result will be the radiometrically corrected image. The output values can either be output as counts/ms or absolute radiance. The ouput file can be 8, 16, or 32 bit which is defined by the OTYPE parameter shown below.
CONV	Write output in reflectance (I/F) or if CONV=NO, write as counts/ms.
W0	Omega naught value in DNs/millisecond for 100% lambertian reflector at 1AU sun-target distance, gain state of 1.0 and bias of 0.0. Current defaults are contained in the MOC parameter defaults file.
DC	Dark current at the minimum gain. Current defaults are contained in the MOC parameter defaults file.
GAIN	Gain dependent offset. Current defaults are contained in the MOC parameter defaults file.
OFFSET	Fixed zero offset. Current defaults are contained in the MOC parameter defaults file.
PARMFILE	Alternative MOC parameter defaults file. moccal will look for a parameter defaults file using the file search specification of "$ISISMGSDATA/moc_parameters.def.*". It will select the file where the "*" resolves to the highest positive integer value. The user can copy this file and modify it to suit. This parameter is used to provide moccal with the MOC parameter defaults explicitly overridding the aforementioned search. See one of these parameter files for details on its contents.
NULLWAGO	This parameter is intended for WA images only and is used strictly for WA Red or Blue images that have WAGOs. The area where these WAGOs occur may have several lines that were acquired during the WAGO change. This has been observed to cause large variations in detector response. NULLWAGO when set to "NO" detects these lines and applies an averaging technique to attempt to correct them as they do contain actual data. This technique uses the average of each line to provide a baseline for expected line averages in the WAGO line transition area. If NULLWAGO is "YES", then the data is essentially discarded and the entire line is set to the ISIS NULL value rather than the averaging algorithm applied. moccal analyzes a region of five lines, the actual line computed where the WAGO change occurs and two lines above and below the actual line for expected averages. This is the WAGO line transition zone. The lines on either side of the WAGO transition zone are used to establish estimated averages of lines in this zone. The expected average for each line in the WAGO zone is interpolated using these two endpoint averages. Any average that differs more than one and half times the interpolation delta value from the expected average is deemed a bad line. If NULLWAGO is "NO", each pixel in this line is then divided by the orignal average and then multiplied by the interpolated average. This raises or lowers the DN levels to the expected average while preserving the data in the line. Otherwise all pixels in the line are set to the ISIS NULL value.
OTYPE	Output pixel data type. Permitted values are: 0 - output type is same as input file pixel type 1 - 8-bit (integer with type conversion parameters) 2 - 16-bit (integer with type conversion parameters) 3 - 32-bit (floating point)
ORANGE	Output pixel data range. If the output pixel type is 1 (8-bit integer with type conversion parameters) or 2 (16-bit integer with type conversion parameters), then the type conversion parameters in the output file will be set to values that allow representing the specified range of output values. Output values outside this range will be stored as the special "representation saturation" value. The ORANGE parameter is ignored if the output pixel type is 3 (32-bit floating point) since type conversion parameters are not applicable to floating point pixel values. If both ORANGE(1) and ORANGE(2) are 0.0, then the type conversion parameters in the output file will automatically be set to allow representing the same range of values as can be represented in the input file. (The user will be required to supply a specific range for ORANGE if the input pixel type is 3 (32-bit floating point) and the output pixel type is 1 (8-bit with type conversion parameters) or 2 (16-bit with type conversion parameters)).
USERNOTE	Comment from the user. This will be recorded in the ISIS session log file and also in the History entry that is put into the History object of the output file.