Help for PICSUM

PURPOSE:

PICSUM will add up to 30 byte or halfword images together. The input samples
may be optionally screened for high and/or low noise spikes.  PICSUM was
originally written to support Galileo camera calibration.  

The option to do a median filter instead of a summation is also supported.

Reference: D-4264  MIPL Software Structural Design for the Instrument
 Calibration of GLL SSI Science Processing.

EXECUTION:

    PICSUM  (I1,I2,I3,...,In)  OUT  user-parameters...

The input images may be byte or halfword format.  The output image is in
halfword format.

All input images must be the same size and format.  The product of the number
of samples on each line (NS) and the number of input images (NI) must be
less than 32768.  For example, if 30 images are input, then the number of
samples must be less than 1092.

For Cassini images, camera, gain, mode, expos, filt1, and filt2 must be the
same for all images.

The input images can be given using a SRCH list (LIST).  However, you must
give one (and only one) file with INP if you use LIST.  That one file should
be the first image listed in your SRCH list.  That one file given with INP
is used only for its VICAR label which will be used for the output image (OUT).

DESPIKE ALGORITHM:

The despike algorithm is invoked by specifying the TSCALE parameter.  The
algorithm identifies noise spikes (e.g. transmission or radiation noise).

For a given pixel location, the DN value from each input image is retrieved and
the median DN value determined (Note that when only two images are input, the
median is always the lower DN).  The DN values from each image is then
compared with the median and all pixels differing from the median by more
than a low and high threshold are rejected.  Also, any input sample less than
or equal to 0 DN is rejected as invalid (assumed to be a data drop-out).

For a given pixel, low and high thresholds are computed as follows:
	LTHRESH = lscale*SQRT(median)/SQRT(C)
	HTHRESH = hscale*SQRT(median)/SQRT(C)
where C is the camera system gain constant in electrons/DN and lscale and
hscale are specified via the TSCALE parameter.  For Galileo images, the system
gain constant is 42.3 for 10K gain-state, 203.0 for 40K, 414.9 for 100K, and
1991.9 for 400K.  For Cassini images, the system gain constant is 42.3 for 24K 
gain-state, 203.0 for 100K, 414.9 for 400K, and 1991.9 for 1400K. 

(**NOTE THIS WILL CHANGE ONCE THE ACTUAL VALUES ARE DETERMINED)

For non-Galileo and non_Cassini images, the system gain constant is assumed
to be 1.0.

The computed thresholds (LTHRESH and HTHRESH) are not allowed to be smaller
than a minimum threshold, as specified by the MINT parameter.  If defaulted,
MINT is assigned the following values:  1 DN for 400K gain-state, 1 DN for
100K, 1 DN for 40K, and 2 DN for 10K.  For non-Galileo and non_Cassini images,
the default is MINT=3.

(**NOTE THIS MAY CHANGE FOR CASSINI)

After all bad samples are eliminated, the remaining samples are summed and the
result scaled appropriately to compensate for the discarded samples.  If all
samples are bad (only true if all data is less than 1 DN) then 0 DN is stored.

OUTPUT PICTURE SCALE

If the ASCALE keyword is specified, the output pixels will be scaled by
the factor 128/N, where N is the number of input frames.

If the output DN value at any sample position exceeds 32767, then it is set
equal to 32767.

The output picture scale (either N or 128/N) and number of input frames
are recorded in the output picture label (label items PICSCALE and NFRAMES).

If the input are Cassini images, SCLKS is also put in the output VICAR
label.  SCLKS are sorted and listed in ascending order.

EXAMPLES

1) PICSUM  (IN1,IN2,IN3,IN4,IN5)  OUT  TSCALE=(3.,3.)

   Five input images are added together to form the output image.  If all
   the input images are in byte format, the despike algorithm is invoked.
   The specified TSCALE values will cause any sample differing from the
   median by more than a 3 sigma shot-noise level to be ignored.

   Suppose that for a given pixel location, the input sample values are
   9,10,12,12,13.  The median is 12.  The computed low and high thresholds
   are 2.  The sample value 9 is discarded and the resulting sum is 47.
   This sum is multiplied by 5/4 to account for the discarded sample.

2) PICSUM IN1 OUT LIST=SRCH.LIST

where SRCH.LIST looks like

NEXT FILE = 00001
IN1
IN2
IN3
IN4


PROGRAM HISTORY

ORIGINAL PROGRAMMER: Gary Yagi, circa 1982
CURRENT COGNIZANT PROGRAMMER: Lucas Kamp
HISTORY:
  14 Feb 2011 LWK/HBM added median filter option
  06 June  97 TXH Ported from VAX to Unix and VAX/VMS to support Cassini
  15 May   96 CCA Added first estimate of Cassini gain ratios
  08 Dec   94 JRY Change the despike range from 0:255 to 0:4095 for Cassini.
  12 July  94 JRY For Cassini images, sclks put in VICAR label and LIST added
  28 April 94 JRY Modified to work with Cassini images
  28 April 91 GMY Make despike threshold gain-state dependent
  06 April 91 GMY Add despike algorithm
  04 Nov   87 GMY Added ASCALE parameter
  16 Jan   87 GMY Code and documentation clean-up
  25 SEPT  84 MEM CONVERSION TO VICAR*2
  16 MARCH 84 MEM CONVERSION TO VAX/VICAR-1
           82 GMY INITIAL VERSION