PDS_VERSION_ID          = PDS3
LABEL_REVISION_NOTE     = "2004-10-1, Initial"
RECORD_TYPE             = STREAM
OBJECT                  = TEXT
PUBLICATION_DATE        = 2004-08-30
NOTE                    = "
        caldoc.txt describes the VIMS calibration pipeline."
END_OBJECT              = TEXT
END

NOTICE, This software requires the use of:
  IDL (Interactive Data Language from RSI)
    http://rsinc.com/
  ISIS (Integrated Software for Imagers and Spectrometers from the USGS)
    http://isis.astrogeology.usgs.gov/Isis2/isis-bin/isis.cgi
  C compiler
    http://gcc.gnu.org/

NOTICE, This software has been tested on Linux only, 
        but should work on any unix based system.
        However, you may have to debug the C code if not
        installed on Linux.

Note:  This software uses a single IDL routine.  There is a ".sav"
       file for this routine in the "bin" directory.  If the user
       has an incompatible version of IDL, this .sav file won't work.
       To make a new .sav file start IDL and do the following in
       the software/src/idl directory:
           IDL> .compile make_dark
           IDL> resolve_all
           IDL> save, /routines, filename="make_dark.sav"
       Then copy or move "make_dark.sav" to the software/bin directory.

The VIMS calibration requires the user to set an environmental variable
called "caldir" (in unix or linux).  This variable should be set to the
root directory of the CD or DVD, that is, THIS file, "caldoc.txt" would
be found in $caldir/software/doc.

The VIMS calibration pipeline takes a command file for its single input.
The pipeline software acts on all raw VIMS images found in the directory
specified, usually the current directory, so the calibration process would be:
  1. make a new directory
  2. copy the files to be calibrated to that directory
  3. enter the directory
  4. create an appropriate command file for the calibration needed
  5. type the command "vims_cal_pipe.pl cal_instruct"

"cal_instruct" is a command file for the pipeline and contains a
series of keyword=value pairs.

In general, each step in the calibration process is listed and various
values are available at each step.

A typical "cal_instruct" file might look like this:

files                = .
descend              = no
mark_saturated       = yes
vis_background       = no
ir_background        = auto
vis_flat_field       = yes
ir_flat_field        = yes
to_specific_energy   = yes
to_I_over_F          = yes
times_pi             = yes
splitcubes           = no
backplanes           = no
keepcomposite        = yes


The options to the calibration pipeline (currently) are:

files:
  The directory in which to find the files to be calibrated.

descend
  Decend into all subdirectories and calibrate all files found there.

mark_saturated:
  Mark pixels in the raw data (after adding the
  background values back to the data) whose values
  are 4095 or higher as 'saturated'.  These pixels
  have their values set to the IEEE standard value for
  CORE_HIGH_INSTR_SATURATION, which is -32765 for
  16 bit integers.  This value changes when the core values
  change to 32 bit real numbers during processing.

vis_flat_field:
  Apply the current VIS flat field (vis_flatfield.qub)

ir_flat_field:
  Apply the current IR flat field (ir_flatfield.qub)

vis_background:
  Currently, we do not use the automated VIS channel
  background subtraction.  New VIS background values are
  generated every month or so from dark sky data.  This
  must always be set to yes if further calibration steps
  are to be applied.

ir_background:
  Currently this is either "auto" or "fix".  "auto" means to
  do nothing, the background has been automatically subtracted.
  "fix" means to add the background back to the data, do a linear
  fit to the background values for each band, and subtract this
  fit from the data.  This helps eliminate the "banding" that was
  seen, particularly, in the Icy Moon data.

to_specific_energy:
  Multiply VIS and IR by instrument performance model in photons/DN,
  (ir_perf.qub, vis_perf.qub), divide by the exposure time in seconds,
  and multiply by wavecal.qub which contains:

             (h*c)
  ---------------------------
  (lambda*A*omega*delta_lambda)

  where lambda is the wavelength in microns, A is the area of the
  primary mirror in square centimeters, omega is the solid angle
  subtended by a pixel in steradians, and delta_lambda is width of
  the spectel. This gives specific energy.

to_I_over_F:
  Divide by solar spectrum scaled to distance from sun:

   I             specific_energy
   -  =  -------------------------------
   F      solar_spectrum * (R_zero/R)^2

  The solar_spectrum is contained in "solar.qub", R_zero is one AU,
  and R is the distance from the sun for the observation.

times_pi:
  Multiply result by PI (This is an optional factor usually included)

splitcubes:
  Make separate VIS and IR cubes with geometric backplanes

backplanes:
  Make separate geometric cubes for VIS and IR.  These cubes only
  contain geometric information, no data.

keepcomposite:
  Keep the calibrated composite (VIS and IR) calibrated cube.

NOTICE REGARDING THE GENERATION OF GEOMETRIC BACKPLANES
--------------------------------------------------------
In order for this software to correctly generate
geometric backplane information such as latitude and
longitude, two things must be present for ISIS to 
function. 

First, a user-generated SPICE kernels list must 
be created. An example of such a kernels list is 
contained in the file $caldir/calib/example_kernels.def. 
The kernels list should be named S##_kernels.def.  That is, 
if the tour sequence is 11, the file should be named 
'S11_kernels.def'. Picking the proper kernel files to 
include in this list is left as an exercise for the reader.

Secondly, the unit vector files, contained on this
volume in the /calib directory, are also needed when doing 
geometric calibration of VIMS cubes.

The unit vector files are:
IR_NORMAL_uv.bin
IR_HI-RES_uv.bin
IR_UNDER_uv.bin
VIS_NORMAL_uv.bin
VIS_HI-RES_uv.bin

Both the SPICE kernels list and the unit vector files must
be placed in the $ISIS/CSSDATA directory of the user's ISIS 2
installation. 


NOTE ON THE USE OF UNIT VECTOR FILES
-------------------------------------

The unit vector files contained herein are placeholders 
for files that will contain unit vectors used to correct geometric 
distortions in VIMS cubes.

In each file, there is information for each pixel in a VIMS cube
giving its spatial offset from its position if there were no 
geometric distortion.  The current files contain zero offsets 
for all pixels.  At the writing of this text in Sept 2009 
the distortion matrix giving the correct offset informaion has 
not been calculated for either VIMS instrument, IR or VIS.  
However, the perl routine in the calibration pipeline, "isis_geo.pm",
which calls "levinit", "levgeoplane", and "lev1stats", requires 
these files to be in the "/cssdata" directory of the ISIS 2 
installation.
