vikcal Documentation

vikcal - Radiometric correction of VIKING Planetary images

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


VIKCAL performs radiometric corrections to planetary images acquired by
the Viking orbiter cameras. VIKCAL performs a radiometric correction in
two steps. First, VIKCAL 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.  VIKCAL 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.  VIKCAL performs an additive, multiplicative, 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 reference,

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

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). The output of VIKCAL is
               defined as the ratio of the observed radiance and
               the radiance of a white screen, normal to the incident
               rays of the Sun.
     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 (milliseconds)
     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 of Mars
               from the Sun.
     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
     OFFT    = Time dependent residual dark current value
     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)+OFFT+OFF)

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

VIKCAL 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 VIKCAL
                    --------------------------------------

      SPACECRAFT_NUMBER   -    Number of spacecraft (1 or 2)
      IMAGE_NUMBER        -    Image identifier (FSC for Viking)
      INSTRUMENT_ID       -    Viking:  4  = Spacecraft 1, camera B
                                        6  = Spacecraft 2, camera B
                                        7  = Spacecraft 1, camera A
                                        8  = Spacecraft 2, camera A
      EXPOSURE_TIME   -    Exposure time of camera
      FILTER_NAME     -    Camera filter position:
                                    1=blue,  2=-blue,  3=violet,4=clear
                                    5=green, 6=red
      NO_CAMERA_STATE -    Number of camera states (always 3)
      CAMERA_STATE_1  -    Light flood condition of camera
                                  (0=light flood off, 1=light flood on)
      CAMERA_STATE_2  -    Camera gain state
                                    (1=high gain, 0=low gain)
      CAMERA_STATE_3  -    DC offset condition
                                    (1=offset on, 0=offset off)
      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
			   SUN_VECTOR keyword does not exist, then the
			   value in the $ISISVIKDATA/vikcal.sav file
                           is used.

After obtaining the image keywords from the image label area, VIKCAL
opens three files: $ISISVIKDATA/vikcal.sav, $ISISVIKDATA/vikoff.sav, and
$ISISVIKDATA/viklin.sav.  The vikcal.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
vikoff.sav file contains a table which provides the time dependent
offset condition (OFFT) for an image. The spacecraft clock count (FSC)
is used to determine the offset correction value.  The viklin.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
VIKCAL cannot find a match in $ISISVIKDATA/vikcal.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 VIKCAL opens the appropriate
calibration files and processes the image.

NOTES ON TAE INPUT PARAMETERS
-----------------------------
Most of the TAE input parameters can be left as default parameters for
VIKCAL.  The only TAE parameters required by VIKCAL 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 vikcal.sav, viklin.sav, and vikoff.sav
files, or can replace keyword values found in the image labels.  For
most applications, program SPICELAB should always be run prior to VIKCAL
to insure the correct keywords exist in the image labels.


Programmer:  Tracie Sucharski, U.S.G.S., Flagstaff, AZ

Input cube file name
 (Default extension is .cub)

NONE

Output cube file name
 (Default extension is .cub)

NONE

Dark current file

--

Time dependent offset

--

Optional exposure time

--

Value added to exposure time

--

Optional omega naught

--

Optional distance of
planet from Sun
(Units are millions of
kilometers)

--

Optional gain state value

--

Optional camera state
offset condition constant

--

Linearizer option(Yes, No)

YES

Linearizer coefficient

--

Linearizer normalization

--

Power of linearizer

--

Optional spacecraft #

--

Optional IMAGE_NUMBER

--

Optional camera ID

--

Optional filter number

--

Optional 1st camera state

--

Optional 2nd camera state

--

Optional 3rd camera state

--

Optional 4th camera state

--

Indicates a saturation
flag on output is to be
set if the input values
are saturated. (Yes/No)

NO

Flag for storing
average albedo values of
viking orbiter images
(Yes/No)

YES

Directory where vikspot.kep
will be located

