
Convolution
===========


Kernels
-------

``AveragingKernel``
```````````````````

``Image`` [Float] **AveragingKernel** (int *radius* = 3)


:Returns: ``Image`` [Float]
:Category: Convolution/Kernels
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Creates an Averaging filter kernel for use with separable
convolution.  The window size is (2*radius+1) * (2*radius+1).

*radius*
  The radius of the kernel.


``BinomialKernel``
``````````````````

``Image`` [Float] **BinomialKernel** (int *radius* = 3)


:Returns: ``Image`` [Float]
:Category: Convolution/Kernels
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Creates a binomial filter kernel for use with separable
convolution of a given radius.

*radius*
  The radius of the kernel.


``GaussianDerivativeKernel``
````````````````````````````

``Image`` [Float] **GaussianDerivativeKernel** (float *standard_deviation* = 1.00, int *order* = 1)


:Returns: ``Image`` [Float]
:Category: Convolution/Kernels
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Init as a Gaussian derivative of order 'order'.  The radius of the
kernel is always 3*std_dev.

*standard_deviation*
  The standard deviation of the Gaussian kernel.

*order*
  The order of the Gaussian kernel.


``GaussianKernel``
``````````````````

``Image`` [Float] **GaussianKernel** (float *standard_deviation* = 1.00)


:Returns: ``Image`` [Float]
:Category: Convolution/Kernels
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Init as a Gaussian function. The radius of the kernel is always
3*standard_deviation.

*standard_deviation*
  The standard deviation of the Gaussian kernel.


``SimpleSharpeningKernel``
``````````````````````````

``Image`` [Float] **SimpleSharpeningKernel** (float *sharpening_factor* = 0.50)


:Returns: ``Image`` [Float]
:Category: Convolution/Kernels
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Creates a kernel for simple sharpening.


``SymmetricGradientKernel``
```````````````````````````

``Image`` [Float] **SymmetricGradientKernel** ()


:Returns: ``Image`` [Float]
:Category: Convolution/Kernels
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Init as a symmetric gradient filter of the form [ 0.5, 0.0, -0.5]


``convolve``
------------

``Image`` [GreyScale|Grey16|Float|RGB|Complex] **convolve** (``Image`` [Float] *kernel*, ``Choice`` [avoid|clip|repeat|reflect|wrap] *border_treatment* = clip)


:Operates on: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Returns: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Category: Convolution
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Convolves an image with a given kernel.

Uses code from the Vigra library (Copyright 1998-2007 by Ullrich
Köthe).

*kernel*
  A kernel for the convolution.  The kernel may either be a FloatImage
  or a nested Python list of floats.

*border_treatment*
  Specifies how to treat the borders of the image.  Must be one of
  the following:

  - BORDER_TREATMENT_AVOID (0)

    do not operate on a pixel where the kernel does not fit in the image

  - BORDER_TREATMENT_CLIP (1)

    clip kernel at image border (this is only useful if the kernel
    is >= 0 everywhere)

  - BORDER_TREATMENT_REPEAT (2)

    repeat the nearest valid pixel

  - BORDER_TREATMENT_REFLECT (3)
  
    reflect image at last row/column

  - BORDER_TREATMENT_WRAP (4)

    wrap image around (periodic boundary conditions)

Example usage:

.. code:: Python

  # Using a custom kernel
  img2 = image.convolve([[0.125, 0.0, -0.125],
                         [0.25 , 0.0, -0.25 ],
                         [0.125, 0.0, -0.125]])

  # Using one of the included kernel generators
  img2 = image.convolve(GaussianKernel(3.0))


``convolve_x``
--------------

``Image`` [GreyScale|Grey16|Float|RGB|Complex] **convolve_x** (``Image`` [Float] *kernel_x*, ``Choice`` [avoid|clip|repeat|reflect|wrap] *border_treatment* = clip)


:Operates on: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Returns: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Category: Convolution
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Convolves an image in the X directions with a 1D kernel.  This is
equivalent to what the Vigra library calls "Separable
Convolution".

Uses code from the Vigra library (Copyright 1998-2007 by Ullrich
Köthe).

*kernel_x*
  A kernel for the convolution in the *x* direction.  The kernel
  may either be a FloatImage or a nested Python list of floats.
  It must consist of only a single row.

*border_treatment*
  Specifies how to treat the borders of the image.  See
  ``convolve`` for information about *border_treatment* values.


``convolve_xy``
---------------

``Image`` [GreyScale|Grey16|Float|RGB|Complex] **convolve_xy** (``Image`` [Float] *kernel_x*, ``Image`` [Float] *kernel_y*, ``Choice`` [avoid|clip|repeat|reflect|wrap] *border_treatment* = clip)


:Operates on: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Returns: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Category: Convolution
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Convolves an image in both X and Y directions with 1D kernels.
This is equivalent to what the Vigra library calls "Separable
Convolution".

Uses code from the Vigra library (Copyright 1998-2007 by Ullrich
Köthe).

*kernel_y*
  A kernel for the convolution in the *y* direction.  The kernel
  may either be a FloatImage or a nested Python list of floats.

*kernel_x*
  A kernel for the convolution in the *x* direction.  The kernel
  may either be a FloatImage or a nested Python list of floats.
  If *kernel_x* is omitted, *kernel_y* will be used in the *x*
  direction.

*border_treatment*
  Specifies how to treat the borders of the image.  See
  ``convolve`` for information about *border_treatment* values.


``convolve_y``
--------------

