
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


Loosely speaking, compactness is a volume to surface area ratio of
the connected components.  Highly ornate connected components have
a low compactness, whereas a perfect circle has very high
compactness.

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 relatively scale and rotation invariant, though as
the image scales, the pixel size relative to the image size
diminishes.  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.50592885375494068])



``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.19879033815007149, 0.41661084419125566, -0.12548447613565841, 0.0062430763858116259, 0.10423298400666849, -0.049510290646449975, -0.079527650509540887])



``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.92000000000000004])



``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 quadrants and then does a nholes_
analysis on each of those quadrants.

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

0 - 3
  vertical ``nholes`` for each of the quadrants in order NW, NE, SW, SE.
4 - 7
  horizonal ``nholes`` for each of the quadrants in order NW, NE, SW, SE.

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

----------

**Example 1:** nholes_extended()

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

*result* = array('d', [3.0, 44.0, 48.0, 33.0, 0.0, 40.0, 38.0, 14.0])



``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
5. Number of *y*-axis crossings

+---------------------------+
| **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.

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

----------

**Example 1:** volume16regions()

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

*result* = array('d', [0.0, 0.17555555555555555, 0.53111111111111109, 0.10666666666666667, 0.0, 0.21777777777777776, 0.037777777777777778, 0.44888888888888889, 0.080000000000000002, 0.42444444444444446, 0.46000000000000002, 0.34000000000000002, 0.33555555555555555, 0.21777777777777776, 0.035555555555555556, 0.093333333333333338])



``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.

+---------------------------+
| **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.034188034188034191, 0.3247863247863248, 0.18803418803418803, 0.076923076923076927, 0.0, 0.0, 0.0, 0.0085470085470085479, 0.65811965811965811, 0.80341880341880345, 0.94871794871794868, 0.25641025641025639, 0.0, 0.0, 0.0, 0.29059829059829062, 0.19658119658119658, 0.0, 0.14529914529914531, 0.69230769230769229, 0.15384615384615385, 0.0, 0.0, 0.14529914529914531, 0.22222222222222221, 0.0, 0.0, 0.68376068376068377, 0.23931623931623933, 0.059829059829059832, 0.0, 0.15384615384615385, 0.89743589743589747, 0.88034188034188032, 0.81196581196581197, 0.51282051282051277, 0.28205128205128205, 0.24786324786324787, 0.0, 0.5213675213675214, 0.13675213675213677, 0.1111111111111111, 0.042735042735042736, 0.39316239316239315, 0.18803418803418803, 0.37606837606837606, 0.0, 0.41025641025641024, 0.076923076923076927, 0.1111111111111111, 0.034188034188034191, 0.19658119658119658, 0.1623931623931624, 0.40170940170940173, 0.5641025641025641, 0.3504273504273504, 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: Michael Droettboom and Karl MacMillan


I can't say I understand much about Zernike moments, except that
they are well known for all kinds of invariance, and are often detailed
enough to reconstruct many shapes in a reasonable way.

A. Khotanzad and Y. Hong. Invariant image recognition by Zernike
moments.  *IEEE Transactions on Pattern Analysis and Machine
Intelligence*, 12(5), 1990.

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

----------

**Example 1:** zernike_moments()

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

*result* = array('d', [-37.223158090332504, -115.27274218259787, -27.38888482889574, -238.55414747433861, 99.091297417022759, 68.584177440635628, 329.80317022580272, 50.381730229673231, 8.6592661085182332, 58.042650475273767, 315.72095729103381, 301.84194567130726, -69.978045223611701, -62.235854155025173, 60.605978333980012, 15.471584853132827, 76.095993290903266, 22.29836927622112, 370.0254790802569, 228.42192663806134, -36.488449055135213, 78.967393589651095, 278.86617421574044, 978.55979874564093, -0.16938552126254994, -1.3852848954135613])



