Help for DIFPIC

 PURPOSE:

Program DIFPIC is used to find the difference between two images.  By default
DIFPIC only diff the pixels. There are optional arguments to diff VICAR
property labels, binary headers, and line prefix as well.

 EXECUTION:

The input images may have any VICAR data format: BYTE, HALF, FULL, REAL, DOUB,
or COMP.  Both input images must have the same format.  The data format is taken
from the VICAR label of the first input file.  The optional output 
image has the same data format as the input images.  

Both input images must have the same dimensions, or, if they are of different 
sizes, the SIZE parameter must be specified.  If the images are three-dimensional,
they must be of BSQ or BIL file organization;  BIP files are not supported.
When an output file is produced, the output DN (data number) for a given line and 
sample is found by subtracting the DN from the second image from the DN from the 
first image. The resulting data numbers are then checked for being valid for the 
data type (byte, halfword, or fullword) of the image and are adjusted if invalid.  
For byte data, data numbers less than 0 are set to 0 (or are added to 256 if MOD 
is specified), and data numbers greater than 255 are set to 255. 
For halfword data, data numbers less than -32768 are set to -32768, and data numbers 
greater than 32767 are set to 32767. 
For fullword data, data numbers less than -2147483648 are set to -2147483648, and 
data numbers greater than 2147483647 are set to 2147483647. 
For formats REAL, DOUB, and COMP, no checking for floating point overflow or 
underflow is performed by the program.  Thus it is possible for DIFPIC to terminate 
with such a floating point error.  If this happens, the user can either run DIFPIC 
without on output file or divide both input images through by 1.0E5 and run DIFPIC 
on the results.
NOTE that program F2 can also be used to compare images, with somewhat greater
generality and robustness, but that program is not as simple to use and does not
give as much supplementary information as does DIFPIC.
When compare VICAR property labels, the program can optionally ignore specified
properties.
To compare binary headers and line prefixes, the program looks for FMT mapping
file to map a BLTYPE to an FMT file for line prefix or binary header. Using
the FMT file, the program finds a list of fields, which are OBJECTs in the FMT 
file, to be diff-ed for.
TAE COMMAND LINE FORMAT
      The following command line formats show the major allowable forms:
      difpic INP=(a1,a2) OUT=b SIZE=(sl,ss,nl,ns) optional parameters
      difpic INP=(a1,a2) OUT=b  SL=sl SS=ss NL=nl NS=ns optional parameters
      difpic (a1,a2) b (sl,ss,nl,ns) optional parameters
      difpic (a1,a2) b optional parameters
      difpic INP=(a1,a2) SIZE=(sl,ss,nl,ns) optional parameters
      difpic INP=(a1,a2) SL=sl SS=ss NL=nl NS=ns optional parameters
      difpic (a1,a2) (sl,ss,nl,ns) optional parameters
      difpic (a1,a2) optional parameters
      difpic INP=(a1,a2) bincmp=bincmp lprcmp=lprcmp verbose=verbose
      difpic INP=(a1,a2) lblcmp=lblcmp ignore_lbls="PRODUCT_CREATION_TIME" verbose=verbose

       Here 'a1' and 'a2' represent the input image file names, and
       'b' represents the output image file name.
EXAMPLES

1.    difpic INP=(A1,A2) OUT=B 'MOD 

      In this example the difference between the byte images A1 and A2 is
      written to the output file B.  Where the DN for image A1 is greater
      than the DN for image A2, the arithmetic difference is less than 0.
      The output DN is determined by taking the arithmetic difference modulo
      256.

2.    difpic INP=(A1,A2) 

      In this example the number of differences (pixels) between the 
      images A1 and A2 is printed and no output file is produced.
STATISTICS
Statistics on the number of differences are displayed by default.  Fuller 
statistics are produced if an output file is specified.  

Some of the statistics are average values for the differences found by DIFPIC.
These are computed in floating point and may involve numerous additions and 
thus may result in slightly different values on different computers.

The value displayed for AVE VAL OF DIFFS includes all pixels: those with 
positive, negative or zero differences.  This is a floating point value based 
on the real differences between the pixels and not on the value of the output 
pixel, which might be coerced to the numeric limits for the data type of the 
pixel.
 PRECISION: 
  When an output file is specified, DIFPIC computes the average difference
as well as the average positive and negative differences.  These are computed
in a straightforward way, adding up the differences and then dividing by the
number of differences.  (These computations are intended to be fast but not
necessarily highly precise.)  To accommodate the large differences that are
possible in the worst cases, the adding up takes place in single precision
floating point for all data formats except for BYTE and DOUBLE.  If there are a
large number of differences, this can result in a large number of floating
point operations and in some cases can result in a noticeable amount of
round-off error.  The test procedure contains such a case.  Thus the precision
of the average differences is not guaranteed.  In normal use the variation in 
these values that can be expected on different MIPS-supported machines should
not differ by more than 1 in six significant digits.  In contrast, the NUMBER
OF DIFFERENCES is a precise integer value.
RESTRICTIONS
1. The input files must both have the same data format. 
2. The maximum number of bytes per line is 200000.
3. BIP file organization is not supported.

 Ported to UNIX by:      Steve Pohorsky               4 Apr 1992

 COGNIZANT PROGRAMMER:   Lucas Kamp

 REVISIONS:
  1991-12    SP PORTED TO RUN ON BOTH UNIX AND VMS.
  1992-09    SP Made buffer size 200000 bytes. Modified to handle 
                all data formats.  CHANGED AVE VALS TO DISPLAY AS FLOAT.
                CORRECTED "AVE DN OF PIX" TO "AVE VAL OF DIFFS"
  1993-03    SP Modified to not use -2147483648 to work around Sun compiler.
                Added ability to handle 3D files if SIZE field defaulted
                and no output file specified.
  1994-07    SP Allowed format="WORD" as alternative to HALF.
  2003-08    lwk removed restrictions on NB, added SB parameter
  2003-11    lwk added checks on size/format of input files
  2011-09    rrp converted difpic to be a regular subroutine and not
                 a VICAR main44 subroutine. Modified the subroutine
		 to accept open input file unit numbers (instead of
		 opening the input files in the subroutine) and a return
		 status to indicate 0 if no differences are found or
		 1 if there are differences. Modiffed DPFPIC* subroutines
		 to return a status value as indicated above. Added new
		 parameters to this pdf for controlling the comparison of
		 labels, binary header, line prefix, for ignoring
		 label items and binary header fields, and the name of the
		 binary header fmt file and line prefix fmt files.
  2020-04-23 WLB Raised MAXBYTESPAR from 300000 to 500000.
  2021-03-09 WLB Fixed logic bug preventing identification of missing values.

PARAMETERS: