Help for MULTOVLY

PURPOSE:

  multovly performs image overlay to produce a table of DN-combination 
counts vs. DN-combinations (a histogram of DN-combinations) in sorted
order in an IBIS interface file format.  In TALLY mode one of the images
can have its pixels summed instead of histogrammed.


EXECUTION:

Examples

multovly  INP = (A,B,C)  OUT = OUT  SIZE = (50,50,150,250)  NCOL = 4          DATA = (1,2,3)  AREA = 4  BYTES = (1,2,2)  ZEROES = (1,2)

  In this example, MULTOVLY will overlay three images (A, B, and C); the first
is a byte image while the other two are halfword images.  The table of DN-
combinations will be compiled only for the window listed in SIZE.  Pixel
combinations with a zero value in the first or second column will be included.
The possible pixels combinations will be listed in columns one through three,
while the number of times each combination occured will be in column four.  

  Only the input images and the output file must be specified; all of the
other parameters will default sensibly.

multovly  (A,B,C,D)  OUT

  In this example, the four images (A,B,C, and D) will be overlayed.  The
number of columns in the output file will be five with the pixel combinations
listed in columns one through four and the number of counts in column five.
The window size will be taken from the size of the first image, and the pixel
type from the format of each image.  Zero values in any image will cause that
pixel combination to be ignored.


multovly (POLYGONS.IMG,DATA.IMG) SUM.INT  'TALLY  SUMCOL=3 AREACOL=2

This example shows the use of the TALLY mode.  When 'TALLY is specified
the last input file is the summed file.  For each unique pixel combination
in the other input images, a sum is made of the pixels in the sum image.  Thus
in this case, for each polygon in the paint image POLYGONS.IMG the pixels
in DATA.IMG will be summed up.  The sum and the number of pixels for each 
unique pixel combination go into SUMCOL and AREACOL columns in the interface
file.  The default columns are, for n input images, column n for the sum column
and column n+1 for the area column.  All of the other parameters refer only
to the first n-1 images (the ones actually being overlayed).


  NCOL can be greater than the actual number of columns of data output: the
rest of the columns will be filled with zeros.
 
  There can be up to ten input images and each image can have byte, halfword,
or fullword (4 bytes) pixels.  There is a limit, however, of 20 bytes to the
total combined width of the pixels in all of the images.  For example, one
could have ten halfword images or five fullword images, but not ten fullword
images.  The BYTES parameter can be less than the actual pixel size, in which
case only the lower bytes of the pixel will be used.  For example, BYTES could
be 3 for a full word image if all of the values were less than 16,777,215
(the largest number that fits into 3 bytes).



OPERATION:

  MULTOVLY uses a hash table method of storing the DN-combinations and the
histogram of counts.  The hash method is only practical if the table is in
internal memory.  Thus if the table is too long for the core memory the
hashing is done in stages, and the parts are merged together and stored in
virtual memory on disk.



RESTRICTIONS:
  The maximum number of entries in the output interface file (i.e. the maximum
number of unique combinations) allowed is 1,000,000 or 3,000,000/KEYLEN, which
ever is smaller. (KEYLEN is the total combined width, in bytes, of the pixels).
MULTOVLY will often allow more than this number of entries, but this is the
maximum number that can always be counted on.
  The length of the lines in all of the input images must be less than or
equal to 40000 bytes (i.e. 40000 samples in a byte image, 20000 samples in
a halfword image, and 10000 samples in a fullword image.)

WRITTEN BY: 		F. Evans  April 1985
COGNIZANT PROGRAMMER:  	F. Evans
DOCUMENATION AUTHOR:  	F. Evans
REVISION:  C  		F. Evans  January 1986

PROGRAM HISTORY:
Sep 11 2014 wlb Initialized most variables in subroutine main

PARAMETERS: