
Features
========

``area``
--------

``FloatVector`` **area** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


The area of the bounding box (i.e. *nrows* * *ncols*).

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|       |          |   X    |
+-------+----------+--------+

----------

**Example 1:** area()

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

*result* = array('d', [7000.0])



``aspect_ratio``
----------------

``FloatVector`` **aspect_ratio** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


The aspect ratio of the bounding box (i.e. *ncols* / *nrows*).

This feature is scale invariant.

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|   X   |          |   X    |
+-------+----------+--------+

----------

**Example 1:** aspect_ratio()

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

*result* = array('d', [0.69999999999999996])



``black_area``
--------------

``FloatVector`` **black_area** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


The simplest of all feature-generating functions, ``black_area``
simply returns the number of black pixels.

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|       |     X    |   X    |
+-------+----------+--------+

.. warning:: This feature is not scale invariant.

----------

**Example 1:** black_area()

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

*result* = array('d', [1518.0])



``compactness``
---------------

``FloatVector`` **compactness** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


Compactness is the volume to surface ratio. Highly ornate connected
components have a low compactness, whereas a perfect circle has a 
high compactness. The present implementation of this feature in
Gamera does however not return the compactness, but its *inverse*,
i.e. the surface to volume ratio.

Since this function requires allocation and deallocation of
memory, it is relatively slow.  However, it has proven to be a
very useful feature in many cases.

This feature is not scale invariant, because, as
the image is scaled by *a*, the surface increases proportional to *a*
while the volume grows with *a^2*.
This is currently not corrected for.

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|       |    X     |   X    |
+-------+----------+--------+

----------

**Example 1:** compactness()

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

*result* = array('d', [0.52766798418972338])



``moments``
-----------

``FloatVector`` **moments** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


Returns *moments* of the image.

The first two elements of the returned ``FloatVector`` are the 
center of gravity on *x* and *y* axis normalized by width and height,
respectively. The following seven entries are the 
*normalized central moments* (*u20,u02,u11,u30,u12,u21,u03*). For their
definition, see Gonzalez, Woods: "Digital Image Processing",
Prentice Hall, second edition (2002).

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|   X   |          |        |
+-------+----------+--------+

----------

**Example 1:** moments()

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

*result* = array('d', [0.50158484657539482, 0.54566082431695084, 0.19879033815007144, 0.4166108441912556, -0.12548447613565852, 0.0062430763858119069, 0.10423298400666886, -0.049510290646450052, -0.079527650509540193])



``ncols_feature``
-----------------

``FloatVector`` **ncols_feature** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


Simply the number of cols. As this feature is *not* scale
invariant, it is helpful for distinguishing similar symbols of
different size.

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|       |          |   X    |
+-------+----------+--------+

----------

**Example 1:** ncols_feature()

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

*result* = array('d', [70.0])



``nholes``
----------

``FloatVector`` **nholes** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


Computes for each row or column the average number of white runs not
	touching the border. From these values, the average over all rows and
	all columns is returned.

The elements of the returned ``FloatVector`` are:

0. vertical
1. horizontal

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|   X   |          |   X    |
+-------+----------+--------+

----------

**Example 1:** nholes()

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

*result* = array('d', [1.8857142857142857, 0.95999999999999996])



``nholes_extended``
-------------------

``FloatVector`` **nholes_extended** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


Divides the image into four strips and then does a nholes_
analysis on each of those strips. This is first done vertically
and then horizontally, resulting in a total of eight feature values.

The elements of the returned ``FloatVector`` are:

0 - 3
  vertical ``nholes`` for each of the strips in order left to right.
4 - 7
  horizonal ``nholes`` for each of the strips in order top to bottom.

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|   X   |          |        |
+-------+----------+--------+

----------

**Example 1:** nholes_extended()

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

*result* = array('d', [0.17142857142857143, 2.5142857142857142, 2.7428571428571429, 1.8857142857142857, 0.0, 1.6000000000000001, 1.52, 0.71999999999999997])



``nrows_feature``
-----------------

``FloatVector`` **nrows_feature** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


Simply the number of rows. As this feature is *not* scale
invariant, it is helpful for distinguishing similar symbols of
different size.

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|       |          |   X    |
+-------+----------+--------+

----------

**Example 1:** nrows_feature()

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

*result* = array('d', [100.0])



``skeleton_features``
---------------------

``FloatVector`` **skeleton_features** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


Generates a number of features based on the skeleton of an image.
First, the image in skeletonized using the Lee and Chen algorithm,
which guarantees that the pixels of the resulting skeleton are
never more than 4-connected.  Then, this skeleton is analysed for
a number of properties:

0. Number of X joints (4-connected pixels)
1. Number of T joints (3-connected pixels)
2. Average number of bend points (pixels which do not form a horizontal or
   vertical line with its neighbors)
3. Number of end points (1-connected pixels)
4. Number of *x*-axis crossings with respect to the *x*-axis through the center of mass
5. Number of *y*-axis crossings with respect to the *y*-axis through the center of mass

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|   X   |          |   X    |
+-------+----------+--------+

