
Deformations
============

``degrade_kanungo``
-------------------

``Image`` [OneBit] **degrade_kanungo** (float(0.00, 1.00) *eta*, float(0.00, 1.00) *a0*, float *a*, float(0.00, 1.00) *b0*, float *b*, int *k* = 2, int *random_seed* = 0)


:Operates on: ``Image`` [OneBit]
:Returns: ``Image`` [OneBit]
:Category: Deformations
:Defined in: deformation.py
:Author: Christoph Dalitz


Degrades an image due to a scheme proposed by Kanungo et al.
(see the reference below). This is supposed to emulate image defects
introduced through printing and scanning.

The degradation scheme depends on six parameters *(eta,a0,a,b0,b,k)* with
the following meaning:

  - each foreground pixel (black) is flipped with probability
    `a0*exp(-a*d^2) + eta`, where d is the distance to the closest
    background pixel

  - each background pixel (white) is flipped with probability
    `b0*exp(-b*d^2) + eta`, where d is the distance to the closest
    foreground pixel

  - eventuall a morphological closing operation is performed with a disk
    of diameter *k*. If you want to skip this step set *k=0*; in that
    case you should do your own smoothing afterwards.

The random generator is initialized with *random_seed* for allowing
reproducable results.

References:

  T. Kanungo, R.M. Haralick, H.S. Baird, et al.:
  *A statistical, nonparametric methodology for document
  degradation model validation.*
  IEEE Transactions on Pattern Analysis and Machine Intelligence
  22, pp. 1209-1223 (2000)


----------

**Example 1:** degrade_kanungo(0.0, 0.5, 0.5, 0.5, 0.5, 2, 0)

..  image:: images/OneBit_generic.png
   :height: 99
   :width: 69

..  image:: images/degrade_kanungo_plugin_00.png
   :height: 99
   :width: 69



``ink_diffuse``
---------------

``Image`` [OneBit|GreyScale|Grey16|Float|RGB] **ink_diffuse** (``Choice`` [Linear Horizontal|Linear Vertical|Brownian] *diffusion_type*, float *exponential_decay_constant*, int *random_seed* = -1)


:Operates on: ``Image`` [OneBit|GreyScale|Grey16|Float|RGB]
:Returns: ``Image`` [OneBit|GreyScale|Grey16|Float|RGB]
:Category: Deformations
:Defined in: deformation.py
:Author: Albert Brzeczko


Simulates water-driven diffusion of ink in paper.

----------

**Example 1:** ink_diffuse(0, 20)

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

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



``inkrub``
----------

``Image`` [OneBit|GreyScale|Grey16|Float|RGB] **inkrub** (int(0, 500) *transcription_prob*, int *random_seed* = -1)


:Operates on: ``Image`` [OneBit|GreyScale|Grey16|Float|RGB]
:Returns: ``Image`` [OneBit|GreyScale|Grey16|Float|RGB]
:Category: Deformations
:Defined in: deformation.py
:Author: Albert Brzeczko


Simulates rubbing off of ink from another page.

----------

**Example 1:** inkrub(50)

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

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



``noise``
---------

``Image`` [OneBit|GreyScale|Grey16|Float|RGB] **noise** (int(0, 500) *amplitude*, ``Choice`` [Horizontal|Vertical] *direction*, int *random_seed* = -1)


:Operates on: ``Image`` [OneBit|GreyScale|Grey16|Float|RGB]
:Returns: ``Image`` [OneBit|GreyScale|Grey16|Float|RGB]
:Category: Deformations
:Defined in: deformation.py
:Author: Albert Brzeczko


Causes random shifting of pixels within a user-specified range, in
a user-specified direction.

----------

**Example 1:** noise(10, 0)

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

..  image:: images/noise_plugin_00.png
   :height: 129
   :width: 237



``wave``
--------

``Image`` [OneBit|GreyScale|Grey16|Float|RGB] **wave** (int(0, 2147483647) *amplitude*, int(0, 2147483647) *period*, ``Choice`` [Horizontal|Vertical] *direction*, ``Choice`` [Sinusoid|Square|Sawtooth|Triangle|Sinc] *waveform*, int *offset*, float *turbulence* = 0.00, int *random_seed* = -1)


:Operates on: ``Image`` [OneBit|GreyScale|Grey16|Float|RGB]
:Returns: ``Image`` [OneBit|GreyScale|Grey16|Float|RGB]
:Category: Deformations
:Defined in: deformation.py
:Author: Albert Brzeczko


Causes periodic disturbance of user-defined frequency, amplitude,
and direction.  Turbulence specifies the amount of random
variation from that line.

----------

**Example 1:** wave(5, 10, 0, 0, 0)

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

..  image:: images/wave_plugin_00.png
   :height: 134
   :width: 227

**Example 2:** wave(10, 5, 1, 2, 0)

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

..  image:: images/wave_plugin_01.png
   :height: 129
   :width: 237



``white_speckles``
------------------

``Image`` [OneBit] **white_speckles** (float(0.00, 1.00) *p*, int *n*, int *k* = 2, ``Choice`` [rook|bishop|king] *connectivity* = king, int *random_seed* = 0)


:Operates on: ``Image`` [OneBit]
:Returns: ``Image`` [OneBit]
:Category: Deformations
:Defined in: deformation.py
:Author: Christoph Dalitz


Adds white speckles to an image. This is supposed to emulate
image defects introduced through printing, scanning and thresholding.

The degradation scheme depends on three parameters *(p,n,k)* with
the following meaning:

 - Each black pixel in the input image is taken with probability *p*
   as a starting point for a random walk of length *n*.
   Consequently *p* can be interpreted as the speckle frequency and *n*
   as a measure for the speckle size.

 - An image containing the random walk is smoothed by a closing operation
   with a rectangle of size *k*.

 - Eventually the image with the random walks is subtracted from both the
   original image and the provided staffless image, which results in white
   speckles at the random walk positions

Input arguments:

 *p, n, k*:
   speckle frequency, random walk length and closing disc size

 *connectivity*:
   effects the connectivity of adjacent random walk points as shown
   in the following figure (in case of bishop moves the final closing
   operation whitens the neighbouring 4-connected pixels too):

   .. image:: images/randomwalk_connectivity.png

References:

  C. Dalitz, M. Droettboom, B. Pranzas, I. Fujinaga:
  *A Comparative Study of Staff Removal Algorithms.*
  IEEE Transactions on Pattern Analysis and Machine Intelligence 30,
  pp. 753-766 (2008)


----------

**Example 1:** white_speckles(0.05, 5, 2, 2, 0)

..  image:: images/OneBit_generic.png
   :height: 99
   :width: 69

..  image:: images/white_speckles_plugin_00.png
   :height: 99
   :width: 69



