Spatial Elliptical Fourier Descriptors
=======================================
.. image:: https://travis-ci.org/sgrieve/spatial_efd.svg?branch=master
:target: https://travis-ci.org/sgrieve/spatial_efd
.. image:: https://ci.appveyor.com/api/projects/status/vgq1n1ke4tnia2yn/branch/master?svg=true
:target: https://ci.appveyor.com/project/sgrieve/spatial-efd
.. image:: https://codecov.io/gh/sgrieve/spatial_efd/branch/master/graph/badge.svg
:target: https://codecov.io/gh/sgrieve/spatial_efd
.. image:: https://requires.io/github/sgrieve/spatial_efd/requirements.svg?branch=master
:target: https://requires.io/github/sgrieve/spatial_efd/requirements/?branch=master
.. image:: https://readthedocs.org/projects/spatial-efd/badge/?version=latest
:target: http://spatial-efd.readthedocs.io/en/latest/?badge=latest
.. image:: https://img.shields.io/badge/License-MIT-green.svg
:target: https://opensource.org/licenses/MIT
.. image:: http://joss.theoj.org/papers/10.21105/joss.00189/status.svg
:target: http://dx.doi.org/10.21105/joss.00189
A pure python implementation of the elliptical Fourier analysis method described by `Kuhl and Giardina (1982) <http://www.sci.utah.edu/~gerig/CS7960-S2010/handouts/Kuhl-Giardina-CGIP1982.pdf>`_. This package is designed to allow the rapid analysis of spatial data stored as ESRI shapefiles, handling all of the geometric conversions. The resulting data can be written back to shapefiles to allow analysis with other spatial data or can be plotted using matplotlib.
The code is built upon the `pyefd module <https://github.com/hbldh/pyefd>`_ and it is hoped that this package will allow more geoscientists to apply this technique to analyze spatial data using the elliptical Fourier descriptor technique as there is no longer a data conversion barrier to entry. This package is also more feature rich than previous implementations, providing calculations of Fourier power and spatial averaging of collections of ellipses.
.. figure:: https://raw.githubusercontent.com/sgrieve/spatial_efd/master/_static/figure_1.png
:width: 600px
:align: center
:alt: spatial_efd example
:figclass: align-center
Examples of Fourier ellipses (black) being fitted to a shapefile outline (red), for increasing numbers of harmonics.
Features
--------
- Built-in geometry processing, just pass in a shapefile and get results quickly!
- Fourier coefficient average and standard deviation calculation
- Handles spatial input data through the pyshp library
- Compute an appropriate number of harmonics for a given polygon
- Basic plotting for analysis and debugging through matplotlib
- Write Fourier ellipses as shapefiles
Installation
------------
Install ``spatial_efd`` by running:
.. code-block:: bash
$ pip install spatial_efd
Dependencies
------------
This package supports Python 2.7 and Python 3 and is tested on Linux and Windows environments, using both the standard python interpreter and `pypy <https://pypy.org>`_. It requires ``matplotlib``, ``numpy``, ``future`` and ``pyshp``. These packages will all install automatically if ``spatial_efd`` is installed using ``pip``.
Dependencies can be tracked by visiting `requires.io <https://requires.io/github/sgrieve/spatial_efd/requirements/?branch=master>`_
Note that Python 2 has reached `end of life <https://www.python.org/doc/sunset-python-2/>`_ and although the code currently works under Python 2, this will not be supported, and future updates may completely break Python 2 support without warning.
Tests
----------
A range of unit tests are included in the `/test/` directory. These can
be run using `pytest`:
.. code-block:: bash
$ pytest
Many of these tests make use of the ``example_data.shp`` file which is a shapefile containing six polygons taken from a real dataset of landslide source areas.
Usage
----------
Normalized Data
~~~~~~~~~~~~~~~~~~~~~~
The first step in using ``spatial_efd`` is always to load a shapefile:
.. code-block:: python
import spatial_efd
shp = spatial_efd.LoadGeometries('test/fixtures/example_data.shp')
This creates a shapefile object ``shp`` which contains the polygon geometries we want to analyze. As in most cases more than one polygon will be stored in an individual file, a single polygon can be selected for processing using python's list notation:
.. code-block:: python
x, y, centroid = spatial_efd.ProcessGeometryNorm(shp[1])
This loads the geometry from the 2nd polygon within the shapefile into a list of x and a list of y coordinates. This method also computes the centroid of the polygon, which can be useful for later analysis. To make comparisons between data from different locations simpler, these data are normalized.
If you already know how many harmonics you wish to compute this can be specified during the calculation of the Fourier coefficients:
.. code-block:: python
harmonic = 20
coeffs = spatial_efd.CalculateEFD(x, y, harmonic)
However, if you need to quantify the number of harmonics needed to exceed a threshold Fourier power, this functionality is available. To do this, an initial set of coefficients need to be computed to the number of harmonics required to equal the Nyquist frequency:
.. code-block:: python
nyquist = spatial_efd.Nyquist(x)
tmpcoeffs = spatial_efd.CalculateEFD(x, y, nyquist)
harmonic = spatial_efd.FourierPower(tmpcoeffs, x)
coeffs = spatial_efd.CalculateEFD(x, y, harmonic)
Once the coefficients have been calculated they can be normalized following the steps outlined by `Kuhl and Giardina (1982) <http://www.sci.utah.edu/~gerig/CS7960-S2010/handouts/Kuhl-Giardina-CGIP1982.pdf>`_:
.. code-block:: python
coeffs, rotation = spatial_efd.normalize_efd(coeffs, size_invariant=True)
``size_invariant`` should be set to True (the default value) in most cases to normalize the coefficient values, allowing comparison between polygons of differing sizes. Set ``size_invariant`` to False if it is required to plot the Fourier ellipses alongside the input shapefiles, or if the Fourier ellipses are to be written to a shapefile. These techniques which apply to normalized data are outlined later in this document.
A set of coefficients can be converted back into a series of x and y coordinates by performing an inverse transform, where the harmonic value passed in will be the harmonic reconstructed:
.. code-block:: python
xt, yt = spatial_efd.inverse_transform(coeffs, harmonic=harmonic)
Wrappers around some of the basic ``matplotlib`` functionality is provided to speed up the visualization of results:
.. code-block:: python
ax = spatial_efd.InitPlot()
spatial_efd.PlotEllipse(ax, xt, yt, color='k', width=1.)
spatial_efd.SavePlot(ax, harmonic, '/plots/myfigure', 'png')
This example generates an axis object, plots our transformed coordinates onto it with a line width of 1 and a line color of black. These axes are saved with a title denoting the harmonic used to generate the coordinates and are saved in the format provided in the location provided.
Note that as this plotting is performed using ``matplotlib`` many other formatting options can be applied to the created axis object, to easily create publication ready plots.
To plot an overlay of a Fourier ellipse and the original shapefile data, a convenience function has been provided to streamline the coordinate processing required.
Plotting the normalized coefficients, where the data has been processed using the ``ProcessGeometryNorm`` method is undertaken as follows (Note that ``size_invariant`` has been set to ``False``):
.. code-block:: python
# size_invariant must be set to false if a normalized Fourier ellipse
# is to be plotted alongside the shapefile data
coeffs, rotation = spatial_efd.normalize_efd(coeffs, size_invariant=False)
ax = spatial_efd.InitPlot()
spatial_efd.plotComparison(ax, coeffs, harmonic, x, y, rotation=rotation)
spatial_efd.SavePlot(ax, harmonic, '/plots/myComparison', 'png')
Which produces a figure like this:
.. figure:: https://raw.githubusercontent.com/sgrieve/spatial_efd/master/_static/figure_3.png
:width: 400
:align: center
:alt: spatial_efd example
:figclass: align-center
Example of a normalized Fourier ellipse (black) being plotted on top of a shapefile outline (red).
All of the above examples have focused on processing a single polygon from a multipart shapefile, but in most cases multiple geometries will be required to be processed. One of the common techniques surrounding elliptical Fourier analysis is the averaging of a collection of polygons. This can be achieved as follows:
.. code-block:: python
shp = spatial_efd.LoadGeometries('test/fixtures/example_data.shp')
coeffsList = []
for shape in shp:
x, y, centroid = spatial_efd.ProcessGeometryNorm(shape)
harmonic = 10
coeffs = spatial_efd.CalculateEFD(x, y, harmonic)
coeffs, rotation = spatial_efd.normalize_efd(coeffs, size_invariant=True)
coeffsList.append(coeffs)
avgcoeffs = spatial_efd.AverageCoefficients(coeffsList)
Once the average coefficients for a collection of polygons has been computed, the standard deviation can also be calculated:
.. code-block:: python
SDcoeffs = spatial_efd.AverageSD(coeffsList, avgcoeffs)
With the average and standard deviation coefficients calculated, the average shape, with error ellipses can be plotted in the same manner as individual ellipses were plotted earlier
.. code-block:: python
x_avg, y_avg = spatial_efd.inverse_transform(avgcoeffs, harmonic=harmonic)
x_sd, y_sd = spatial_efd.inverse_transform(SDcoeffs, harmonic=harmonic)
ax = spatial_efd.InitPlot()
spatial_efd.PlotEllipse(ax, x_avg, y_avg, color='b', width=2.)
# Plot avg +/- 1 SD error ellipses
spatial_efd.PlotEllipse(ax, x_avg + x_sd, y_avg + y_sd, color='k', width=1.)
spatial_efd.PlotEllipse(ax, x_avg - x_sd, y_avg - y_sd, color='k', width=1.)
spatial_efd.SavePlot(ax, harmonic, '/plots/average', 'png')
Which produces a figure like this:
.. figure:: https://raw.githubusercontent.com/sgrieve/spatial_efd/master/_static/figure_4.png
:width: 400
:align: center
:alt: spatial_efd example
:figclass: align-center
Example of an average Fourier ellipse (blue) being plotted with standard deviation error ellipses (black).
Non-Normalized Data
~~~~~~~~~~~~~~~~~~~~~~
In cases where the original coordinates are needed, a different processing method can be called when loading coordinates from a shapefile, to return the non-normalized data:
.. code-block:: python
x, y, centroid = spatial_efd.ProcessGeometry(shp[1])
This method should be used where the original coordinates need to be preserved, for example if output to a shapefile is desired. To plot non-normalized data alongside the original shapefile data, the locus of the coefficients must be computed and passed as an argument to the inverse transform method:
.. code-block:: python
locus = spatial_efd.calculate_dc_coefficients(x, y)
xt, yt = spatial_efd.inverse_transform(coeffs, harmonic=harmonic, locus=locus)
To plot non-normalized coefficients, again call the ``plotComparison`` method, with the rotation value set to ``0`` as no normalization has been performed on the input data:
.. code-block:: python
ax = spatial_efd.InitPlot()
spatial_efd.plotComparison(ax, coeffs, harmonic, x, y, rotation=0.)
spatial_efd.SavePlot(ax, harmonic, '/plots/myComparison', 'png')
Which produces a figure like this:
.. figure:: https://raw.githubusercontent.com/sgrieve/spatial_efd/master/_static/figure_2.png
:width: 400
:align: center
:alt: spatial_efd example
:figclass: align-center
Example of a non-normalized Fourier ellipse (black) being plotted on top of a shapefile outline (red).
In the case of the non-normalized data plotted above, these ellipses can also be written to a shapefile to allow further analysis in a GIS package:
.. code-block:: python
shape_id = 1
shpinstance = spatial_efd.generateShapefile('mydata/myShapefile', prj='test/fixtures/example_data.prj')
shpinstance = spatial_efd.writeGeometry(coeffs, x, y, harmonic, shpinstance, shape_id)
The first method called creates a blank shapefile in the path ``mydata``, ready to be populated with Fourier ellipses. By passing in the existing ``example.prj`` file to the save method, a new projection file will be generated for the saved shapefile, ensuring that it has the correct spatial reference information for when it is loaded into a GIS package. Note that no reprojection is performed as the aim is for the input and output coordinate systems to match. If this parameter is excluded, the output shapefile will have no defined spatial reference system.
The second method can be wrapped in a loop to write as many ellipses as required to a single file. ``shape_id`` is written into the attribute table of the output shapefile and can be set to any integer as a means of identifying the Fourier ellipses.
For more detailed guidance on all of the functions and arguments in this package please check out the source code on `github <https://github.com/sgrieve/spatial_efd>`_ or the `API documentation. <http://spatial-efd.readthedocs.io/en/latest/spatial_efd.html>`_
Contribute
----------
.. image:: https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat
:target: https://codecov.io/github/sgrieve/spatial_efd/issues
I welcome contributions to the code, head to the issue tracker on GitHub to get involved!
- `Issue Tracker <https://github.com/sgrieve/spatial_efd/issues>`_
- `Source Code <https://github.com/sgrieve/spatial_efd>`_
Support
-------
If you find any bugs, have any questions or would like to see a feature in a new version, drop me a line:
- Twitter: `@GIStuart <https://www.twitter.com/GIStuart>`_
- Email: stuart@swdg.io
License
-------
The project is licensed under the MIT license.
Citation
--------
If you use this package for scientific research please cite it as:
Grieve, S. W. D. (2017), spatial-efd: A spatial-aware implementation of elliptical Fourier analysis, The Journal of Open Source Software, 2 (11), doi:10.21105/joss.00189.
You can grab a bibtex file `here <https://www.doi2bib.org/bib/10.21105%2Fjoss.00189>`_.
References
-----------
`Kuhl and Giardina (1982) <http://www.sci.utah.edu/~gerig/CS7960-S2010/handouts/Kuhl-Giardina-CGIP1982.pdf>`_. Elliptic Fourier features of a closed contour. Computer graphics and image processing, 18(3), 236-258.
Raw data
{
"_id": null,
"home_page": "http://github.com/sgrieve/spatial_efd",
"name": "spatial-efd",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "GIS elliptical fourier analysis shapefile",
"author": "Stuart WD Grieve",
"author_email": "stuart@swdg.io",
"download_url": "https://files.pythonhosted.org/packages/aa/0c/2b6fc1224329902be4f76d1f0611d4825b3cc7d8f84cd41fe4bfc3f54573/spatial_efd-1.2.1.tar.gz",
"platform": "",
"description": "Spatial Elliptical Fourier Descriptors\n=======================================\n\n.. image:: https://travis-ci.org/sgrieve/spatial_efd.svg?branch=master\n :target: https://travis-ci.org/sgrieve/spatial_efd\n\n.. image:: https://ci.appveyor.com/api/projects/status/vgq1n1ke4tnia2yn/branch/master?svg=true\n :target: https://ci.appveyor.com/project/sgrieve/spatial-efd\n\n.. image:: https://codecov.io/gh/sgrieve/spatial_efd/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/sgrieve/spatial_efd\n\n.. image:: https://requires.io/github/sgrieve/spatial_efd/requirements.svg?branch=master\n :target: https://requires.io/github/sgrieve/spatial_efd/requirements/?branch=master\n\n.. image:: https://readthedocs.org/projects/spatial-efd/badge/?version=latest\n :target: http://spatial-efd.readthedocs.io/en/latest/?badge=latest\n\n.. image:: https://img.shields.io/badge/License-MIT-green.svg\n :target: https://opensource.org/licenses/MIT\n\n.. image:: http://joss.theoj.org/papers/10.21105/joss.00189/status.svg\n :target: http://dx.doi.org/10.21105/joss.00189\n\n\nA pure python implementation of the elliptical Fourier analysis method described by `Kuhl and Giardina (1982) <http://www.sci.utah.edu/~gerig/CS7960-S2010/handouts/Kuhl-Giardina-CGIP1982.pdf>`_. This package is designed to allow the rapid analysis of spatial data stored as ESRI shapefiles, handling all of the geometric conversions. The resulting data can be written back to shapefiles to allow analysis with other spatial data or can be plotted using matplotlib.\n\nThe code is built upon the `pyefd module <https://github.com/hbldh/pyefd>`_ and it is hoped that this package will allow more geoscientists to apply this technique to analyze spatial data using the elliptical Fourier descriptor technique as there is no longer a data conversion barrier to entry. This package is also more feature rich than previous implementations, providing calculations of Fourier power and spatial averaging of collections of ellipses.\n\n.. figure:: https://raw.githubusercontent.com/sgrieve/spatial_efd/master/_static/figure_1.png\n :width: 600px\n :align: center\n :alt: spatial_efd example\n :figclass: align-center\n\n Examples of Fourier ellipses (black) being fitted to a shapefile outline (red), for increasing numbers of harmonics.\n\nFeatures\n--------\n\n- Built-in geometry processing, just pass in a shapefile and get results quickly!\n- Fourier coefficient average and standard deviation calculation\n- Handles spatial input data through the pyshp library\n- Compute an appropriate number of harmonics for a given polygon\n- Basic plotting for analysis and debugging through matplotlib\n- Write Fourier ellipses as shapefiles\n\nInstallation\n------------\n\nInstall ``spatial_efd`` by running:\n\n.. code-block:: bash\n\n $ pip install spatial_efd\n\nDependencies\n------------\n\nThis package supports Python 2.7 and Python 3 and is tested on Linux and Windows environments, using both the standard python interpreter and `pypy <https://pypy.org>`_. It requires ``matplotlib``, ``numpy``, ``future`` and ``pyshp``. These packages will all install automatically if ``spatial_efd`` is installed using ``pip``.\n\nDependencies can be tracked by visiting `requires.io <https://requires.io/github/sgrieve/spatial_efd/requirements/?branch=master>`_\n\nNote that Python 2 has reached `end of life <https://www.python.org/doc/sunset-python-2/>`_ and although the code currently works under Python 2, this will not be supported, and future updates may completely break Python 2 support without warning.\n\nTests\n----------\n\nA range of unit tests are included in the `/test/` directory. These can\nbe run using `pytest`:\n\n.. code-block:: bash\n\n $ pytest\n\nMany of these tests make use of the ``example_data.shp`` file which is a shapefile containing six polygons taken from a real dataset of landslide source areas.\n\nUsage\n----------\n\nNormalized Data\n~~~~~~~~~~~~~~~~~~~~~~\n\nThe first step in using ``spatial_efd`` is always to load a shapefile:\n\n.. code-block:: python\n\n import spatial_efd\n shp = spatial_efd.LoadGeometries('test/fixtures/example_data.shp')\n\nThis creates a shapefile object ``shp`` which contains the polygon geometries we want to analyze. As in most cases more than one polygon will be stored in an individual file, a single polygon can be selected for processing using python's list notation:\n\n.. code-block:: python\n\n x, y, centroid = spatial_efd.ProcessGeometryNorm(shp[1])\n\nThis loads the geometry from the 2nd polygon within the shapefile into a list of x and a list of y coordinates. This method also computes the centroid of the polygon, which can be useful for later analysis. To make comparisons between data from different locations simpler, these data are normalized.\n\nIf you already know how many harmonics you wish to compute this can be specified during the calculation of the Fourier coefficients:\n\n.. code-block:: python\n\n harmonic = 20\n coeffs = spatial_efd.CalculateEFD(x, y, harmonic)\n\nHowever, if you need to quantify the number of harmonics needed to exceed a threshold Fourier power, this functionality is available. To do this, an initial set of coefficients need to be computed to the number of harmonics required to equal the Nyquist frequency:\n\n.. code-block:: python\n\n nyquist = spatial_efd.Nyquist(x)\n tmpcoeffs = spatial_efd.CalculateEFD(x, y, nyquist)\n harmonic = spatial_efd.FourierPower(tmpcoeffs, x)\n coeffs = spatial_efd.CalculateEFD(x, y, harmonic)\n\nOnce the coefficients have been calculated they can be normalized following the steps outlined by `Kuhl and Giardina (1982) <http://www.sci.utah.edu/~gerig/CS7960-S2010/handouts/Kuhl-Giardina-CGIP1982.pdf>`_:\n\n.. code-block:: python\n\n coeffs, rotation = spatial_efd.normalize_efd(coeffs, size_invariant=True)\n\n``size_invariant`` should be set to True (the default value) in most cases to normalize the coefficient values, allowing comparison between polygons of differing sizes. Set ``size_invariant`` to False if it is required to plot the Fourier ellipses alongside the input shapefiles, or if the Fourier ellipses are to be written to a shapefile. These techniques which apply to normalized data are outlined later in this document.\n\nA set of coefficients can be converted back into a series of x and y coordinates by performing an inverse transform, where the harmonic value passed in will be the harmonic reconstructed:\n\n.. code-block:: python\n\n xt, yt = spatial_efd.inverse_transform(coeffs, harmonic=harmonic)\n\nWrappers around some of the basic ``matplotlib`` functionality is provided to speed up the visualization of results:\n\n.. code-block:: python\n\n ax = spatial_efd.InitPlot()\n spatial_efd.PlotEllipse(ax, xt, yt, color='k', width=1.)\n spatial_efd.SavePlot(ax, harmonic, '/plots/myfigure', 'png')\n\nThis example generates an axis object, plots our transformed coordinates onto it with a line width of 1 and a line color of black. These axes are saved with a title denoting the harmonic used to generate the coordinates and are saved in the format provided in the location provided.\n\nNote that as this plotting is performed using ``matplotlib`` many other formatting options can be applied to the created axis object, to easily create publication ready plots.\n\nTo plot an overlay of a Fourier ellipse and the original shapefile data, a convenience function has been provided to streamline the coordinate processing required.\nPlotting the normalized coefficients, where the data has been processed using the ``ProcessGeometryNorm`` method is undertaken as follows (Note that ``size_invariant`` has been set to ``False``):\n\n.. code-block:: python\n\n # size_invariant must be set to false if a normalized Fourier ellipse\n # is to be plotted alongside the shapefile data\n coeffs, rotation = spatial_efd.normalize_efd(coeffs, size_invariant=False)\n ax = spatial_efd.InitPlot()\n spatial_efd.plotComparison(ax, coeffs, harmonic, x, y, rotation=rotation)\n spatial_efd.SavePlot(ax, harmonic, '/plots/myComparison', 'png')\n\nWhich produces a figure like this:\n\n.. figure:: https://raw.githubusercontent.com/sgrieve/spatial_efd/master/_static/figure_3.png\n :width: 400\n :align: center\n :alt: spatial_efd example\n :figclass: align-center\n\n Example of a normalized Fourier ellipse (black) being plotted on top of a shapefile outline (red).\n\nAll of the above examples have focused on processing a single polygon from a multipart shapefile, but in most cases multiple geometries will be required to be processed. One of the common techniques surrounding elliptical Fourier analysis is the averaging of a collection of polygons. This can be achieved as follows:\n\n.. code-block:: python\n\n shp = spatial_efd.LoadGeometries('test/fixtures/example_data.shp')\n\n coeffsList = []\n\n for shape in shp:\n x, y, centroid = spatial_efd.ProcessGeometryNorm(shape)\n\n harmonic = 10\n coeffs = spatial_efd.CalculateEFD(x, y, harmonic)\n\n coeffs, rotation = spatial_efd.normalize_efd(coeffs, size_invariant=True)\n\n coeffsList.append(coeffs)\n\n avgcoeffs = spatial_efd.AverageCoefficients(coeffsList)\n\nOnce the average coefficients for a collection of polygons has been computed, the standard deviation can also be calculated:\n\n.. code-block:: python\n\n SDcoeffs = spatial_efd.AverageSD(coeffsList, avgcoeffs)\n\nWith the average and standard deviation coefficients calculated, the average shape, with error ellipses can be plotted in the same manner as individual ellipses were plotted earlier\n\n.. code-block:: python\n\n x_avg, y_avg = spatial_efd.inverse_transform(avgcoeffs, harmonic=harmonic)\n x_sd, y_sd = spatial_efd.inverse_transform(SDcoeffs, harmonic=harmonic)\n\n ax = spatial_efd.InitPlot()\n spatial_efd.PlotEllipse(ax, x_avg, y_avg, color='b', width=2.)\n\n # Plot avg +/- 1 SD error ellipses\n spatial_efd.PlotEllipse(ax, x_avg + x_sd, y_avg + y_sd, color='k', width=1.)\n spatial_efd.PlotEllipse(ax, x_avg - x_sd, y_avg - y_sd, color='k', width=1.)\n\n spatial_efd.SavePlot(ax, harmonic, '/plots/average', 'png')\n\nWhich produces a figure like this:\n\n.. figure:: https://raw.githubusercontent.com/sgrieve/spatial_efd/master/_static/figure_4.png\n :width: 400\n :align: center\n :alt: spatial_efd example\n :figclass: align-center\n\n Example of an average Fourier ellipse (blue) being plotted with standard deviation error ellipses (black).\n\nNon-Normalized Data\n~~~~~~~~~~~~~~~~~~~~~~\n\nIn cases where the original coordinates are needed, a different processing method can be called when loading coordinates from a shapefile, to return the non-normalized data:\n\n.. code-block:: python\n\n x, y, centroid = spatial_efd.ProcessGeometry(shp[1])\n\nThis method should be used where the original coordinates need to be preserved, for example if output to a shapefile is desired. To plot non-normalized data alongside the original shapefile data, the locus of the coefficients must be computed and passed as an argument to the inverse transform method:\n\n.. code-block:: python\n\n locus = spatial_efd.calculate_dc_coefficients(x, y)\n xt, yt = spatial_efd.inverse_transform(coeffs, harmonic=harmonic, locus=locus)\n\nTo plot non-normalized coefficients, again call the ``plotComparison`` method, with the rotation value set to ``0`` as no normalization has been performed on the input data:\n\n.. code-block:: python\n\n ax = spatial_efd.InitPlot()\n spatial_efd.plotComparison(ax, coeffs, harmonic, x, y, rotation=0.)\n spatial_efd.SavePlot(ax, harmonic, '/plots/myComparison', 'png')\n\nWhich produces a figure like this:\n\n.. figure:: https://raw.githubusercontent.com/sgrieve/spatial_efd/master/_static/figure_2.png\n :width: 400\n :align: center\n :alt: spatial_efd example\n :figclass: align-center\n\n Example of a non-normalized Fourier ellipse (black) being plotted on top of a shapefile outline (red).\n\nIn the case of the non-normalized data plotted above, these ellipses can also be written to a shapefile to allow further analysis in a GIS package:\n\n.. code-block:: python\n\n shape_id = 1\n shpinstance = spatial_efd.generateShapefile('mydata/myShapefile', prj='test/fixtures/example_data.prj')\n shpinstance = spatial_efd.writeGeometry(coeffs, x, y, harmonic, shpinstance, shape_id)\n\nThe first method called creates a blank shapefile in the path ``mydata``, ready to be populated with Fourier ellipses. By passing in the existing ``example.prj`` file to the save method, a new projection file will be generated for the saved shapefile, ensuring that it has the correct spatial reference information for when it is loaded into a GIS package. Note that no reprojection is performed as the aim is for the input and output coordinate systems to match. If this parameter is excluded, the output shapefile will have no defined spatial reference system.\n\nThe second method can be wrapped in a loop to write as many ellipses as required to a single file. ``shape_id`` is written into the attribute table of the output shapefile and can be set to any integer as a means of identifying the Fourier ellipses.\n\nFor more detailed guidance on all of the functions and arguments in this package please check out the source code on `github <https://github.com/sgrieve/spatial_efd>`_ or the `API documentation. <http://spatial-efd.readthedocs.io/en/latest/spatial_efd.html>`_\n\nContribute\n----------\n\n.. image:: https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat\n :target: https://codecov.io/github/sgrieve/spatial_efd/issues\n\nI welcome contributions to the code, head to the issue tracker on GitHub to get involved!\n\n- `Issue Tracker <https://github.com/sgrieve/spatial_efd/issues>`_\n- `Source Code <https://github.com/sgrieve/spatial_efd>`_\n\nSupport\n-------\n\nIf you find any bugs, have any questions or would like to see a feature in a new version, drop me a line:\n\n- Twitter: `@GIStuart <https://www.twitter.com/GIStuart>`_\n- Email: stuart@swdg.io\n\nLicense\n-------\n\nThe project is licensed under the MIT license.\n\nCitation\n--------\n\nIf you use this package for scientific research please cite it as:\n\nGrieve, S. W. D. (2017), spatial-efd: A spatial-aware implementation of elliptical Fourier analysis, The Journal of Open Source Software, 2 (11), doi:10.21105/joss.00189.\n\n\nYou can grab a bibtex file `here <https://www.doi2bib.org/bib/10.21105%2Fjoss.00189>`_.\n\nReferences\n-----------\n\n`Kuhl and Giardina (1982) <http://www.sci.utah.edu/~gerig/CS7960-S2010/handouts/Kuhl-Giardina-CGIP1982.pdf>`_. Elliptic Fourier features of a closed contour. Computer graphics and image processing, 18(3), 236-258.\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Spatial elliptical fourier analysis",
"version": "1.2.1",
"project_urls": {
"Homepage": "http://github.com/sgrieve/spatial_efd"
},
"split_keywords": [
"gis",
"elliptical",
"fourier",
"analysis",
"shapefile"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "867de867162823afc694e6ca41817236a78f4b04f4c6717b72d8d0b4ed5e9d46",
"md5": "06becee38517160961d676f0ecd79f77",
"sha256": "5684083569ee5e2a277f38ea6fc87dc6694f5ecdcf505e2392fde8ebe07953b9"
},
"downloads": -1,
"filename": "spatial_efd-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "06becee38517160961d676f0ecd79f77",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 14146,
"upload_time": "2020-03-04T17:55:21",
"upload_time_iso_8601": "2020-03-04T17:55:21.593598Z",
"url": "https://files.pythonhosted.org/packages/86/7d/e867162823afc694e6ca41817236a78f4b04f4c6717b72d8d0b4ed5e9d46/spatial_efd-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "aa0c2b6fc1224329902be4f76d1f0611d4825b3cc7d8f84cd41fe4bfc3f54573",
"md5": "367f778bfbf222975a8a092d1048a4c5",
"sha256": "e49d71178b925a7f266619899b432c940a116a7afb86cbaa2ce706ec938b5904"
},
"downloads": -1,
"filename": "spatial_efd-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "367f778bfbf222975a8a092d1048a4c5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 177853,
"upload_time": "2020-03-04T17:55:23",
"upload_time_iso_8601": "2020-03-04T17:55:23.295105Z",
"url": "https://files.pythonhosted.org/packages/aa/0c/2b6fc1224329902be4f76d1f0611d4825b3cc7d8f84cd41fe4bfc3f54573/spatial_efd-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-03-04 17:55:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sgrieve",
"github_project": "spatial_efd",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"appveyor": true,
"lcname": "spatial-efd"
}
JSON