``Image`` [GreyScale|Grey16|Float|RGB|Complex] **convolve_y** (``Image`` [Float] *kernel_y*, ``Choice`` [avoid|clip|repeat|reflect|wrap] *border_treatment* = clip)


:Operates on: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Returns: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Category: Convolution
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Convolves an image in the X directions with a 1D kernel.  This is
equivalent to what the Vigra library calls "Separable Convolution".

Uses code from the Vigra library (Copyright 1998-2007 by Ullrich
Köthe).

*kernel_y*
  A kernel for the convolution in the *x* direction.  The kernel
  may either be a FloatImage or a nested Python list of floats.
  It must consist of only a single row.

*border_treatment*
  Specifies how to treat the borders of the image.  See
  ``convolve`` for information about *border_treatment* values.


``gaussian_gradient``
---------------------

[object] **gaussian_gradient** (float *scale* = 0.50)


:Operates on: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Returns: [object]
:Category: Convolution
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Calculate the gradient vector by means of a 1st derivatives of
Gaussian filter.

*scale*

  Returns a tuple of (*x_gradient*, *y_gradient*).

----------

**Example 1:** gaussian_gradient(1.0)

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

|gaussian_gradient_plugin_00_00| |gaussian_gradient_plugin_00_01| 

.. |gaussian_gradient_plugin_00_00| image:: images/gaussian_gradient_plugin_00_00.png
   :height: 67
   :width: 96

.. |gaussian_gradient_plugin_00_01| image:: images/gaussian_gradient_plugin_00_01.png
   :height: 67
   :width: 96

**Example 2:** gaussian_gradient(1.0)

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

|gaussian_gradient_plugin_01_00| |gaussian_gradient_plugin_01_01| 

.. |gaussian_gradient_plugin_01_00| image:: images/gaussian_gradient_plugin_01_00.png
   :height: 129
   :width: 227

.. |gaussian_gradient_plugin_01_01| image:: images/gaussian_gradient_plugin_01_01.png
   :height: 129
   :width: 227

**Example 3:** gaussian_gradient(1.0)

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

|gaussian_gradient_plugin_02_00| |gaussian_gradient_plugin_02_01| 

.. |gaussian_gradient_plugin_02_00| image:: images/gaussian_gradient_plugin_02_00.png
   :height: 67
   :width: 96

.. |gaussian_gradient_plugin_02_01| image:: images/gaussian_gradient_plugin_02_01.png
   :height: 67
   :width: 96



``gaussian_smoothing``
----------------------

``Image`` [GreyScale|Grey16|Float|RGB|Complex] **gaussian_smoothing** (float *standard_deviation* = 1.00)


:Operates on: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Returns: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Category: Convolution
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Performs gaussian smoothing on an image.

*standard_deviation*
  The standard deviation of the Gaussian kernel.

----------

**Example 1:** gaussian_smoothing(1.0)

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

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

**Example 2:** gaussian_smoothing(3.0)

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

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

**Example 3:** gaussian_smoothing(1.0)

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

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



``hessian_matrix_of_gaussian``
------------------------------

[object] **hessian_matrix_of_gaussian** (float *scale* = 0.50)


:Operates on: ``Image`` [GreyScale|Grey16|Float]
:Returns: [object]
:Category: Convolution
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Filter image with the 2nd derivatives of the Gaussian at the given
scale to get the Hessian matrix.

*scale*

----------

**Example 1:** hessian_matrix_of_gaussian(1.0)

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

|hessian_matrix_of_gaussian_plugin_00_00| |hessian_matrix_of_gaussian_plugin_00_01| |hessian_matrix_of_gaussian_plugin_00_02| 

.. |hessian_matrix_of_gaussian_plugin_00_00| image:: images/hessian_matrix_of_gaussian_plugin_00_00.png
   :height: 67
   :width: 96

.. |hessian_matrix_of_gaussian_plugin_00_01| image:: images/hessian_matrix_of_gaussian_plugin_00_01.png
   :height: 67
   :width: 96

.. |hessian_matrix_of_gaussian_plugin_00_02| image:: images/hessian_matrix_of_gaussian_plugin_00_02.png
   :height: 67
   :width: 96



``laplacian_of_gaussian``
-------------------------

``Image`` [GreyScale|Grey16|Float] **laplacian_of_gaussian** (float *scale* = 0.50)


:Operates on: ``Image`` [GreyScale|Grey16|Float]
:Returns: ``Image`` [GreyScale|Grey16|Float]
:Category: Convolution
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Filter image with the Laplacian of Gaussian operator at the given
scale.

*scale*

----------

**Example 1:** laplacian_of_gaussian(1.0)

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

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



``simple_sharpen``
------------------

``Image`` [GreyScale|Grey16|Float|RGB|Complex] **simple_sharpen** (float *sharpening_factor* = 0.50)


:Operates on: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Returns: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Category: Convolution
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Perform simple sharpening.

*sharpening_factor*
  The amount of sharpening to perform.

----------

**Example 1:** simple_sharpen(1.0)

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

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

**Example 2:** simple_sharpen(3.0)

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

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



``sobel_edge_detection``
------------------------

``Image`` [GreyScale|Grey16|Float|RGB|Complex] **sobel_edge_detection** ()


:Operates on: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Returns: ``Image`` [GreyScale|Grey16|Float|RGB|Complex]
:Category: Convolution
:Defined in: convolution.py
:Author: Michael Droettboom (With code from VIGRA by Ullrich Köthe)


Performs simple Sobel edge detection on the image.

----------

**Example 1:** sobel_edge_detection(1.0)

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

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

**Example 2:** sobel_edge_detection(3.0)

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

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



