voycal Documentation

voycal - Radiometric correction of Planetary images

INTRODUCTION
------------


VOYCAL performs radiometric corrections to planetary images acquired
by the Viking orbiter and Voyager spacecraft vidicon cameras. VOYCAL
performs a radiometric correction in two steps. First, VOYCAL corrects
for the varying response of the vidicon across the field-of-view of
the camera.  Multiplicative and additive correction coefficients, as a
function of line and sample position, are applied to an image array to
produce the results of an 'ideal' camera.  Optionally, for Voyager
cameras, a non-linearity correction can be additionally applied to the
image data.  Secondly, VOYCAL converts the image data to radiance
factor values.  The radiance factor is defined as the ratio of the
observed radiance and the radiance of a white screen, normal to the
incident rays of the sun.


EQUATIONS
---------
The sensitivity of a vidicon camera varies across the field of view
of an image frame.  VOYCAL performs an additive, mutiplicative, and
non-linearity radiometric correction to an image to correct for the
varying sensitivity of the camera.  For information on the radiometric
properties of a vidicon camera, see the references;

    "Inflight Performance of the Viking Visual Imaging Subsystem"
     Klassen, Thorpe, and Morabito; Applied Optics, Vol. 16, No. 12,
     December 1977.

    "Radiometric Performance of the Voyager Cameras" Danielson,
     Kuperman, Johnson, and Soderblom; Journal of Geophysical
     Research, Vol. 86, No. A10, Pages 8683-8689, September
     30, 1981.

General equations applied to data for radiometric correction are
indicated below:

Let: i,j     = line and sample position of pixel in an image
     DI(i,j) = Result of correction.  This value is known as the
               (Radiance factor)*10000. The output of VOYCAL is
               defined as the ratio of the observed radiance and
               the radiance of a white screen, normal to the incident
               rays of the sun. DI(i,j) = 10000 for an ideal 100%
	       lambertian reflector with the sun and camera orthoganal
	       to the planet surface.
     DR(i,j) = Raw input density number
     DC(i,j) = Camera shading dark current. This is a value from a file
               which provides the additive correction.
     G(i,j)  = Camera shading gain. This is a value from a file which
               provides the multiplicative correction.
     EXP     = Exposure time (seconds)
     W0      = Sensitivity of camera with sun-distance correction at
               standard distance from the sun.  This value is equivalent
               to the density number of a one second exposure of the
               camera for the standard distance of the planet from the
               sun.
     DIST0   = Standard distance of planet.  The W0 value was determined
               for a standard planet-sun distance. For Mars, the
               standard distance is 1.63 AU, the mean distance Mars from
               the Sun.  For Voyager image data, the standard distance
               is the distance of the planet (Jupiter, Saturn, Uranus)
               at the time of the Voyager encounter.
     W1      = Sensitivity of camera with planet-sun distance
	       correction at actual distance of planet from the sun.
	       This value is equivalent to the density number of a one
	       second exposure of the camera for the planet-sun distance.
     DIST1   = actual distance of planet from the sun at time image was
               recorded
     GAIN    = Camera gain state constant
     OFF     = Camera state offset condition value

 W1 = W0*((DIST0**2)/DIST1**2))

 DI(i,j) = (1.0/(EXP*W1))*G(i,j)*(GAIN*DR(i,j)+DC(i,j)+OFF)*10000

The linearity correction to the DN values is performed before the gain
and offset correction is applied. If the linearity option is chosen, and
the voylin.sav file has a table entry for the mission camera of the
data being processed, or the user has provided TAE input for the
coefficients B,K,LINORM, then a linearity correction will be made. The
result of the linearity correction is fed into the equation shown
above.  Thus, the result of the linearity correction is called DL(i,j).
The following linearity equation is used:

      DL(i,j) = A*(DR(i,j)+DC(i,j)) + B*(((DR(i,j)+DC(i,j))/LINORM)**K)

      B = coefficient of linearity
      K = power of linearity fit (usually 4)
      LINORM = linearizer normalization (usually 128)
      A = (LINORM-B)/LINORM

PROGRAM STRATEGY
----------------

