Help for HIST

PURPOSE:
HIST prints DN-frequency histograms of one or more areas of an image.

EXECUTION:
	HIST  INP=PIC  user-parameters...
where
    PIC is a VICAR image of arbitrary size.  PIC may be in byte, halfword
    (16-bit integer), fullword (32-bit integer), floating-point (REAL*4),
    double precision (REAL*8) data format.  See FORMAT keyword.

PIC should normally reside on random access storage (e.g. magnetic disk)
to avoid the possibility of tape rewinding.  The exception is for byte
or halfword data where only one area is requested (see AREA parameter).

OPERATION:

The format of the plotted histogram is specified via the MODE keyword.  Valid
values are NORMAL, WIDE, SCREEN, SPLOT, and NOHIST.  The DN axis may be plotted
vertically using 80 columns (NORMAL) or 132 columns (WIDE); or plotted
horizontally and formatted to fit on a standard 23x80 terminal screen (SCREEN).
SPLOT outputs a plot to a VT240 compatible terminal using the REGIS graphics
package.  The SCREEN mode works only on byte data, and the SPLOT mode will not
run in batch. 

The FORMAT keyword may be used to specify the data format of the input image.
If defaulted, the data format is determined from the input picture label.
Valid values are BYTE, HALF, FULL, REAL, and DOUB.

The DN-range displayed in the histogram may be specified using the LIMITS
parameter.  If defaulted, these limits are set to the minimum and maximum
DN values in the specified image area.

The number of lines (DN-levels) used to plot the output histogram is specified
by the NLINES parameter (default=256).

The 'PAUSE keyword introduces pauses every 23 lines to prevent the histogram
from scrolling off the terminal screen.

The computed mean and standard deviation of the input image may be output as
parameters which may be subsequently passed on to another program:
	LOCAL SD  TYPE=REAL		!Declare SD and AVG
	LOCAL AVG TYPE=REAL		!as local TAE variables
	HIST  PIC  SIGMA=SD  MEAN=AVG	!Compute SD and AVG
	PROG  PIC  STATS=(SD,AVG)	!Pass SD and AVG to program PROG

DESCRIPTION OF THE PRINTED HISTOGRAM

The following is an example of a histogram printed using the 132-column (WIDE)
format:

        GRAY    FREQ     CDF           10        20        30        40 . . .
                              +         +         +         +         + . . .
 < LOW LIMIT     123   0.023  *         +         +         +         + . . .
        -129    1275   0.199  **        +         +         +         + . . .
         128    5395   1.042  **********+         +         +         + . . .
         385    9440   2.517  ******************  +         +         + . . .
         642   13536   4.632  ***************************   +         + . . .
          .       .       .      .      .      .     .    .     .     .
          .       .       .      .      .      .     .    .     .     .
          .       .       .      .      .      .     .    .     .     .
        6296    1238  95.234  **        +         +         +         + . . .
 >HIGH LIMIT     935 100.000  *         +         +         +         + . . .

The histogram consists of a bar graph, where the length of the bar at each DN
level is proportional to the number of pixels at that level.  The graph is
annotated on the left with a table of the frequency and cummulative distri-
bution function (CDF) at each DN-level.  The CDF is the percent count of all
pixels up to and including the given DN-level.  If the keyword 'NOCUM is
specified, this column changes to the percent count at that DN-level.
The CDF is not reported in the NORMAL screen format.

If there are pixels outside the DN-range specified by the LIMITS parameter,
these are indicated by the <LOW LIMIT and >HIGH LIMIT entries.

If the input data format is other than BYTE, the histogram is usually
compressed before display.  This is because the DN-range is normally larger
than can be displayed in the specified number of lines (NLINES parameter).
In these cases, the frequency displayed at a given DN-level represents the
number of pixels between that DN-level and the next higher DN-level in the
display.

For WIDE mode, histograms are preceded by an information line, such as:
FREQUENCY DISTRIBUTION    SL=1  SS=1  NL=15  NS=15   LINC=  1    SINC=  1
If the SIZE field is specified, then the SL and SS values in this message
are computed relative to the subimage defined by the SIZE field.

Any zero entries in a wide or normal mode histogram are skipped in the
printout.  For wide mode, one or more consecutive zero entries is represented
by a single blank line in the histogram.  For normal mode, one or more 
consecutive zero entries is indicated by an * following the DN value
in the next line of the displayed histogram.
Examples

The following command prints out an 80-column-format histogram of input
image A:
	HIST  A 

The following command produces a line plot of the histogram using the
Regis graphics package.  It should only be run on a VT240 compatible terminal.
DN values are plotted along the x-axis, while frequencies are plotted along the
y-axis.
	HIST  A  'SPLOT

The following command will print out a histogram of the 15x15 pixel area in
the upper-left corner of image A.  The histogram will be plotted using a wide
(132 column) format:
	HIST  A  AREA=(1,1,15,15)  'WIDE

The following command will print two graphs in the narrow format using a
maximum of three hundred lines to represent the data:
	HIST  A  AREA=(1,1,15,15,100,100,10,40)  NLINES=300
Two histograms are plotted.  The first for the area (1,1,15,15) and the second
for the area (100,100,10,40).

The following command produces a histogram of image A for which only every
third sample of every second line will be read (for speed).
	HIST  A  SPIKES=3  LINC=2  SINC=3
SPIKES specifies that the 3 largest frequencies will be saturated.

PROGRAM HISTORY

WRITTEN BY:  Alan Mazer, September 1983
COGNIZANT PROGRAMMER:  Gary Yagi
REVISIONS:
     MODIFIED FOR VAX CONVERSION BY ALAN S MAZER, 23 SEPT 1983
     REVISION 1 BY ASM, FEBRUARY 7 1984 - SPEED ENHANCEMENTS
         1) REPLACED CONVERSION OF ALL INPUT DATA TO REAL-TYPE WITH
	     SEPARATE TABULATION ROUTINES FOR EACH TYPE
         2) ADDED LOOK-UP TABLE FOR BYTE-IMAGE PROCESSING
  84-10-9   LWK  converted to Vicar2, check for rounding error in sdev.
  84-10-11  LWK  for byte data, compute stats from histogram.
  84-12-13  LWK  revised treatment of BINS, LIMITS.
  85-4-17   REA  fixed bug in LINC & AREA parameters
  85-4-17   LWK  revised processing of REAL*4 data
  86-11-11  REA  modify formatting, hist collection routines, add
		       output parameters MEAN, SIGMA
  87-1-12   REA  add EXCLUDE, SCREEN parameters
  87-2-4    REA  add SPLOT, PPLOT and TITLE parameters
  87-3-2    REA  disable PPLOT (AVIRIS version)
  89-10-12  GMY  Massive changes to source code and help file.
	  	 Replaced BINS parameter with NLINES parameter.
		 Changed algorithms for collecting and compressing
		 histograms.
  90-11-7   LWK  Fixed bug in treatment of SINC with byte data
  91-2-18   GMY  Fixed case where halfword image has only one DN.
  92-10-19  SP   Made portable for UNIX.  modified to support DOUB format.
                 Corrected bug where HIST did not find MIN and MAX correctly
                 when LIMITS specified for halfword image.
  98-03-98  RRP  Fixed TAB4 to prevent division by zero when both lower and
                 upper bounds are the same in which case bandwidth equals 0.
  99-01-19  LWK  enabled for 3-D images