--

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. If the file extension is omitted, then ".cub" will be assumed. The result will be the radiometrically corrected image.
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 $ISISVIKDATA/vikcal.sav file. If the DCFILE specified by the user is an 8-bit or 16-bit image then the file is assumed to be an actual 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.
OFFT	Time dependent offset correction value. The offset of the camera changes with time. This value is ADDED to the image. If the default values of NULL is used, this value is extracted from the vikoff.sav file. When specified, this parameter will overide the value in vikoff.sav. This parameter contains 5 values: OFFT(1) = offset correction value of principal point 5 OFFT(2) = (principal point 1 - principal point 5) OFFT(3) = (principal point 3 - principal point 5) OFFT(4) = (principal point 7 - principal point 5) OFFT(5) = (principal point 9 - principal point 5) The values OFFT(2) to OFFT(5) are used to modify the low frequency shape of the dark current if desired. They contain the difference between principal point N and principal point 5, where N=1,3,7,9). If used, these will override the values in $ISISVIKDATA/vikoff.sav.
LINEAR	Flag to indicate if LINEARIZER option is desired. LINEAR=YES (default) indicates linear correction to be applied if there is an entry in the viklin.sav file for the mission and camera to be processed. LINEAR=NO indicates that no linear correction is to be applied.
B	Linearity coefficient (For more information look at equations in HELP VIKCAL). This value usually left zero because this value is obtained from viklin.sav file. Supply this value only to override the viklin.sav value for B.
K	Power of linearity correction (for more information look at the equations in the main help section (HELP *) ). If this parameter is left as the default, NULL, this value will be obtained from viklin.sav file. Supply this value only to override the viklin.sav value for K.
LINORM	Linearity normalization coefficient. (for more information look at the equations in the main help section (HELP *) ). If this parameter is left at the default, NULL, LINORM will be obtained from viklin.sav file. Supply this value only to override the viklin.sav value for LINORM.
EXP	Exposure overide value. User can optionally enter the exposure time of the image. If this parameter is left at the default, NULL, VIKCAL 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 is left at the default to indicate that exposure corrections are to be obtained from the vikcal.sav file.
W0	Omega naught overide value. User can optionally enter this value. VIKCAL normally extracts W0 from the vikcal.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 SC_SUN_POSITION_VECTOR keyword.
GAIN	Camera gain state override value. VIKCAL normally extracts GAIN from the vikcal.sav file.
OFF	Offset condition override value. OFF specifies the camera state offset condition value applied. VIKCAL normally extracts this information from the vikcal.sav file.
SPNUM	Spacecraft number. This parameter is normally extracted from the keyword area on the image labels. If the keyword SPACECRAFT_NUMBER 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 IMAGE_NUMBER 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 INSTRUMENT_ID 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.
STATE4	4th camera state. This parameter is normally extracted from the keyword area on the image labels. If the keyword CAMERA_STATE_4 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 SAT_FLAG=YES then the output file will contain the ISIS special pixel, HRS, wherever the input values are saturated (254 or 255). Use this flag at your own risk!
SPT_FLAG	This is a YES or NO flag for storing mean albedo values corresponding to IRTM (Infrared Thermal Mapper) fields of view and 24 image areas. These values are stored in a data file for use in calibration, photometric-function solutions, and correlation with IRTM . IF SPT_FLAG = YES, then the file vikspot.kep is updated by VIKCAL. Note: This file is not used in VIKCAL, but in later programs to correct photometric errors.
SPOTDIR	This indicates the directory location where the vikspot.kep file will be located. If the default of NULL is used, the file will be put in the user's current directory.
OTYPE	Output pixel data type. Permitted values are: NULL = 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) When processed data are being written back into the input file, the output pixel type must be the same as the existing pixel type in the input file.
ORANGE	Output pixel data range. If ORANGE is NULL, then the CORE_BASE and CORE_MULTIPLIER in the output file will be set to represent the same range of data as the input file. If OTYPE=1 (8-bit) or OTYPE=2 (16-bit), then the CORE_BASE and CORE_MULTIPLIER 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 a special "representation saturation" value. The ORANGE parameter is ignored if OTYPE=3 (32-bit) since the CORE_BASE and CORE_MULTIPLIER are not applicable to floating point pixel values. **NOTE** For a more detailed explanation of ORANGE, tutor the orange.pdf.
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.