Help for BLEMGEN

PURPOSE:

   BLEMGEN is a radiometric calibration program which automatically
identifies camera blemishes and generates a Blemish File.  The Blemish
File is a required input to program GALSOS which radiometrically corrects
the flight image data.  The blemishes may be displayed via program BLEMPIC.

   BLEMGEN is specific to CCD cameras with a linear light-transfer function
and is currently used for the Galileo SSI and Cassini ISS.

References: 

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

D-tbd   Software Design Document for Instrument Calibration -
        Cassini ISS, C. Avis.

EXECUTION STATEMENT:

    BLEMGEN INP=(CAL,SAT,ERR,RMS,DC) OUT=BLEM user-parameters...  

The input files are generated by the radiometric calibration program GALGEN,
and consist of statistical data measuring the linearity at each pixel:

    CAL is the Radiometric File containing the slope terms of the linear
	light-transfer function (REAL*4).
    SAT contains the saturation DN for each low-full-well-pixel (16-bit data).
    ERR contains the maximum absolute difference (in DN) between sample
	points and the fitted line (16-bit data).
    RMS contains the rms error (in DN) from the linear fit (16-bit data).
    DC  is the Dark-Current File containing the offset terms of the linear
	light-transfer function (16-bit data).

These input files are images the same size as that output by the
camera (depends upon summation mode).  Note that if the slope model is
used in GALGEN, then a raw dark-current file or a PICSUM of multiple
dark-current files may be used in place of DC.

The output (BLEM) is a Blemish File containing the (line,sample) location,
classification number, and (for low-full-well pixels) saturation DN of
each identified blemish (16-bit integer).

OPERATION:

The output Blemish File (BLEM) defines each blemish as a vector of the form
(LINE,SAMP,CLASS,SATDN), where LINE and SAMP are the picture coordinates
where the blemish occurs, SATDN is the DN value at which the pixel saturates
at full-well, and CLASS describes the interpolation algorithm to be used to
remove the blemish. The vectors are sorted first on LINE, then on SAMP.

Two types of blemishes are stored in the Blemish File: 1) permanent blemishes
and 2) low-full-well pixels.  Low-full-well pixels are treated as blemishes
only when the DN value exceeds the full-well capacity of the pixel.  Per-
manent blemishes are identified by vectors with SAT=0.  If SAT>0, then the
vector represents a low-full-well pixel.

BLEMISH IDENTIFICATION:

A permanent blemish is any pixel which has one of the following character-
istics:

    o  a light-transfer function whose slope or offset is excessively
       high or low.

    o  a lower-than-average full-well.

    o  light-transfer function nonlinearities greater than specified
       thresholds.

Blemishes are identified by applying user-specified thresholds to the
slope, offset, saturation DN, maximum error, and rms associated with
each pixel of the CCD (see parameters MINSLOPE,MAXSLOPE,MINDC,MAXDC,
MINSAT,MAXERR, and MAXRMS) as follows:

    1) Let z and dc represent the slope and offset terms of the inverse
       light-transfer function
		e = z(d-dc)
       as extracted from input files CAL and DC, respectively.  Then
       z and dc are acceptable if:
		MINSLOPE < z < MAXSLOPE
       and
		   MINDC < dc < MAXDC
       Otherwise, the pixel is identified as a permanent blemish.

    2) Let SATDN be the DN value at which full-well is reached, as
       extracted from the input file SAT.  Then if
		   SATDN < MINSAT
       the pixel is identified as a permanent blemish.  Else if
		   SATDN < 32767
       the pixel is identified as a low-full-well pixel.

    3) Let EMAX represent the maximum absolute difference between the
       light-transfer data points and the fitted curve, as extracted
       from the input file ERR.  Then if
		    EMAX > MAXERR
       the pixel is identified as a permanent blemish.

    4) Let ERMS represent the rms error resulting from the fit, as
       extracted from the input file RMS.  Then if
		    ERMS > MAXRMS
       the pixel is identified as a permanent blemish.

BLEMISH CLASSIFICATION:

The blemish classification is used by GALSOS (GLL) and DECAL (CAS) to 
determine the interpolation algorithm to use in removing the blemishes.  
Blemishes are classified according to which of the surrounding pixels are 
good and hence available for interpolation.  In order to limit the possible 
number of permutations, the surrounding pixels are paired, leaving four 
pairs. If we represent the blemish as a B, and each pair as a number 1-4, 
then we have the following diagram:

                        1   2   3

                        4   B   4

                        3   2   1
  
The  four  least significant bits in the CLASS halfword represent each of
these pairs in order, such that CLASS = 15 would mean to use all 4 pairs,
CLASS = 5 would mean to use pairs 3 and 1, etc.  This results in a range
of values for CLASS from 0-15.  If CLASS=0, then no neighboring pixels
are available for interpolation (i.e. it is surrounded by other blemishes
or the edges of the image.)

The classification scheme is extended to include double-column blemishes
B of the form:

	1 b b 3			 1 b b 3
	2 B b 2		or	 2 b B 2
	3 b b 1			 3 b b 1

