coyote: CGOTSU_THRESHOLD

Description
The purpose of this function is to find an optimal threshold for separating
a bimodal distribution of pixels in an image histogram. The algorithm used is the
"faster approach" algorithm explained 
`on this web page `.
.. image:: cgotsu_threshold.png
Categories
Utility
Returns
The optimal threshold that separates two populations of pixels is returned.
Params
data: in, required, 
   The data from which the histogram is created.
Keywords
binsize: in, optional
   The binsize of the histogram. By default, Scott's Choice of bin size for histograms is used::
       binsize = (3.5 * StdDev(data)) / N_Elements(data)^(0.3333)
   unless the data is byte type. Then a BINSIZE of 1 is used by default
   If BINSIZE in not defined, and NBINS is defined, the BINSIZE is calcuated as::
        binsize = (Max(dataToHistogram) - Min(dataToHistogram)) / (NBINS -1)
   While it is pointed out in the HISTOGRAM documentation, it is extremely
   important that the BINSIZE be of the same data type as the data you are going to
   calculate the histogram of. If it is not VERY strange things can happen. I've
   tried to protect you from most of the bad things, but I don't have a high confidence
   level that I have done it for every situation. If you see something that "just don't
   look right", I would check first to see if your data types match. That might solve
   all your problems.
example: in, optional, type=boolean, default=0
   Set this keyword if you wish to use the example data from the 
   `reference documentation `.
histdata: out, optional
   The output value of the internal HISTOGRAM command.
l64: in, optional, type=boolean, default=0                       
   If set, the return value of HISTOGRAM are 64-bit integers, rather than
   the default 32-bit integers. Set by default for data types greater than or
   equal to 12.
locations: out, optional
   Starting locations of each bin. (See the HISTOGRAM documentation for details.)
max: in, optional
   The maximum value to use in calculating input histogram. Equivalent to the MAX keyword
   in the HISTOGRAM documentation.
min: in, optional
   The minimum value to use in calculating input histogram. Equivalent to the MIN keyword
   in the HISTOGRAM documentation.
missing: in, optional
   The value that should be represented as "missing" and not used in the histogram.
   Be aware that if the input data is not of type "float" or "double" that the input
   data will be converted to floating point prior to calculating the histogram.
nan: in, optional, type=boolean, default=0   
   If set, ignore NAN values in calculating and plotting histogram.
nbins: in, optional, type=integer
   The number of output bins in the histogram. Meaning is slightly different from
   meaning in the HISTOGRAM command. Used only to calculate BINSIZE when BINSIZE is
   not specified. In this case, binsize = rangeofData/(nbins-1).
omax: out, optional
   The maximum output value used to construct the histogram. (See HISTOGRAM documentation.)
omin: out, optional
   The minimum output value used to construct the histogram. (See HISTOGRAM documentation.)
plotit: in, optional, type=boolean, default=0
   If this keyword is set, a histogram of the data is plotted along with a plot of the
   between class variance to show the selected threshold.
reverse_indices: out, optional
   The list of reverse indices returned from the HISTOGRAM command. (See HISTOGRAM documentation.)
Examples
Set the `Example` keyword to use the data from the reference page.
Author
FANNING SOFTWARE CONSULTING::
   David W. Fanning 
   1645 Sheely Drive
   Fort Collins, CO 80526 USA
   Phone: 970-221-0438
   E-mail: david@idlcoyote.com
   Coyote's Guide to IDL Programming: http://www.idlcoyote.com
History
Change History::
   Written by:  David W. Fanning, 13 November 2012, from a program named OTSU_THRESHOLD by Carl Salvaggio and
       modified by Gianguido Cianci.
   The OTSU_THRESHOLD algorithm used previously made many assumptions about the data. The algorithm used here
       has been completely rewritten to comply with the values in the reference page and to avoid making 
       assumptions about the data used to create the histogram. 21 November 2012. DWF.
   Modified to set L64 keyword if data type GE 14 (suggested by user). 22 November 2012. DWF.
   Modified the threshold value to use DIndGen instead of IndGen, which was causing incorrect
       results with integer data. 24 November 2012. DWF.
Copyright
Copyright (c) 2012, Fanning Software Consulting, Inc.