----------

**Example 1:** skeleton_features()

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

*result* = array('d', [4.0, 15.0, 0.41726618705035973, 12.0, 4.0, 3.0])



``top_bottom``
--------------

``FloatVector`` **top_bottom** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


Features useful only for segmentation-free analysis.  Currently,
the first feature is the first row containing a black pixel, and
the second feature is the last row containing a black pixel.

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|   X   |          |   X    |
+-------+----------+--------+

----------

**Example 1:** top_bottom()

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

*result* = array('d', [0.0, 0.98999999999999999])



``volume``
----------

``FloatVector`` **volume** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


The percentage of black pixels within the rectangular bounding box
of the image.  Result in range (0, 1].

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|   X   |          |   X    |
+-------+----------+--------+

----------

**Example 1:** volume()

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

*result* = array('d', [0.21685714285714286])



``volume16regions``
-------------------

``FloatVector`` **volume16regions** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


Divides the image into a 4 x 4 grid of 16 regions and calculates
the volume within each. This feature is also known as "zoning" method.

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|   X   |          |        |
+-------+----------+--------+

----------

**Example 1:** volume16regions()

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

*result* = array('d', [0.0, 0.18588235294117647, 0.54823529411764704, 0.068235294117647061, 0.0, 0.21777777777777776, 0.051111111111111114, 0.43555555555555553, 0.084705882352941173, 0.46352941176470586, 0.47058823529411764, 0.32705882352941179, 0.34444444444444444, 0.18222222222222223, 0.035555555555555556, 0.077777777777777779])



``volume64regions``
-------------------

``FloatVector`` **volume64regions** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Michael Droettboom and Karl MacMillan


Divides the image into a 8 x 8 grid of 64 regions and calculates
the volume within each. This feature is also known as "zoning" method.

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|   X   |          |        |
+-------+----------+--------+

----------

**Example 1:** volume64regions()

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

*result* = array('d', [0.0, 0.0, 0.0, 0.0096153846153846159, 0.25, 0.125, 0.0625, 0.0, 0.0, 0.0, 0.0092592592592592587, 0.65811965811965811, 0.79629629629629628, 0.94017094017094016, 0.21296296296296297, 0.0, 0.0, 0.0, 0.31481481481481483, 0.19658119658119658, 0.0, 0.18803418803418803, 0.70370370370370372, 0.15384615384615385, 0.0, 0.0, 0.12962962962962962, 0.23076923076923078, 0.0, 0.0085470085470085479, 0.7407407407407407, 0.18803418803418803, 0.072916666666666671, 0.0, 0.1875, 0.98076923076923073, 0.98958333333333337, 0.85576923076923073, 0.51041666666666663, 0.21153846153846154, 0.26851851851851855, 0.0, 0.56481481481481477, 0.13675213675213677, 0.1111111111111111, 0.034188034188034191, 0.42592592592592593, 0.18803418803418803, 0.42592592592592593, 0.0, 0.37962962962962965, 0.068376068376068383, 0.12037037037037036, 0.02564102564102564, 0.16666666666666666, 0.14529914529914531, 0.32407407407407407, 0.63247863247863245, 0.30555555555555558, 0.0, 0.0, 0.0, 0.0, 0.0])



``zernike_moments``
-------------------

``FloatVector`` **zernike_moments** ()


:Operates on: ``Image`` [OneBit]
:Returns: ``FloatVector``
:Category: Features
:Defined in: features.py
:Author: Robert Butz and Christoph Dalitz


Computes the absolute values of the Normalized Zernike Moments up to
order six.

Zernike moments are the scalar product in the complex L2
Hilbert space between the image and the complex Zernike polynomials.
This results in complex values, the absolute values of which are
invariant under image rotation and reflection. To make them additionally
scale invariant, different normalization schemes have been suggested.
The present implementation normalizes the Zernike moments by
division with the zeroeth geometric moment *m00*, which results
in an approximate scale invariance according to
S. Belkasim, E. Hassan, T. Obeidi: "Explicit invariance of Cartesian
Zernike moments." Pattern Recognition Letters 28, pp. 1969-1980 (2007)

The return values are the absolute values of
*A20, A22, A31, A33, A40, A42, A44, A51, A53, A54, A60, A62, A64, A66*.
The moments *A00* and *A11* are not computed because these are constant
under the used normalization scheme.

+---------------------------+
| **Invariant to:**         |  
+-------+----------+--------+
| scale | rotation | mirror | 
+-------+----------+--------+
|   X   |    X     |   X    |
+-------+----------+--------+

----------

**Example 1:** zernike_moments()

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

*result* = array('d', [0.35570221601513524, 0.37280502456098508, 1.0154466430308065, 0.49707336608131353, 3.5354492194795513, 1.5932916018819399, 0.62134170760164187, 3.7607115620084022, 2.300729879970445, 0.74561004912197015, 5.4393022425702435, 6.0908087847207506, 3.1377614772963267, 0.86987839064229866])



