
Binarization
============

``gatos_background``
--------------------

``Image`` [GreyScale] **gatos_background** (``Image`` [OneBit] *binarization*, int *region size* = 15)


:Operates on: ``Image`` [GreyScale]
:Returns: ``Image`` [GreyScale]
:Category: Binarization
:Defined in: binarization.py
:Author: John Ashley Burgoyne and Ichiro Fujinaga


Estimates the background of an image according to Gatos et al.'s
method. See:

Gatos, Basilios, Ioannis Pratikakis, and Stavros
J. Perantonis. 2004. An adaptive binarization technique for low
quality historical documents. *Lecture Notes in Computer
Science* 3163: 102--113.

*region_size* 
  Region size for interpolation.

*binarization*
  A preliminary binarization of the image.


``gatos_threshold``
-------------------

``Image`` [OneBit] **gatos_threshold** (``Image`` [GreyScale] *background*, ``Image`` [OneBit] *binarization*, float *q* = 0.60, float *p1* = 0.50, float *p2* = 0.80)


:Operates on: ``Image`` [GreyScale]
:Returns: ``Image`` [OneBit]
:Category: Binarization
:Defined in: binarization.py
:Author: John Ashley Burgoyne and Ichiro Fujinaga


Thresholds an image according to Gatos et al.'s method. See:

Gatos, Basilios, Ioannis Pratikakis, and Stavros
J. Perantonis. 2004. An adaptive binarization technique for low
quality historical documents. *Lecture Notes in Computer
Science* 3163: 102-113.

*background*
  Estimated background of the image.

*binarization*
  A preliminary binarization of the image.

Use the default settings for the other parameters unless you know
what you are doing.


``image_mean``
--------------

float **image_mean** ()


:Operates on: ``Image`` [GreyScale|Grey16|Float]
:Returns: float
:Category: Binarization
:Defined in: binarization.py
:Author: John Ashley Burgoyne and Ichiro Fujinaga


Returns the mean over all pixels of an image as a FLOAT.


``image_variance``
------------------

float **image_variance** ()


:Operates on: ``Image`` [GreyScale|Grey16|Float]
:Returns: float
:Category: Binarization
:Defined in: binarization.py
:Author: John Ashley Burgoyne and Ichiro Fujinaga


Returns the variance over all pixels of an image as a FLOAT.


``mean_filter``
---------------

``Image`` [Float] **mean_filter** (int *region size* = 5)


:Operates on: ``Image`` [GreyScale|Grey16|Float]
:Returns: ``Image`` [Float]
:Category: Binarization
:Defined in: binarization.py
:Author: John Ashley Burgoyne and Ichiro Fujinaga


Returns the regional mean of an image as a FLOAT.

*region_size*
  The size of the region in which to calculate a mean.

----------

**Example 1:** mean_filter()

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

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

**Example 2:** mean_filter()

..  image:: images/Grey16_generic.png
   :height: 71
   :width: 82

..  image:: images/mean_filter_plugin_01.png
   :height: 71
   :width: 82

**Example 3:** mean_filter()

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

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



``niblack_threshold``
---------------------

``Image`` [OneBit] **niblack_threshold** (int *region size* = 15, float *sensitivity* = -0.20, int(0, 255) *lower bound* = 20, int(0, 255) *upper bound* = 150)


:Operates on: ``Image`` [GreyScale]
:Returns: ``Image`` [OneBit]
:Category: Binarization
:Defined in: binarization.py
:Author: John Ashley Burgoyne and Ichiro Fujinaga


Creates a binary image using Niblack's adaptive algorithm.

Niblack, W. 1986. *An Introduction to Digital Image Processing.* Englewood
Cliffs, NJ: Prentice Hall.

Like the QGAR library, there are two extra global thresholds for
the lightest and darkest regions.

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

*sensitivity*
  The sensitivity weight on the variance.

*lower bound*
  A global threshold beneath which all pixels are considered black.

*upper bound*
  A global threshold above which all pixels are considered white.

----------

**Example 1:** niblack_threshold()

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

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



``sauvola_threshold``
---------------------

``Image`` [OneBit] **sauvola_threshold** (int *region size* = 15, float *sensitivity* = 0.50, int(1, 255) *dynamic range* = 128, int(0, 255) *lower bound* = 20, int(0, 255) *upper bound* = 150)


:Operates on: ``Image`` [GreyScale]
:Returns: ``Image`` [OneBit]
:Category: Binarization
:Defined in: binarization.py
:Author: John Ashley Burgoyne and Ichiro Fujinaga