VOYCAL reads the keyword label area from the input file to obtain
various processing parameters in order to radiometrically correct a
vidicon image. The following keywords are extracted from the keyword
label area:



                    TABLE OF IMAGE KEYWORDS USED BY VOYCAL
                    --------------------------------------

      SPACECRAFT_NAME   -  Spacecraft name (VOYAGER) combined with
                           spacecraft number (ie. VOYAGER_1 or
                           VOYAGER_2)
      IMAGE_NUMBER      -  Image identifier (FDS for Voyager)
      INSTRUMENT_ID     -  WA = Camera A, Wide angle camera
                           NA = Camera B, Narrow angle camera
      CAL_TARGET_CODE   -  Planet system code:
                           (J=Jupiter, S=Saturn, U=Uranus)
      EXPOSURE_DURATION -  Exposure time of camera
      FILTER_NAME       -  Camera filter position:
                            0=clear, 1=violet, 2=blue,  3=orange,
                            5=green, 7=ultra-violet
      NO_CAMERA_STATE   -  Number of camera states (always 3)
      CAMERA_STATE_1    -  Camera scan rate (values: 1, 2, 3, 7, 10)
      CAMERA_STATE_2    -  Keyword not used in Voyager mission
      CAMERA_STATE_3    -  Gain state condition of camera
                           (always contains the number 1)
      SC_SUN_POSITION_VECTOR  - The sun vector is used to determine the
			   distance of the planet from the sun at the
			   time the image was recorded. If the
			   SC_SUN_POSITION_VECTOR keyword does not
                           exist, then the value in
                           $ISISVOYDATA/voycal.sav file is used.

After obtaining the image keywords from the image label area, VOYCAL
opens two files: $ISISVOYDATA/voycal.sav, and $ISISVOYDATA/voylin.sav.
The voycal.sav file contains a table for
determining the calibration files and parameters in the radiometric
equation for the given set of camera conditions of the image.
The voylin.sav file is a table which provides the non-linearity
parameters for a given set of camera conditions. For full details
on the information in these files, consult the documentation found
within these files.  NOTE: If VOYCAL cannot find a match in the
$ISISVOYDATA/voycal.sav for the camera state of the image, then an error
message is printed and the program terminates without performing
a radiometric correction.

After determining all processing parameters VOYCAL opens the appropriate
calibration files and then processes the image

NOTES ON TAE INPUT PARAMETERS
-----------------------------
Most of the TAE input parameters can be left as default parameters for
VOYCAL.  The only TAE parameters required by VOYCAL are the FROM and TO
parameters which indicate the input and output file names. The other
TAE parameters provide optional processing strategies, provide override
values of the values found in the voycal.sav and voylin.sav files,
or can replace keyword values found in the image labels.  For
most applications, program SPICELAB should always be run prior to VOYCAL
to insure the correct keywords exist in the image labels.



Programmer:  Tracie Sucharski

Input cube file name
 (Default extension is .cub)

NONE

Output cube file name
 (Default extension is .cub)

NONE

Dark current file
 (Optional)

" "

Optional exposure time
 (Override labels)

0.

Linearizer option
 (YES, NO)

YES

Linearizer coefficient
 (Overides voylin.sav file,
  usually defaults to 0)

0.0

Linearizer normalization
 (Overides voylin.sav file,
  usually defaults to 0)

0.0

Power of linearizer
 (Overides voylin.sav file,
  usually defaults to 0)

0

Delta exposure time.
Value added to exposure time
DEL_EXP=999 (Default) implies
obtain exposure correction from
voycal.sav file

999

Optional omega naught
 (Override voycal.sav file)

0.

Optional distance of
planet from sun
 (Units are millions of
  kilometers)
  (Override labels)

0.

Optional camera state
offset condition constant
 (Override voycal.sav file)

0.

Optional gain state value
 (Override voycal.sav file)

0.

Optional bit type normalizer
NORM=100.0  (Default 8-BIT)
NORM=10000.0(Default 16-BIT)

0.

Optional SPACECRAFT_NAME
 (Override image labels)

" "

Optional Spacecraft #
 (Override image labels)

0

Image number of image
 (Overides image labels)

0

Optional Instrument ID
 (Override image labels)

" "

Optional target code
 (Override image labels)

" "

Optional filter number
 (Override image labels)

" "

Optional 1st camera state
 (Override image labels)

" "

Optional 2nd camera state
 (Override image labels)

" "

Optional 3rd camera state
 (Override image labels)

" "

Indicates a saturation
flag on output is to be
set if the input values
are saturated (254,255)

NO

Output pixel type
 NULL = input type
    1 = 8 bit
    2 = 16 bit
    3 = 32 bit

2

Output min/max data range

0.0,1.0

User comment

" "

ADDITIONAL NOTES:

Parm	Description
FROM	Input cube file name. If the file extension is omitted, then ".cub" will be assumed.
TO	Output cube file name. The result will be the radiometrically corrected image. If the file extension is omitted, then ".cub" will be assumed.
DCFILE	This parameter allows the user to use an alternate dark current file. In most cases, this field is left blank to indicate the default dark current file is to be used. The name of the default dark current file is found in the $ISISVOYDATA/voycal.sav file. If the DCFILE specified by the user is an 8-bit image then the file is assumed to be an acutal DARK CURRENT file and the values in this file will be subtracted in order to make the correction. If the DCFILE is a 32-bit floating point file then the file is assumed to be a DARK CURRENT CORRECTION file and the values in this file will be added in order to make the correction.
LINEAR	Flag to indicate if LINEARIZER option is desired. LINEAR=Y (default) indicates linear correction to be applied if there is an entry in the voylin.sav file for the mission and camera to be processed. LINEAR=N indicates that no linear correction is to be applied
B	Linearity coefficient (for more information look at equations in HELP VOYCAL.) This value usually left zero because this value is obtained from voylin.sav file. Supply this value only to override the voylin.sav value for B.
K	Power of linearity correction (for more information look at the equations in HELP VOYCAL). This value is usually left zero because it is obtained from voylin.sav file. Supply this value only to override the voylin.sav value for K
LINORM	Linearity normalization coefficient. (for more information look at the equations in HELP VOYCAL). This value is usually left zero because it is obtained from voylin.sav file. Supply this value only to override the voylin.sav value for LINORM.
EXP	Exposure overide value. User can optionally enter the exposure time of the image. VOYCAL will normally extract the exposure time from the image labels.
DEL_EXP	Delta exposure time. Errors exist in the exposure times indicated on some image labels. This value is added to the exposure time. Normally this value left at DEL_EXP=999 to indicate that exposure corrections to be obtained from the voycal.sav file.
W0	Omega naught overide value. User can optionally enter this value. VOYCAL normally extracts W0 from the voycal.sav file.
SUN	This parameter contains the distance of the planet to the sun in astronomical units. Normally the parameter is extracted from the image labels with the SUN_VECTOR keyword.
GAIN	Camera gain state override value. VOYCAL normally extracts GAIN from the voycal.sav file.
OFF	Offset condition override value. OFF specifies the camera state offset condition value applied. VOYCAL normally extracts this information from the voycal.sav file.
NORM	Normalizing value to map data to output bit type (used for OBIT=8 or 16 only). The result of the correction (normally a number between 0.0 and 1.0) is multiplied by NORM to convert to 8 or 16-bit dynamic range. NORM will default to 100.0 for 8-bit data and 10,000.0 for 16-bit data.
SPCRAFT	Mission name. This parameter is normally extracted from the keyword area on the image labels. If the keyword MISSION= does not exist on the labels, then this value can be provided by the user.
SPNUM	Spacecraft number. This parameter is normally extracted from the keyword area on the image labels. If the keyword SPACECRAFT_NO does not exist on the labels, then this value can be provided by the user.
IMAGE_NO	This parameter contains the Spacecraft clock count, which acts at the Frame identification code. This parameter is normally extracted from the keyword area on the image labels. If the FRAME_ID does not exist on the labels, then this value can be provided by the user.
INST_ID	This parameter is the camera identification. This parameter is normally extracted from the keyword area on the image labels. IF CAMERA does not exist on the labels, then this value can be provide by the user.
FILTER	Filter number or wave length of image. This parameter is normally extracted from the keyword area on the image labels. If the keyword FILTER_NAME does not exist on the labels, then this value can be provided by the user.
STATE1	1st camera state. This parameter is normally extracted from the keyword area on the image labels. If the keyword CAMERA_STATE_1 does not exist on the labels, then this value can be provided by the user.
STATE2	2nd camera state. This parameter is normally extracted from the keyword area on the image labels. If the keyword CAMERA_STATE_2 does not exist on the labels, then this value can be provided by the user.
STATE3	3rd camera state. This parameter is normally extracted from the keyword area on the image labels. If the keyword CAMERA_STATE_3 does not exist on the labels, then this value can be provided by the user.
SAT_FLAG	The saturation flag is meant to be used only by the expert image processing analyst. This flag is normally set to NO. If the SAT_FLAG=YES then the output file will contain saturation flags (+32767) whereever the input values are saturated (254 or 255). Use this flag at your own risk!