pyefd 1.2.0

Python implementation of "Elliptic Fourier Features of a Closed Contour"

PyEFD
=====

.. image:: https://travis-ci.org/hbldh/pyefd.svg?branch=master
:target: https://travis-ci.org/hbldh/pyefd
.. image:: https://readthedocs.org/projects/pyefd/badge/?version=latest
:target: http://pyefd.readthedocs.org/en/latest/?badge=latest
:alt: Documentation Status
.. image:: http://img.shields.io/pypi/v/pyefd.svg
:target: https://pypi.python.org/pypi/pyefd/
.. image:: http://img.shields.io/pypi/l/pyefd.svg
:target: https://pypi.python.org/pypi/pyefd/
.. image:: https://coveralls.io/repos/github/hbldh/pyefd/badge.svg?branch=master
:target: https://coveralls.io/github/hbldh/pyefd?branch=master

An Python/NumPy implementation of a method for approximating a contour with a Fourier series, as described in [#first]_.

Installation
------------

.. code:: bash

$ pip install pyefd

Usage
-----

Given a closed contour of a shape, generated by e.g. `scikit-image <http://scikit-image.org/>`_
or `OpenCV <http://opencv.org/>`_, this package can fit a
`Fourier series <https://en.wikipedia.org/wiki/Fourier_series>`_
approximating the shape of the contour.

General usage examples
~~~~~~~~~~~~~~~~~~~~~~

This section describes the general usage patterns of ``pyefd``.

.. code:: python

from pyefd import elliptic_fourier_descriptors
coeffs = elliptic_fourier_descriptors(contour, order=10)


The coefficients returned are the ``a_n``, ``b_n``, ``c_n`` and ``d_n`` of
the following Fourier series representation of the shape.

The coefficients returned are by default normalized so that they are
rotation and size-invariant. This can be overridden by calling:

.. code:: python

from pyefd import elliptic_fourier_descriptors
coeffs = elliptic_fourier_descriptors(contour, order=10, normalize=False)

Normalization can also be done afterwards:

.. code:: python

from pyefd import normalize_efd
coeffs = normalize_efd(coeffs)

OpenCV example
~~~~~~~~~~~~~~

If you are using `OpenCV <http://opencv.org/>`_ to generate contours, this example
shows how to connect it to ``pyefd``.

.. code:: python

import cv2
import numpy
from pyefd import elliptic_fourier_descriptors

# Find the contours of a binary image using OpenCV.
contours, hierarchy = cv2.findContours(
im, cv2.RETR_TREE, cv2.CHAIN_APPROX_SIMPLE)

# Iterate through all contours found and store each contour's
# elliptical Fourier descriptor's coefficients.
coeffs = []
for cnt in contours:
# Find the coefficients of all contours
coeffs.append(elliptic_fourier_descriptors(
numpy.squeeze(cnt), order=10))

Using EFD as features
~~~~~~~~~~~~~~~~~~~~~

To use these as features, one can write a small wrapper function:

.. code:: python

def efd_feature(contour):
coeffs = elliptic_fourier_descriptors(contour, order=10, normalize=True)
return coeffs.flatten()[3:]

If the coefficients are normalized, then ``coeffs[0, 0] = 1.0``,
``coeffs[0, 1] = 0.0`` and ``coeffs[0, 2] = 0.0``, so they can be disregarded when using
the elliptic Fourier descriptors as features.

See [#first]_ for more technical details.

Testing
-------

Run tests with:

.. code:: bash

$ python setup.py test

or with `Pytest <http://pytest.org/latest/>`_:

.. code:: bash

$ py.test tests.py

The tests include a single image from the MNIST dataset of handwritten digits ([#second]_) as a contour to use
for testing.

Documentation
-------------

See `ReadTheDocs <http://pyefd.readthedocs.org/>`_.

References
----------

.. [#first] `Frank P Kuhl, Charles R Giardina, Elliptic Fourier features of a closed contour,
Computer Graphics and Image Processing, Volume 18, Issue 3, 1982, Pages 236-258,
ISSN 0146-664X, http://dx.doi.org/10.1016/0146-664X(82)90034-X. <http://www.sci.utah.edu/~gerig/CS7960-S2010/handouts/Kuhl-Giardina-CGIP1982.pdf>`_


.. [#second] `LeCun et al. (1999): The MNIST Dataset Of Handwritten Digits <http://yann.lecun.com/exdb/mnist/>`_


v1.2.0 (2018-06-14)
=================
- Updated setup.py
- Updated numpy requirement
- Added Pipfile
- Ran Black on code
- Testing on 3.6

v1.1.0 (2018-06-13)
=================
- New example for OpenCV
- Updated documentation

v1.0 (2016-04-19)
=================
- Deemed stable enough for version 1.0 release
- Created documentation.

v0.1.2 (2016-02-29)
===================
- Testing with pytest instead of nosetests.
- Added Coveralls use.

v0.1.1 (2016-02-17)
===================
- Fixed MANIFEST
- Added LICENSE file that was missing.

v0.1.0 (2016-02-09)
===================
- Initial release