Help for HIST

PURPOSE:
HIST prints DN-frequency histograms of one or more areas of an input data
set. It is accepts BYTE, HALF, FULL, and REAL image data types and allows 
the user to specify the maximum number of bars to be used in the graph, 
as well as the range of values which those bars represent. There are several
options available for the print format of the output. The DN axis may be
aligned vertically using 80 columns (NORMAL) or 132 columns (WIDE); or, the
DN axis can be horizontal and formatted to fit within a 23x80 screen (SCREEN).
The WINDOW and WBAR options plot to IDL windows.  If PPLOT is 
specified, the histogram is generated as a line plot on the printer. The 
SCREEN mode works only on byte data, and the WINDOW and WBAR modes will not 
run in batch. The PPLOT option and one of the other options may be run in the 
same execution.
Note that HIST does not determine the histogram limits: these must be
set by the LIMITS parameter, which defaults to (0,255) for byte, or to
(-32768,32767) for other data types. (To obtain an estimate of the DN
range in an image, use the keyword NOHIST in a preliminary run, then
run HIST again with suitable LIMITS.)
Examples

HIST A 

This command will print out an 80-column-format histogram of input image A
based on A's full area.  The histogram will be normalized such that the
first and second most frequent values are each represented by a fifty
character bar. (This is determined by the graph display format, the default
narrow format in this case, and by the default for the SPIKES option; the
wide-graph format has a different default normalization procedure which prints 
the graph so that the largest bar is 100 characters and all other bars are
proportional.  This narrow format allows the user to see in detail the size
of the shorter bars when some bars are much larger than others.  The SPIKES
option described here is described in more detail below.  The default is
SPIKES=1.) Pixel values will be distributed among a maximum of 256
(default) bars as appropriate; the default range of pixel values to accept
is 0 through 255 for byte data, and -32768 through 32767 for halfword,
real, and integer data. 
HIST A BINS=21 LIMITS=(0.0,40.0) FORMAT=HALF

This command will print out an 80-column histogram as above, but will use
21 bins, evenly spaced, with centers from 0.0 to 40.0. The width of each bin,
then, is 2.0. There are, in addition, two bins to keep track of pixels which
are outside of the specified limits. These bins are also represented by 
labeled bars on the graph.  Note that the FORMAT option was used to specify 
that the image is to be read as HALF data; the default is to read the image 
data format from the image's system label. (The allowable data types are 
BYTE, HALF, FULL, and REAL.)
HIST A 'SCREEN 'PPLOT TITLE="TRONA CLASSIFICATION RESULTS"

This command will plot the histogram of A, with DN values running horizontally
across the 80 column screen, and the populations running vertically. The 
format is set to allow viewing of the entire histogram at once. The bins are 
compressed as needed to fit on the screen, and only byte data is permitted for
the screen option. The PPLOT keyword causes a pen plot to be generated on the
printer, in addition to the screen histogram. The value of the TITLE 
parameter is put as a caption to the plot.
HIST A 'WIDE AREA=(1,1,15,15)

This command will print out another histogram of image A, this time using
the wide (132 column) format.  Only the first 15 samples of the first 15
lines of the image will be plotted on the graph. 

HIST A AREA=(1,1,15,15,100,100,10,40) BINS=300

This command will print two graphs in the narrow format, using a maximum of
three hundred bars to represent the data.  The range of the bars will be
either of two defaults: 0 through 255 if image A is in byte format, and
-32768 through 32767 if the image is in another, larger format.  Note that
the request is for two graphs of the same image.  The first graph will be
for the area (1,1,15,15) and the second will be for the area
(100,100,10,40).  If the 'WIDE option is used, these graphs will be labeled
with headers giving the area represented; the default, compact histogram
does not give this information. 
HIST A SPIKES=3 LINC=2 SINC=3

This command will produce a histogram of image A for which only every third
sample of every second line will be read.  This is done mainly to speed
output of the program.  Note that there is also an INC option which may be
set to any similar increment, in effect setting LINC and SINC to the same
value.  Again, this is done mainly to speed processing of the image.  Note,
too, the use of the SPIKES option.  As mentioned in the example above,
SPIKES specifies the bar which is to be normalized to a bar value of 50,
which is the maximum; any values larger than this value will be reduced to
50, and the graph will indicate the rank of each bar which is 50 units
long.  This option, in effect, removes any large spikes in the graph which
would otherwise dwarf smaller bars in the narrow format.  The default value
of SPIKE is one. 

PROGRAM HISTORY

WRITTEN BY:  Alan Mazer, September 1983
COGNIZANT PROGRAMMER:  Ray Bambery
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
  1984-10-9   LWK  converted to Vicar2, check for rounding error in sdev.
  1984-10-11  LWK  for byte data, compute stats from histogram.
  1984-12-13  LWK  revised treatment of BINS, LIMITS.
  1985-4-17   REA  fixed bug in LINC & AREA parameters
  1985-4-17   LWK  revised processing of REAL*4 data
  1986-11-11  REA  modify formatting, hist collection routines, add
		       output parameters MEAN, SIGMA
  1987-1-12   REA  add EXCLUDE, SCREEN parameters
  1987-2-4    REA  add SPLOT, PPLOT and TITLE parameters
  1987-8-4    REA  fix bug in x-axis scaling algorithm
  1987-10-27  REA  add 3-D file capability
  1989-8-23   REA  add BAR graph parameter
  1990-2-22   REA  add output parameters MIN, MAX
  1990-10-5   REA  add laserprinter capabilities
  1991-4-8    REA  convert to UNIX
  1992-8-6    REA  add WINDOW and WBAR options
  1996-10-25  REA  remove Regis options
  1997-8-20   REA  add BYCHAN option
  2000-7-12   REA  adjust print-out column widths for DN and population
  2001-2-16   REA  fix min/max bug when both regular and pen plots;
                   consolidate statistics logic.
  2015-08-10  WLB  replaced xqout call with xvqout call to pass out vars to shell vicar

OPERATION:
The main part of the program, MAIN44, sets up defaults and handles most of
the options requested by the user, modifying variables and setting flags. 
MAIN44 then calls subroutine WORK (through STACKA for dynamic storage
allocation). 

WORK goes through each of the areas of the image, reading the lines which
are part of the area, and sorting pixels into buckets based on the number
of buckets and their range.  The bucket width equals the difference between
the limits of the range, divided by the number of buckets minus 1. The 
variables SUM and SUM2 are updated for each pixel to be used later for the 
calculation of the mean and standard deviation.  

Finally, when the entire area has been read in, PHIST, SHIST, or PLOTXY is 
called to dislay the histogram data, and the next area for the image, if any,
is similarly processed. 

WRITTEN BY:  Alan Mazer, September 1983
COGNIZANT PROGRAMMER:  Ron Alley