Help for ADESPIKE

PURPOSE:

ADESPIKE will detect and remove single-pixel errors (spikes).  A pixel
is determined to be in error if it differs from its adjacent neighbors
by more than certain specifiable thresholds.  Pixel errors are replaced
by the average of adjacent pixels.

ADESPIKE was originally developed to remove random telemetry transmission
errors (bit-errors) from flight images.  However, the algorithm is
completely general and can be applied to any image containing random noise
affecting individual pixels.  Independent tests are applied in the horizontal
and vertical directions.  Consequently, ADESPIKE can also detect and remove
lines or columns one pixel in width which deviate significantly from
neighboring lines or columns (e.g. line drop-outs).

EXECUTION:

         ADESPIKE  INP  OUT  user-parameters...
where
    INP is the input image (byte or halfword).
    OUT is the output image.
The input image may be of arbitrary size.  The output image will be the
same data format as the input.

OPERATION:
  Let x0 be the DN value of a given pixel, and let x1, x2, x3, and x4 be
the DN values of its neighbors:

                          x3
                       x1 x0 x2
                          x4

A horizontal test is first applied by comparing x0 with x1 and x2.  If x0
fails this test, it is replaced by the average of x1 and x2 and processing
continues (however, see BITS and DN parameters below).  Otherwise a vertical
test is applied by comparing x0 with x3 and x4.  If x0 fails this test, it
is replaced by the average of x3 and x4 and processing continues.  Otherwise
x0 is accepted as a valid pixel.

The horizontal test is as follows:  Let avg=(x1+x2)/2.  Then x0 is in error
if:
                 x0 < A     or   B < x0
where
       A = min(avg-SLTOL, x1-DSLTOL, x2-DSLTOL)
       B = max(avg+SUTOL, x1+DSUTOL, x2+DSUTOL)
The thresholds SLTOL, SUTOL, DSLTOL, and DSUTOL are specifiable parameters.

The vertical test is as follows:  Let avg=(x3+x4)/2.  Then x0 is in error
if:
                 x0 < C     or   D < x0
where
       C = min(avg-CLTOL, x3-DCLTOL, x4-DCLTOL)
       D = max(avg+CUTOL, x3+DCUTOL, x4+DCUTOL)
The thresholds CLTOL, CUTOL, DCLTOL, and DCUTOL are specifiable parameters.

ADESPIKE processes the pixels in the same order as they are stored in the
input file.  I.e., the image lines are processed in ascending order, and
the pixels for a given line are processed in ascending sample order.  Note
that when a pixel is corrected, the corrected value is used when testing
and replacing adjacent pixels (to the immediate right and below).

The pixel replacement value may be modified via the BITS or DN parameters.
Specifying BITS=n (where n is a positive integer) specifies that only the
n most-significant-bits of error-pixels are to be replaced.  For example,
BITS=3 specifies that the 3 most-significant-bits of x0 are to
be replaced, while the 5 least-significant-bits (assuming byte data)
remain unchanged.  If BITS=0 is specified, then the appropriate number
of bits to replace is automatically determined from the specified
thresholds.  The default (BITS=-1) is to replace all bits.

Specifying DN=m causes all error-pixels to be replaced by m.

BINARY LABEL SUPPORT

References:  1) "Tracking GLL SSI Bad-Data Values, Binary Label Design"
  G. Yagi, MSD:384-89-152, May 22, 1989.
             2) "Tracking GLL SSI Bad-Data Values, Software Requirements"
  G. Yagi, MSD:384-89-157, June 30, 1989.

If the input image contains binary labels (Ref. 1), then ADESPIKE will copy
the binary labels to the output file and add information regarding all spikes
that it has identified and removed. If the binary labels contain information
regarding data drop-outs, ADESPIKE will use this information to avoid using
data drop-outs in the detection and interpolation process.

TIMING:

The following times were measured for an 800x800 byte image:
    5.8 CPU sec on 8650
    32.5 CPU sec on 780

WRITTEN BY: P. L. Jepsen	12 March 74
CONVERTED TO VAX BY: L. W. Kamp,  12 April 1983
COGNIZANT PROGRAMMER: Gary Yagi
REVISIONS:
 21 JUL 95  A. Scop      (CRI) As per FR87387 misspelled variable INU
                         corrected to IUN in XVTRANS call.
 16 MAR 95  A. Scop      (CRI) updated tst pdf as per FR85748.  Tst pdf
                         presently can't run on ANDES because galsos not
                         ported to ANDES because sybase is not present.
  1 JUL 94  M. Cox       (CRI) Made portable for UNIX
  6 APR 93  H. Mortensen Initialize LASTPIX buffer with nso and not 0.
                         Added printing of tolerance values. Zeroed out
                         bdv_rec after each XVWRIT. Added call to DUMP_BDV
          	         from the subroutine AUTSAR and fixed branching to 
                         to the subroutine DUMP_BDV call in the subroutine 
                         HUTSAR.
 21 Aug 91  W.P. Lee     Modified Test PDF for REDR processing 
 28 Mar 91  W.P. Lee     Enabled ADESPIKE to work on BYTE image with BINARY
                         Labels retained and updated 
 15 Oct 90  L.W.Kamp     Fixed bug in end-of-line test in AUTSAR;  removed
			 U_FORMAT=HALF for binary labels & added byte buffer
			 to WORKB.
 30 Aug 89  A. Runkle	 Read, copy and generate binary label information.
			 Ignore data drop-outs when enumerated in binary label.
 15 Feb 89  G. Yagi	 Major revisions to help file.
			 Fixed minor bug in BITS parameter.
			 Fixed processing of second line.
 31 May 85  L. Kamp	 Conversion to Vicar2; added STACKA
  7 MAY 85  B. Barkan	 ASSEMBLERIZED PART OF CODE
 10 JAN 84  C. Avis	 BUG FIXED FOR FR
 12 APR 83  L. Kamp	 CONVERT TO VAX: REMOVE BAL CODE (USE UCL AUTSAR)
		         MOVE PARAM CALL BEFORE OPEN CALL
		         READ BYTE DATA AS HALFWORD
 12 MAR 80  G. Yagi      REWRITE TO SPEED UP EXECUTION
 27 JUN 75  DAH		 CHANGES FOR CONVERSION TO 360/OS
 16 MAR 74               MVM73 MODIFICATIONS
 12 MAR 74   ...VIKING LANDER VERSION...   INITIAL RELEASE