Generate a two-dimensional histogram from two image bands
HISTO2 generates a two-dimensional histogram from two image bands by counting the number of occurrences of each possible pair of values. The output is a two-dimensional array, in LAS image format, with the horizontal coordinate axis (increasing column number) corresponding to increasing values of the first input band, and the vertical axis (increasing row number) corresponding to increasing values of the second input band.The histogram may be output as an image, as an ASCII file, or both, with the origin either at the top left or bottom left corner (specified by parameters OUT, ASCII, and ORIGIN). The values may be output as actual counts (SCALING=LINEAR) or as the logarithms of the counts (SCALING=LOG); for logarithmic scaling, the value assigned to zero is specified by parameter LOGZERO. The record length and field width for the ASCII file may be specified, using parameters RECLEN and FIELDSZ.
The number of bins, bin size, and starting pixel value for the first bin may optionally be specified for each band (parameters NBIN, BINSIZE, and IBIN/IVALUE).
- IN
- Image file(s) containing the two input bands.
This may specify either a single input image or a two-image input group, specified as "image1+image2". Band (spectral window) specifiers are required unless either a single two-band image or two one-band images are specified. Window specifers are also permitted.
- OUT(--)
- Name of file to receive binary image-format frequency array.
If no file name is specified, binary output is not generated.
- ODTYPE(ADAPT)
- Data type of output binary image, "WORD", "LONG", "REAL", or "ADAPT".
If linear scaling is specified (SCALING = "LINEAR"), the ADAPT option specifies that I*1, I*2 or I*4 should be used depending on the maximum frequency count. If "WORD" is specified and the maximum count for any bin exceeds the maximum integer for type WORD, type LONG will be used instead.
If logarithmic scaling is specified (SCALING = "LOG"), output type REAL is always used.
- ASCII(--)
- Name of file to receive ASCII frequency array.
Each row of the array will begin a new output record; if each row requires more than 512 bytes, the rows will be broken into mutliple records of not more than 512 bytes each.
If no filename is specified, ASCII output is not generated.
- RECLEN(512)
- Record length for ASCII output array.
The last record for each row of the array may be only partially filled. Unused space at the end of any record will be padded with blanks.
- FIELDSZ(--)
- Width of each field in ASCII output array.
Default for SCALING = "LINEAR" is 1 more than number of digits needed to print largest count; for SCALING = "LOG", 3 decimal places are included.
- NBIN(0,0)
- Dimensions of frequency table -- number of columns and rows, corresponding to first and second band, respectively.
If the band contains 8-bit data (type BYTE), the default value, 0, normally indicates that 256 bins will be used. However, if parameter IBIN is VALUE, (256 - IVALUE) bins will be used; and if IBIN is MINIMUM, the maxium and minimum pixel values will be determined, and their difference plus 1 bins will be used. If BINSIZE is not 0 or 1, the number of bins determined from IBIN and IVALUE will be divided by BINSIZE and rounded to the next higher integer.
For other data types, the default value NBIN = 0 normally indicates that 1024 bins are to be used if parameter BINSIZE has its default value, 0.0. However, for integer data types if IBIN is not "ZERO" and the entire range of data is less than 1024, the number of bins will be reduced accordingly. If a BINSIZE value greater than 0.0 is specified, the number of bins will be calcualted by subtracting the smallest value in the first bin (as defined by parameters IBIN and IVALUE) from the maximum pixel value, dividing this difference by BINSIZE, and rounding to the next higher integer. A result greater than 1024 will cause the program to abort; if this many bins is actually wanted, rerun HISTO2 with an explicit value for NBIN.
- BINSIZE(0.0,0.0)
- Size of each bin for first and second bands, respectively.
The default value, 0.0, indicates that the minimum size needed to map the data into NBIN bins is to be calculated; for integer data, the bin size value will be rounded up to an integer.
- IBIN(ZERO,ZERO)
- Specifies how the minimum pixel value in the first bin is to be defined for each band. Options are:
ZERO -- The (lowest value in the) first bin is 0. MINIMUM -- The (lowest value in the) first bin is the minimum pixel value in the band. NEGMAX -- Compare the negative of the maximum pixel value in the band with the minimum pixel value, and use whichever is more negaive as the lowest value in the first bin. This puts pixel values near zero in the center bins. VALUE -- The (lowest value in the) first bin is given by parameter OVALUE.Default is ZERO.
- IVALUE(0.0,0.0)
- Minimum value in first bin for each band, if IBIN = "VALUE".
Default is 0.0.
- ORIGIN(TOP)
- Location of histogram origin. Options are:
TOP -- Top left corner BOTTOM -- Bottom left cornerDefault is TOP.
- SCALING(LINEAR)
- Scaling to apply to frequency counts. Options are:
LINEAR -- Use actual values of frequency counts. LOG -- Use natural logarithm of frequency counts; set zero counts to the value specified by parameter LOGZERO.
- LOGZERO(--)
- Value to use as logarithm of zero (SCALING = "LOG" only).
Default is -.05 * logarithm of maximum frequency count.
Creates a two-dimensional histogram for bands 2 and 4 of image FCREEK.IMG. The output is written in LAS image format to file FC_HIST.IMG. The output values represent actual counts, with the upper left corner of the output corresponding to the pair of values (0,0).
Creates a two-dimensional histogram for band 3 of images FCREEK_MAY and FCREEK_AUG. The output is an ASCII file, using 64 bins for each band, containing the logarithms of the actual frequency counts. The bin containing the count for value pairs (0-3,0-3) is at the lower left corner (start of last line) of the output array.
If either input file is not 8-bit data (type BYTE), if parameter IBIN is MINIMUM or NEGMAX, or the sum of the parameters NBIN and IVALUE is less than 256, HISTO2 begins by checking whether the corresponding DDR file contains valid maximum and minimum data. If not, a preliminary read of the file is performed, during which its maxiumum and minimum values are determined.
HISTO then allocates space for the array as specified by parameter NBIN. If parameter BINSIZE is not defaulted, the size of each histogram bin is determined by computing the difference between the maximum pixel value and the minimum value for the first bin (as specified by parameters IBIN and IVALUE) for each band, and dividing by NBIN. For integer data, this value is rounded to the next higher interger. The input image files are then (re)opened and read one line at a time. For each pixel, the bin into which the value for each band falls is determined, and the location in the two-dimensional frequnecy table pointed to by the pair of bin indices is incremented. When all input lines have been processed, the image and/or ASCII files containing the frequency counts are created. If logarithmic scaling has been specified, the counts are first converted to their natural logarithms, using the value specified by parameter LOGZERO for zero counts.
If any pixel values were excluded because their values fell below the minimum value for the first bin or above the maximum value for the last bin in either band, HISTO2 will write a message reporting the number of excluded pixels in each category.
If the operating system (e.g. VAX/VMS) supports file version numbers, a new version of the file and its associated DDR and history files will be created.
The maximum frequency count exceeded the largest positive integer that can be expressed by data type WORD.
The input filename, window specification, or band number was not specified correctly. Check parameter syntax.
The window sizes specified for the two input images are not
the same. If the window size was not specified explicitly,
then the sizes of the full images are different -- at least
one image will require an explicit window specification.
If only one input image is specified, the image must contain at least two bands, and if it contains more than two, exactly two bands must be specified explicitly. If two input images are specified, one band must be specified for each image unless the image contains only one band.
If the operating system (e.g. unix) does not support file version
numbers, the existing version of the image, DDR, and history
files would be overwritten. Change the name output file or
rename or delete the existing versions, and then rerun
HISTO2.
An error occurred opening the input file. Check filename and directory specification, and whether user process has read access to file. If problem persists, notify system manager.
Input image has 8-bit (BYTE) data values, which are
interpreted as values between 0 and 255. A negative value
for the starting bin is not permitted.
Reenter the value(s) of parameter BINSIZE as positive numbers.
The data descriptor (.DDR) file for the input image could
not be found, was unreadable, or did not contain a record
for the input image band. Check that the band spedification
is correct (use DSPDDR to display number of bands). If .DDR
file is missing, the input image will need to be
regenerated.
The data descriptor (.DDR) file for the input image does not contain valid minimum and maximum values. Run program MINMAX to compute these values; make sure the VALID flag is set for the specified band.
The standard procedure for computing the number of bins when
NBIN is not specified explicitly has given a very large
result. Because such a large value normally indicates an
error in specifying the parameters BINSIZE, IBIN, and/or
IVALUE, processing is aborted. If this many bins are
actually wanted, use parameter NBIN to so specify.
This probably reflects a program bug or system error -- notify system manager.
This probably reflects a program bug or system error -- notify system manager.
This probably reflects a program bug or system error --
notify system manager.
The specified output file could not be opened. Check that output directory exists and that user process has write access to it. If problem persists, notify system manager.
Increase the value of parameter FILLDSZ to allow for the
maximum frequency count. If linear scaling is used, this
value must be at least one greater than the number of digits
in the maximum count. For logarithmic scaling, a field size
of 8 should be sufficient unless parameter LOGZERO has more
than two digits before the decimal point.
Check that available disk space and disk quota have not been exceeded. If error persists, notify system manager.
Check that available disk space and disk quota have not been exceeded. If error persists, notify system manager.
The Data Descriptor file associated with the output image
could not be read back in for updating. This is probably a
program bug or system error -- notify system manager.
The band-specific part of the Data Descriptor file associated with the output image could not be read back in for updating. This is probably a program bug or system error -- notify system manager.
Error occurred while writing updated DDR for output image -- notify system manager.
Error occurred while rewriting band-spsecific DDR for output
image -- notify system manager.
Error occurred while inserting minimum and maximum values of (scaled) frequency counts into DDR for output image -- notify system manager.
None.