More documentation added. Setup.py updated.

Author: hbldh

HISTORY.rst

@@ -1,2 +1 @@
 include LICENSE README.md requirements.txt
-include README.rst LICENSE NOTICE HISTORY.rst test_requests.py requirements.txt requests/cacert.pem

MANIFEST.in

@@ -0,0 +1,65 @@
+PyEFD
+=====
+
+.. image:: https://travis-ci.org/hbldh/pyefd.svg?branch=master
+    :target: https://travis-ci.org/hbldh/pyefd
+.. image:: http://img.shields.io/pypi/v/pyefd.svg
+    :target: https://pypi.python.org/pypi/pyefd/
+.. image:: http://img.shields.io/pypi/dm/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/
+
+An Python/NumPy implementation of the method described in \[1\].
+
+Usage
+-----
+::
+
+    $ pip install pyefd
+
+Given a closed contour of a shape, this package can fit a 
+[Fourier series](https://en.wikipedia.org/wiki/Fourier_series) 
+approximating the shape of the contour::
+
+    from pyefd import elliptic_fourier_descriptors
+    coeffs = elliptic_fourier_descriptors(contour, order=10)
+   
+The coefficients returned are the :math:`a_n`, :math:`b_n`, :math:`c_n` and :math:`d_n` of
+the following Fourier series representation of the shape:
+
+.. math::
+    \begin{align*}
+        \hat{x}(t) & = A_0 + \sum_{n=1}^N\left( a_n \cos \frac{2n\pi t}{T} + b_n \sin \frac{2n\pi t}{T} \right)
+        \hat{y}(t) & = C_0 + \sum_{n=1}^N\left( c_n \cos \frac{2n\pi t}{T} + d_n \sin \frac{2n\pi t}{T} \right) 
+    \end{align*}
+
+See \[1\] for more technical details.
+
+Testing
+-------
+
+Run tests with::
+
+    $ python setup.py test
+
+or with [Pytest](http://pytest.org/latest/)::
+
+    $ py.test tests.py
+
+The tests includes a single image from the MNIST dataset of handwritten digits (\[2\]) as a contour to use
+for testing.
+
+Documentation
+-------------
+
+See the [Github pages](http://hbldh.github.io/pyefd).
+
+References
+----------
+
+\[1\] [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.sciencedirect.com/science/article/pii/0146664X8290034X)
+
+\[2\] [LeCun et al. (1999): The MNIST Dataset Of Handwritten Digits](http://yann.lecun.com/exdb/mnist/)

README.md

@@ -2,7 +2,7 @@
 # -*- coding: utf-8 -*-
 """
 :mod:`efd`
-==================
+==========
 
 Created by hbldh <henrik.blidh@nedomkull.com>
 Created on 2016-01-30
@@ -37,7 +37,7 @@
     _range = range
 
 
-def elliptical_fourier_descriptors(contour, order=10, normalize=False):
+def elliptic_fourier_descriptors(contour, order=10, normalize=False):
     """Calculate elliptical Fourier descriptors for a contour.
 
     :param contour: A contour array of size [M x 2].
@@ -53,10 +53,10 @@ def elliptical_fourier_descriptors(contour, order=10, normalize=False):
     """
     dxy = np.diff(contour, axis=0)
     dt = np.sqrt((dxy ** 2).sum(axis=1))
-    t = np.cumsum(dt)
+    t = np.concatenate([([0., ]), np.cumsum(dt)])
     T = t[-1]
 
-    phi = np.concatenate([([0., ]), (2 * np.pi * t) / T])
+    phi = (2 * np.pi * t) / T
 
     coeffs = np.zeros((order, 4))
     for n in _range(1, order + 1):
@@ -83,6 +83,9 @@ def normalize_efd(coeffs, size_invariant=True):
 
     :param coeffs: A [n x 4] Fourier coefficient array.
     :type coeffs: :py:class:`numpy.ndarray`
+    :param size_invariant: If size invariance normalizing should be done as well.
+                           Default is `True`
+    :type size_invariant: bool
     :return: The normalized [n x 4] Fourier coefficient array.
     :rtype: :py:class:`numpy.ndarray`
 
@@ -118,7 +121,31 @@ def normalize_efd(coeffs, size_invariant=True):
     return coeffs
 
 
-def plot_efd(contour, coeffs, locus=(0., 0.), n=300):
+def calculate_dc_coefficients(contour):
+    """Calculate the A0 and C0 coefficients of the elliptic Fourier series
+
+    :param contour: A contour array of size [M x 2].
+    :type contour: :py:class:`numpy.ndarray`
+    :return: The A0 and C0 coefficients.
+    :rtype: tuple
+
+    """
+    dxy = np.diff(contour, axis=0)
+    dt = np.sqrt((dxy ** 2).sum(axis=1))
+    t = np.concatenate([([0., ]), np.cumsum(dt)])
+    T = t[-1]
+
+    xi = np.cumsum(dxy[:, 0]) - (dxy[:, 0] / dt) * t[1:]
+    A0 = (1 / T) * np.sum(((dxy[:, 0] / (2 * dt)) * np.diff(t ** 2)) + xi * dt)
+    delta = np.cumsum(dxy[:, 1]) - (dxy[:, 1] / dt) * t[1:]
+    C0 = (1 / T) * np.sum(((dxy[:, 1] / (2 * dt)) * np.diff(t ** 2)) + delta * dt)
+
+    # A0 and CO relate to the first point of the contour array as origin.
+    # Adding those values to the coefficients to make them relate to true origin.
+    return contour[0, 0] + A0, contour[0, 1] + C0
+
+
+def plot_efd(coeffs, locus=(0., 0.), image=None, contour=None, n=300):
     """Plot a [2 x (n/2)] grid of successive truncations of the series.
 
     :param coeffs:  [n x 4] Fourier coefficient array.
@@ -136,20 +163,25 @@ def plot_efd(contour, coeffs, locus=(0., 0.), n=300):
         return
 
     N = coeffs.shape[0]
+    N_half = int(np.ceil(N / 2))
+    n_rows = 2
+
     t = np.linspace(0, 1.0, n)
     xt = np.ones((n,)) * locus[0]
     yt = np.ones((n,)) * locus[1]
 
-    ax = plt.subplot2grid((3, N // 2), (0, 0), colspan=N//2)
-    ax.imshow(contour, plt.cm.gray)
     for n in _range(coeffs.shape[0]):
         xt += (coeffs[n, 0] * np.cos(2 * (n + 1) * np.pi * t)) + \
               (coeffs[n, 1] * np.sin(2 * (n + 1) * np.pi * t))
         yt += (coeffs[n, 2] * np.cos(2 * (n + 1) * np.pi * t)) + \
               (coeffs[n, 3] * np.sin(2 * (n + 1) * np.pi * t))
-        ax = plt.subplot2grid((3, N // 2), (n // (N // 2) + 1, n % (N // 2)))
+        ax = plt.subplot2grid((n_rows, N_half), (n // N_half, n % N_half))
         ax.set_title(str(n + 1))
-        ax.plot(yt, -xt, 'r')
+        if contour is not None:
+            ax.plot(contour[:, 1], contour[:, 0], 'c--', linewidth=2)
+        ax.plot(yt, xt, 'r', linewidth=2)
+        if image is not None:
+            ax.imshow(image, plt.cm.gray)
 
     plt.show()
 

README.rst

@@ -18,23 +18,33 @@
 from __future__ import absolute_import
 
 import os
-from setuptools import setup, find_packages
+import sys
+from codecs import open
+from setuptools import setup
+
+
+if sys.argv[-1] == 'publish':
+    os.system('python setup.py register')
+    os.system('python setup.py sdist upload')
+    os.system('python setup.py bdist_wheel upload --universal')
+    sys.exit()
+
+
+version = '0.1.0.dev1'
+requires = ["numpy>=1.7.0"]
+
+
+def read(f):
+    return open(f, encoding='utf-8').read()
 
-# Get the long description from the README file
-try:
-    with open(os.path.join(os.path.abspath(os.path.dirname(__file__)), 'README.rst')) as f:
-        long_description = f.read()
-except:
-    with open(os.path.join(os.path.abspath(os.path.dirname(__file__)), 'README.md')) as f:
-        long_description = f.read()
 
 setup(
     name='pyefd',
-    version='0.1.0.dev1',
+    version=version,
     author='Henrik Blidh',
     author_email='henrik.blidh@nedomkull.com',
     description='Python implementation of "Elliptic Fourier Features of a Closed Contour"',
-    long_description=long_description,
+    long_description=read('README.rst') + '\n\n' + read('HISTORY.rst'),
     license='MIT',
     url='https://github.com/hbldh/pyefd',
     classifiers=[
@@ -53,9 +63,13 @@
         'Programming Language :: Python :: 3.4',
         'Programming Language :: Python :: 3.5',
     ],
-    keywords=["elliptical fourier descriptors", "shape descriptors", "image analysis"],
-    packages=find_packages(exclude=('tests', )),
-    install_requires=[],
+    keywords=["elliptic fourier descriptors", "shape descriptors", "image analysis"],
+    py_modules=['pyefd'],
+    test_suite="tests",
+    zip_safe=False,
+    include_package_data=True,
+    platforms='any',
+    install_requires=requires,
     package_data={},
     dependency_links=[],
     ext_modules=[],

pyefd.py

@@ -119,9 +119,41 @@ def tearDown(self):
         pass
 
     def test_efd_shape_1(self):
-        c = pyefd.elliptical_fourier_descriptors(contour_1, order=10)
-        assert c.shape == (10, 4)
+        coeffs = pyefd.elliptic_fourier_descriptors(contour_1, order=10)
+        assert coeffs.shape == (10, 4)
 
     def test_efd_shape_2(self):
-        c = pyefd.elliptical_fourier_descriptors(contour_1, order=40)
+        c = pyefd.elliptic_fourier_descriptors(contour_1, order=40)
         assert c.shape == (40, 4)
+
+    def test_normalizing_1(self):
+        c = pyefd.elliptic_fourier_descriptors(contour_1, normalize=False)
+        assert np.abs(c[0,0]) > 0.0
+        assert np.abs(c[0,1]) > 0.0
+        assert np.abs(c[0,2]) > 0.0
+
+    def test_normalizing_2(self):
+        c = pyefd.elliptic_fourier_descriptors(contour_1, normalize=True)
+        np.testing.assert_almost_equal(c[0, 0], 1.0, decimal=14)
+        np.testing.assert_almost_equal(c[0, 1], 0.0, decimal=14)
+        np.testing.assert_almost_equal(c[0, 2], 0.0, decimal=14)
+
+    def test_locus(self):
+        locus = pyefd.calculate_dc_coefficients(contour_1)
+        np.testing.assert_array_almost_equal(locus, np.mean(contour_1, axis=0), decimal=0)
+
+    def test_fit_1(self):
+        n = 300
+        locus = pyefd.calculate_dc_coefficients(contour_1)
+        coeffs = pyefd.elliptic_fourier_descriptors(contour_1, order=20)
+
+        t = np.linspace(0, 1.0, n)
+        xt = np.ones((n,)) * locus[0]
+        yt = np.ones((n,)) * locus[1]
+
+        for n in pyefd._range(coeffs.shape[0]):
+            xt += (coeffs[n, 0] * np.cos(2 * (n + 1) * np.pi * t)) + \
+                  (coeffs[n, 1] * np.sin(2 * (n + 1) * np.pi * t))
+            yt += (coeffs[n, 2] * np.cos(2 * (n + 1) * np.pi * t)) + \
+                  (coeffs[n, 3] * np.sin(2 * (n + 1) * np.pi * t))
+