Creates a binary image using Sauvola's adaptive algorithm.

Sauvola, J. and M. Pietikainen. 2000. Adaptive document image
binarization.  *Pattern Recognition* 33: 225--236.

Like the QGAR library, there are two extra global thresholds for
the lightest and darkest regions.

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

*sensitivity*
  The sensitivity weight on the adjusted variance.

*dynamic_range*
  The dynamic range of the variance.

*lower bound*
  A global threshold beneath which all pixels are considered black.

*upper bound*
  A global threshold above which all pixels are considered white.

----------

**Example 1:** sauvola_threshold()

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

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



``variance_filter``
-------------------

``Image`` [Float] **variance_filter** (``Image`` [Float] *means*, int *region size* = 5)


:Operates on: ``Image`` [GreyScale|Grey16|Float]
:Returns: ``Image`` [Float]
:Category: Binarization
:Defined in: binarization.py
:Author: John Ashley Burgoyne and Ichiro Fujinaga


Returns the regional variance of an image as a FLOAT.

*means*
  Pre-calculated means for each region.

*region_size*
  The size of the region in which to calculate the variance.


``white_rohrer_threshold``
--------------------------

``Image`` [OneBit] **white_rohrer_threshold** (int *x lookahead* = 8, int *y lookahead* = 1, int *bias mode* = 0, int *bias factor* = 100, int *f factor* = 100, int *g factor* = 100)


:Operates on: ``Image`` [GreyScale]
:Returns: ``Image`` [OneBit]
:Category: Binarization
:Defined in: binarization.py
:Author: Uma Kompella (using code from the XITE library)


Creates a binary image using White and Rohrer's dynamic thresholding
algorithm. It is the first of the two algorithms described in:

J. M. White and G. D. Rohrer. 1983. Image thresholding for optical
character recognition and other applications requiring character
image extraction.  *IBM J. Res. Dev.* 27(4), pp. 400-411

The algorithm uses a 'running' average instead of true average of
the gray values in the neighborhood.  The lookahead parameter
gives the number of lookahead pixels used in the biased running
average that is used in deciding the threshold at each pixel
location.

*x_lookahead*
  the number of lookahead pixels in the horizontal direction for
  computing the running average. White and Rohrer suggest a value
  of 8 for a 240 dpi scanning resolution.

*y_lookahead*
  number of lines used for further averaging from the horizontal
  averages.

The other parameters are for calculating biased running average.
Without bias the thresholding decision would be determined by
noise fluctuations in uniform areas.

This implementation uses code from XITE__.

.. __: http://www.ifi.uio.no/forskning/grupper/dsb/Software/Xite/

.. note::

   Permission to use, copy, modify and distribute this software
   and its documentation for any purpose and without fee is hereby
   granted, provided that this copyright notice appear in all
   copies and that both that copyright notice and this permission
   notice appear in supporting documentation and that the name of
   B-lab, Department of Informatics or University of Oslo not be
   used in advertising or publicity pertaining to distribution of
   the software without specific, written prior permission.

   B-LAB DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
   INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
   FITNESS, IN NO EVENT SHALL B-LAB BE LIABLE FOR ANY SPECIAL,
   INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
   RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
   ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
   ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
   THIS SOFTWARE.

----------

**Example 1:** white_rohrer_threshold()

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

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



``wiener_filter``
-----------------

``Image`` [GreyScale|Grey16|Float] **wiener_filter** (int *region size* = 5, float *noise variance* = -1.00)


:Operates on: ``Image`` [GreyScale|Grey16|Float]
:Returns: ``Image`` [GreyScale|Grey16|Float]
:Category: Binarization
:Defined in: binarization.py
:Author: John Ashley Burgoyne and Ichiro Fujinaga


Adaptive Wiener filter for de-noising.

See:

J. Lim. 2001. *Two-Dimensional Signal Processing.* Englewood
Cliffs: Prentice Hall.

*region_size*
  The size of the region within which to calculate the filter
  coefficients.

*noise_variance* 
  Variance of the noise in the image. If negative, estimated
  automatically as the median of local variances.

----------

**Example 1:** wiener_filter()

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

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

**Example 2:** wiener_filter()

..  image:: images/Grey16_generic.png
   :height: 71
   :width: 82

..  image:: images/wiener_filter_plugin_01.png
   :height: 71
   :width: 82

**Example 3:** wiener_filter()

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

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