where the b represent neighboring blemishes.  The resulting CLASS is
represented in binary as 10xxx and 11xxx for the right and left double-
column blemishes, respectively, where the x's are 1 or 0 depending on the
presence or absence of good pixels at the corresponding locations.  This
results in a range of values for CLASS from 17-23 and 25-31.

All blemishes of CLASS=0 (termed unclassified blemishes) are set equal to
0 by GALSOS or DECAL.  If a blemish lies on one of the edges of the image, 
it is assigned CLASS=0.

Note that this blemish classification scheme is oriented towards the
removal of single pixel blemishes.  The only extended blemishes treated
are line blemishes a single pixel in width, or column blemishes no more
that two pixels in width.

If the keyword BC is specified, then the blemish class is replaced by a
code which indicates which blemish criteria was used in flagging each
blemish:

	1 = slope term out of range
	2 = offset term out of range
	3 = unused
	4 = pixel saturation level exceeds MINSAT
	5 = maximum error exceeds MAXERR
	6 = rms error exceeds MAXRMS  
	7 = low-full-well pixel

The criteria tests are performed in series and a pixel will not be
tested after it fails one test.  The tests are performed in the 
following order (using the above criteria numbers):

            2, 6, 5, 4, 1, 7

WARNING: The BC keyword should be used for diagnostic purposes only.
The resulting output is NOT a valid blemish file.

BLEMGEN prints out the following statistical data:

	1) Mean and standard deviation of slope and offset coefficients
	   for all good pixels (i.e. excluding blemishes).
	2) Number of permanent blemishes.
	3) Number of low-full-well-pixels.
	4) Number of unclassified blemishes.
	5) Number of double column blemishes.
	6) Total number of blemishes (=permanent blemishes+low-full-well
	   pixels).
	7) Histogram of DN values at which low-full-well pixels saturate.
	8) The number of pixels failing each criteria

Note that if isolated unclassified blemishes exist away from the edges of
the image there is a problem.  To display the blemishes, see BLEMPIC.

EXAMPLE:
  galgen INP=(D0,D1,D2,D3,...,Dn)	     !Input light-transfer sequence
    OFFSETS=OFFSETS.DAT +		     !Input Shutter-Offset File
    OUT=(CAL,SAT,ERR,RMS,DC) +		     !Output files
    EXPO=(0,133.22,200,266.67,400,533.33) +  !Commanded exposure times (in msec)
    GAIN=100 +				     !Camera gain-state
    LC=3.54      ERROR=(0,20) SKIP=4

  blemgen INP=(CAL,SAT,ERR,RMS,DC + 	      !GALGEN outputs input to BLEMGEN
    OUT=BLEM +				      !Output blemish file
    MINSLOPE=0.13 MAXSLOPE=18.2 +	      !Limits on slope terms (CAL)
    MINDC=3 MAXDC=95 +			      !Limits on dark-current (DC)
    MINSAT=15 MAXERR=9 MAXRMS=5               !Limits on SAT, ERR, and RMS

  In this example, GALGEN and BLEMGEN are run to generate a Radiometric File
  (CAL), Dark-Current File (DC), and Blemish File (BLEM).  These files,
  together with the Shutter-Offset File (OFFSETS.DAT) are required as inputs
  to GALSOS, which radiometrically corrects Galileo flight images:

  galsos A1 OUT CAL=CAL DC=DC BLEM=BLEM OFFSETS=OFFSETS.DAT      IOF=10000. HPER=0.5

HISTORY:

 ORIGINAL PROGRAMMER: Dan Stanfill, Nov 85
 CURRENT COGNIZANT PROGRAMMER: Gary Yagi
 REVISIONS:
  1986-08-14 G. Yagi - Added BC parameter
  1987-05-20 G. Yagi - Compute sigmas in double precision
  1987-12-12 G. Yagi - Interface to new Radiometric File format
  1988-04-28 G. Yagi - Minor changes to help file
  1988-10-18 G. Yagi - Add test in call to PHIST
  1989-09-22 G. Yagi - Switch codes for bad slope and offset
  1989-10-12 G. Yagi - Fix double-column blemish routine
  1989-10-13 G. Yagi - Fix processing of column 2
  1990-04-01 G. Yagi - Delete spurious messages in BC mode
  1994-08-26 C. Avis - Made input buffers 1024 for Cassini
  1994-10-10 J. Turner(CRI) - Made portable for UNIX
  1995-01-08 J. Yoshimizu - Added UNITS
  1997-07-28 S. Pohorsky - Merged Cassini calibration version into MIPS.
                           Per Charlie Avis, changed Cassini units to
                           picoamp-milliseconds.  (Note this changes the
                           default units in preparation for Cassini.  This
                           is minor; only affects the 'Energy units =' 
                           message.)
  2019-08-22 W. Bunch - IDS-7922 - Cleaned up a bunch of -Wall warnings.

PARAMETERS: