
Thresholding
============

``abutaleb_threshold``
----------------------

``Image`` [OneBit] **abutaleb_threshold** (``Choice`` [dense|rle] *storage format*)


:Operates on: ``Image`` [GreyScale]
:Returns: ``Image`` [OneBit]
:Category: Thresholding
:Defined in: threshold.py
:Author: Michael Droettboom and Karl MacMillan


Creates a binary image by using the Abutaleb locally-adaptive
thresholding algorithm.

*storage_format* (optional)
  specifies the compression type for the result:

  DENSE (0)
    no compression
  RLE (1)
    run-length encoding compression

----------

**Example 1:** abutaleb_threshold()

..  image:: images/GreyScale_generic.png
   :height: 67
   :width: 96

..  image:: images/abutaleb_threshold_plugin_00.png
   :height: 67
   :width: 96



``bernsen_threshold``
---------------------

``Image`` [OneBit] **bernsen_threshold** (``Choice`` [dense|rle] *storage format*, int(1, 50) *region size* = 20, int(0, 255) *contrast limit* = 5, ``bool`` *doubt*)


:Operates on: ``Image`` [GreyScale]
:Returns: ``Image`` [OneBit]
:Category: Thresholding
:Defined in: threshold.py
:Author: Michael Droettboom and Karl MacMillan


Creates a binary image by using the Bernsen algorithm.

*storage_format*
  specifies the compression type for the result:

  DENSE (0)
    no compression
  RLE (1)
    run-length encoding compression

*region_size*
  The size of each region in which to calculate a threshold

*contrast_limit*
  The minimum amount of contrast required to threshold.

*doubt*
  When True, *doubt* is low.

----------

**Example 1:** bernsen_threshold()

..  image:: images/GreyScale_generic.png
   :height: 67
   :width: 96

..  image:: images/bernsen_threshold_plugin_00.png
   :height: 67
   :width: 96



``djvu_threshold``
------------------

``Image`` [OneBit] **djvu_threshold** (float(0.00, 1.00) *smoothness* = 0.20, int *max_block_size* = 512, int *min_block_size* = 64, int(1, 8) *block_factor* = 2)


:Operates on: ``Image`` [RGB]
:Returns: ``Image`` [OneBit]
:Category: Thresholding
:Defined in: threshold.py
:Author: Michael Droettboom and Karl MacMillan


Creates a binary image by using the DjVu thresholding algorithm.

See Section 5.1 in:

  Bottou, L., P. Haffner, P. G. Howard, P. Simard, Y. Bengio and
  Y. LeCun.  1998.  High Quality Document Image Compression with
  DjVu.  AT&T Labs, Lincroft, NJ.

  http://research.microsoft.com/~patrice/PDF/jei.pdf

This implementation features an additional extension to the
algorithm described above.  Once the background and foreground
colors are determined for each block, the image is thresholded by
interpolating the foreground and background colors between the
blocks.  This prevents "blockiness" along boundaries of strong
color change.

*smoothness*
  The amount of effect that parent blocks have on their children
  blocks.  Higher values will result in more smoothness between
  blocks.  Expressed as a percentage between 0.0 and 1.0.

*max_block_size*
  The size of the largest block to determine a threshold.

*min_block_size*
  The size of the smallest block to determine a threshold.

*block_factor*
  The number of child blocks (in each direction) per parent block.
  For instance, a *block_factor* of 2 results in 4 children per
  parent.

----------

**Example 1:** djvu_threshold(0.5, 512, 64, 2)

..  image:: images/RGB_generic.png
   :height: 129
   :width: 227

..  image:: images/djvu_threshold_plugin_00.png
   :height: 129
   :width: 227



``otsu_find_threshold``
-----------------------

int **otsu_find_threshold** ()


:Operates on: ``Image`` [GreyScale]
:Returns: int
:Category: Thresholding
:Defined in: threshold.py
:Author: Michael Droettboom and Karl MacMillan


Finds a threshold point using the Otsu algorithm. Reference:

N. Otsu: *A Threshold Selection Method from Grey-Level
Histograms.* IEEE Transactions on Systems, Man, and Cybernetics
(9), pp. 62-66 (1979)

----------

**Example 1:** otsu_find_threshold()

..  image:: images/GreyScale_generic.png
   :height: 67
   :width: 96

*result* = 143



``otsu_threshold``
------------------

``Image`` [OneBit] **otsu_threshold** (``Choice`` [dense|rle] *storage format*)


:Operates on: ``Image`` [GreyScale]
:Returns: ``Image`` [OneBit]
:Category: Thresholding
:Defined in: threshold.py
:Author: Michael Droettboom and Karl MacMillan


Creates a binary image by splitting along a threshold value
determined using the Otsu algorithm.

Equivalent to ``image.threshold(image.otsu_find_threshold())``.

*storage_format* (optional)
  specifies the compression type for the result:
  
  DENSE (0)
    no compression
  RLE (1)
    run-length encoding compression

----------

**Example 1:** otsu_threshold()

..  image:: images/GreyScale_generic.png
   :height: 67
   :width: 96

..  image:: images/otsu_threshold_plugin_00.png
   :height: 67
   :width: 96



``threshold``
-------------

``Image`` [OneBit] **threshold** (int *threshold*, ``Choice`` [dense|rle] *storage format*)


:Operates on: ``Image`` [GreyScale|Grey16|Float]
:Returns: ``Image`` [OneBit]
:Category: Thresholding
:Defined in: threshold.py
:Author: Michael Droettboom and Karl MacMillan


Creates a binary image by splitting along a given threshold value.

Pixels that are greater than the given value become white.
Pixels less than the given value become black.

*storage_format* (optional)
  specifies the compression type for the result:

  DENSE (0)
    no compression
  RLE (1)
    run-length encoding compression.

----------

**Example 1:** threshold(128)

..  image:: images/GreyScale_generic.png
   :height: 67
   :width: 96

..  image:: images/threshold_plugin_00.png
   :height: 67
   :width: 96



``tsai_moment_preserving_find_threshold``
-----------------------------------------

int **tsai_moment_preserving_find_threshold** ()


:Operates on: ``Image`` [GreyScale]
:Returns: int
:Category: Thresholding
:Defined in: threshold.py
:Author: Uma Kompella


Finds a threshold point using the Tsai Moment Preserving threshold
algorithm. Reference:

W.H. Tsai: *Moment-Preserving Thresholding: A New Approach.*
Computer Vision Graphics and Image Processing (29), pp. 377-393
(1985)

----------

**Example 1:** tsai_moment_preserving_find_threshold()

..  image:: images/GreyScale_generic.png
   :height: 67
   :width: 96

*result* = 153



``tsai_moment_preserving_threshold``
------------------------------------

``Image`` [OneBit] **tsai_moment_preserving_threshold** (``Choice`` [dense|rle] *storage format*)


:Operates on: ``Image`` [GreyScale]
:Returns: ``Image`` [OneBit]
:Category: Thresholding
:Defined in: threshold.py
:Author: Uma Kompella


Creates a binary image by splitting along a threshold value
determined using the Tsai Moment Preserving Threshold algorithm.

Equivalent to
``image.threshold(image.tsai_moment_preserving_find_threshold())``.

*storage_format* (optional)
  specifies the compression type for the result:

  DENSE (0)
    no compression
  RLE (1)
    run-length encoding compression

----------

**Example 1:** tsai_moment_preserving_threshold()

..  image:: images/GreyScale_generic.png
   :height: 67
   :width: 96

..  image:: images/tsai_moment_preserving_threshold_plugin_00.png
   :height: 67
   :width: 96



