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, In order for this software to correctly generate
        geometric backplane information such as latitude and
        longitude, a proper SPICE kernels list must be provided.
        An example of such a kernels list is contained in the
        file $caldir/calib/example_kernels.def. This file should
        be placed in the $ISISCSSDATA directory and be named
        S##_kernels.def.  That is, if the tour sequence is 11,
        the file 'S11_kernels.def' must be placed in the above
        mentioned directory.  Picking the proper kernel files
        to include in this list is left as an exercise for the
        reader.