spatial_efd

spatial_efd.spatial_efd.AverageCoefficients(coeffList)[source]

Average the coefficients contained in the list of coefficient arrays, coeffList.

This method is outlined in:

2-D particle shape averaging and comparison using Fourier descriptors: Powder Technology Volume 104, Issue 2, 1 September 1999, Pages 180-189

Parameters:coeffList (list) – A list of coefficient arrays to be averaged.
Returns:A numpy array containing the average An, Bn, Cn, Dn coefficient values.
Return type:numpy.ndarray
spatial_efd.spatial_efd.AverageSD(coeffList, avgcoeffs)[source]

Use the coefficients contained in the list of coefficient arrays, coeffList, and the average coefficient values to compute the standard deviation of series of ellipses.

This method is outlined in:

2-D particle shape averaging and comparison using Fourier descriptors: Powder Technology Volume 104, Issue 2, 1 September 1999, Pages 180-189

Parameters:
  • coeffList (list) – A list of coefficient arrays to be averaged.
  • avgcoeffs (numpy.ndarray) – A numpy array containing the average coefficient values, generated by calling AverageCoefficients().
Returns:

A numpy array containing the standard deviation An, Bn, Cn, Dn coefficient values.

Return type:

numpy.ndarray

spatial_efd.spatial_efd.CalculateEFD(X, Y, harmonics=10)[source]

Compute the Elliptical Fourier Descriptors for a polygon.

Implements Kuhl and Giardina method of computing the coefficients An, Bn, Cn, Dn for a specified number of harmonics. This code is adapted from the pyefd module. See the original paper for more detail:

Kuhl, FP and Giardina, CR (1982). Elliptic Fourier features of a closed contour. Computer graphics and image processing, 18(3), 236-258.

Parameters:
  • X (list) – A list (or numpy array) of x coordinate values.
  • Y (list) – A list (or numpy array) of y coordinate values.
  • harmonics (int) – The number of harmonics to compute for the given shape, defaults to 10.
Returns:

A numpy array of shape (harmonics, 4) representing the four coefficients for each harmonic computed.

Return type:

numpy.ndarray

spatial_efd.spatial_efd.CloseContour(X, Y)[source]

Close an opened polygon.

Parameters:
  • X (list) – A list (or numpy array) of x coordinate values.
  • Y (list) – A list (or numpy array) of y coordinate values.
Returns:

A tuple containing the X and Y lists of coordinates where the first and last elements are equal.

Return type:

tuple

spatial_efd.spatial_efd.ContourArea(X, Y)[source]

Compute the area of an irregular polygon.

Ensures the contour is closed before processing, but does not modify X or Y outside the scope of this method. Algorithm taken from http://paulbourke.net/geometry/polygonmesh/.

Parameters:
  • X (list) – A list (or numpy array) of x coordinate values.
  • Y (list) – A list (or numpy array) of y coordinate values.
Returns:

The area of the input polygon.

Return type:

float

spatial_efd.spatial_efd.ContourCentroid(X, Y)[source]

Compute the centroid of an irregular polygon.

Ensures the contour is closed before processing, but does not modify X or Y outside the scope of this method. Algorithm taken from http://paulbourke.net/geometry/polygonmesh/.

Parameters:
  • X (list) – A list (or numpy array) of x coordinate values.
  • Y (list) – A list (or numpy array) of y coordinate values.
Returns:

A tuple containing the (x,y) coordinate of the center of the input polygon.

Return type:

tuple

spatial_efd.spatial_efd.FourierPower(coeffs, X, threshold=0.9999)[source]

Compute the total Fourier power and find the minium number of harmonics required to exceed the threshold fraction of the total power.

This is a good method for identifying the number of harmonics to use to describe a polygon. For more details see:

  1. Costa et al. / Postharvest Biology and Technology 54 (2009) 38-47

Warning

The number of coeffs must be >= the nyquist freqency.

Parameters:
  • coeffs (numpy.ndarray) – A numpy array of shape (n, 4) representing the four coefficients for each harmonic computed.
  • X (list) – A list (or numpy array) of x coordinate values.
  • threshold (float) – The threshold fraction of the total Fourier power, the default is 0.9999.
Returns:

The number of harmonics required to represent the contour above the threshold Fourier power.

Return type:

int

spatial_efd.spatial_efd.InitPlot()[source]

Set up the axes for plotting, ensuring that x and y dimensions are equal.

Returns:Matplotlib axis instance.
Return type:matplotlib.axes.Axes
spatial_efd.spatial_efd.LoadGeometries(filename)[source]

Takes a filename and uses pyshp to load it, returning a list of shapefile.ShapeRecord instances.

This list can be iterated over, passing the individual shape instances to ProcessGeometry() one by one. There is no input handling if a non-polygon shapefile is passed in, that will result in undefined behavior.

Parameters:filename (string) – A filename with optional full path pointing to an ESRI shapefile to be loaded by the pyshp module. The file extension is optional.
Returns:A list of shapefile._ShapeRecord objects representing each polygon geometry in the shapefile.
Return type:list
spatial_efd.spatial_efd.NormContour(X, Y, rawCentroid)[source]

Normalize the coordinates which make up a contour.

Rescale the coordinates to values between 0 and 1 in both the x and y directions. The normalizing is performed using x or y width of the minimum bounding rectangle of the contour, whichever is largest. X and Y must have the same dimensions.

Parameters:
  • X (list) – A list (or numpy array) of x coordinate values.
  • Y (list) – A list (or numpy array) of y coordinate values.
  • rawCentroid (tuple) – A tuple containing the x,y coordinates of the centroid of the contour.
Returns:

A tuple containing a list of normalized x coordinates, a list of normalized y coordinate and the normalized centroid.

Return type:

tuple

spatial_efd.spatial_efd.Nyquist(X)[source]

Returns the maximum number of harmonics that can be computed for a given contour, the nyquist freqency.

See this paper for details: C. Costa et al. / Postharvest Biology and Technology 54 (2009) 38-47

Parameters:X (list) – A list (or numpy array) of x coordinate values.
Returns:The nyquist frequency, expressed as a number of harmonics.
Return type:int
spatial_efd.spatial_efd.PlotEllipse(ax, x, y, color='k', width=1.0)[source]

Plots an ellipse represented as a series of x and y coordinates on a given axis.

Parameters:
  • ax (matplotlib.axes.Axes) – Matplotlib axis instance.
  • x (list) – A list (or numpy array) of x coordinate values.
  • y (list) – A list (or numpy array) of y coordinate values.
  • color (string) – A matplotlib color string to color the line used to plot the ellipse. Defaults to k (black).
  • width (float) – The width of the plotted line. Defaults to 1.
spatial_efd.spatial_efd.ProcessGeometry(shape)[source]

Method to handle all the geometry processing that may be needed by the rest of the EFD code.

Method which takes a single shape instance from a shapefile eg shp.Reader(‘shapefile.shp’).shapeRecords()[n] where n is the index of the shape within a multipart geometry. This results in the contour, coordinate list and centroid data computed for the input polygon being normalized and returned to the user.

Parameters:shapefile._ShapeRecord – A shapefile object representing the geometry and attributes of a single polygon from a multipart shapefile.
Returns:A tuple containing a list of normalized x coordinates, a list of normalized y coordinates, contour (a list of [x,y] coordinate pairs, normalized about the shape’s centroid) and the normalized coordinate centroid.
Return type:tuple
spatial_efd.spatial_efd.ProcessGeometryNorm(shape)[source]

Method to handle all the geometry processing that may be needed by the rest of the EFD code. This method normalizes the input data to allow spatially distributed data to be plotted in the same cartesian space.

Method which takes a single shape instance from a shapefile eg shp.Reader(‘shapefile.shp’).shapeRecords()[n] where n is the index of the shape within a multipart geometry. This results in the contour, coordinate list and centroid data computed for the input polygon being normalized and returned to the user.

Parameters:shapefile._ShapeRecord – A shapefile object representing the geometry and attributes of a single polygon from a multipart shapefile.
Returns:A tuple containing a list of normalized x coordinates, a list of normalized y coordinates, contour (a list of [x,y] coordinate pairs, normalized about the shape’s centroid) and the normalized coordinate centroid.
Return type:tuple
spatial_efd.spatial_efd.RotateContour(X, Y, rotation, centroid)[source]

Rotates a contour about a point by a given amount expressed in degrees.

Operates by calling rotatePoint() on each x,y pair in turn. X and Y must have the same dimensions.

Parameters:
  • X (list) – A list (or numpy array) of x coordinate values.
  • Y (list) – A list (or numpy array) of y coordinate values.
  • rotation (float) – The angle in degrees for the contour to be rotated by.
  • centroid (tuple) – A tuple containing the x,y coordinates of the centroid to rotate the contour about.
Returns:

A tuple containing a list of x coordinates and a list of y coordinates.

Return type:

tuple

spatial_efd.spatial_efd.SavePlot(ax, harmonic, filename, figformat='png')[source]

Wrapper around the savefig method.

Call this method to add a title identifying the harmonic being plotted, and save the plot to a file. Note that harmonic is simply an int value to be appended to the plot title, it does not select a harmonic to plot.

The figformat argumet can take any value which matplotlib understands, which varies by system. To see a full list suitable for your matplotlib instance, call plt.gcf().canvas.get_supported_filetypes().

Parameters:
  • ax (matplotlib.axes.Axes) – Matplotlib axis instance.
  • harmonic (int) – The harmonic which is being plotted.
  • filename (string) – A complete path and filename, without an extension, for the saved plot.
  • figformat (string) – A string denoting the format to save the figure as. Defaults to png.
spatial_efd.spatial_efd.calculate_dc_coefficients(X, Y)[source]

Compute the dc coefficients, used as the locus when calling inverse_transform().

This code is adapted from the pyefd module. See the original paper for more detail:

Kuhl, FP and Giardina, CR (1982). Elliptic Fourier features of a closed contour. Computer graphics and image processing, 18(3), 236-258.

Parameters:
  • X (list) – A list (or numpy array) of x coordinate values.
  • Y (list) – A list (or numpy array) of y coordinate values.
Returns:

A tuple containing the c and d coefficients.

Return type:

tuple

spatial_efd.spatial_efd.generateShapefile()[source]

Create an empty shapefile to write output into using writeGeometry().

Builds a multipart polygon shapefile with a single attribute, ID, which can be used to reference the written polygons. Does not write any geometry or create any files.

Returns:An empty polygon shapefile instance ready to have data written to it.
Return type:shapefile.Writer
spatial_efd.spatial_efd.getBBoxDimensions(x, y)[source]

Returns the width in the x and y dimensions and the maximum x and y coordinates for the bounding box of a given list of x and y coordinates.

Parameters:
  • x (list) – A list (or numpy array) of x coordinate values.
  • y (list) – A list (or numpy array) of y coordinate values.
Returns:

A four-tuple representing (width in the x direction, width in the y direction, the minimum x coordinate and the minimum y coordinate).

Return type:

tuple

spatial_efd.spatial_efd.inverse_transform(coeffs, locus=(0.0, 0.0), n=300, harmonic=10)[source]

Perform an inverse fourier transform to convert the coefficients back into spatial coordinates.

Implements Kuhl and Giardina method of computing the performing the transform for a specified number of harmonics. This code is adapted from the pyefd module. See the original paper for more detail:

Kuhl, FP and Giardina, CR (1982). Elliptic Fourier features of a closed contour. Computer graphics and image processing, 18(3), 236-258.

Parameters:
  • coeffs (numpy.ndarray) – A numpy array of shape (n, 4) representing the four coefficients for each harmonic computed.
  • locus (tuple) – The x,y coordinates of the centroid of the contour being generated. Use calculate_dc_coefficients() to generate the correct locus for a shape.
  • n (int) – The number of coordinate pairs to compute. A larger value will result in a more complex shape at the expense of increased computational time. Defaults to 300.
  • harmonics (int) – The number of harmonics to be used to generate coordinates, defaults to 10. Must be <= coeffs.shape[0]. Supply a smaller value to produce coordinates for a more generalized shape.
Returns:

A numpy array of shape (harmonics, 4) representing the four coefficients for each harmonic computed.

Return type:

numpy.ndarray

spatial_efd.spatial_efd.normalize_efd(coeffs, size_invariant=True)[source]

Normalize the Elliptical Fourier Descriptor coefficients for a polygon.

Implements Kuhl and Giardina method of normalizing the coefficients An, Bn, Cn, Dn. Performs 3 separate normalizations. First, it makes the data location invariant by re-scaling the data to a common origin. Secondly, the data is rotated with respect to the major axis. Thirdly, the coefficients are normalized with regard to the absolute value of A_1. This code is adapted from the pyefd module. See the original paper for more detail:

Kuhl, FP and Giardina, CR (1982). Elliptic Fourier features of a closed contour. Computer graphics and image processing, 18(3), 236-258.

Parameters:
  • coeffs (numpy.ndarray) – A numpy array of shape (n, 4) representing the four coefficients for each harmonic computed.
  • size_invariant (bool) – Set to True (the default) to perform the third normalization and false to return the data withot this processing step. Set this to False when plotting a comparison between the input data and the Fourier ellipse.
Returns:

A tuple consisting of a numpy.ndarray of shape (harmonics, 4)

representing the four coefficients for each harmonic computed and the rotation in degrees applied to the normalized contour.

Return type:

tuple

spatial_efd.spatial_efd.plotComparison(ax, coeffs, harmonic, x, y, rotation=0.0, color1='k', width1=2.0, color2='r', width2=1.0)[source]

Convenience function which plots an EFD ellipse and a shapefile polygon in the same coordate system.

Warning

If passing in normalized coefficients, they must be created with the size_invariant parameter set to False.

Parameters:
  • ax (matplotlib.axes.Axes) – Matplotlib axis instance.
  • x (list) – A list (or numpy array) of x coordinate values.
  • y (list) – A list (or numpy array) of y coordinate values.
  • rotation (float) – The angle in degrees for the contour to be rotated by. Generated by normalize_efd(). Leave as 0 if non-normalized coefficients are being plotted.
  • harmonic (int) – The number of harmonics to be used to generate coordinates. Must be <= coeffs.shape[0]. Supply a smaller value to produce coordinates for a more generalized shape.
  • color1 (string) – A matplotlib color string to color the line used to plot the Fourier ellipse. Defaults to k (black).
  • width1 (float) – The width of the plotted fourier ellipse. Defaults to 1.
  • color2 (string) – A matplotlib color string to color the line used to plot the shapefile. Defaults to r (red).
  • width2 (float) – The width of the plotted shapefile. Defaults to 1.
spatial_efd.spatial_efd.rotatePoint(point, centerPoint, angle)[source]

Rotates a point counter-clockwise around centerPoint.

The angle to rotate by is supplied in degrees. Code based on: https://gist.github.com/somada141/d81a05f172bb2df26a2c

Parameters:
  • point (tuple) – The point to be rotated, represented as an (x,y) tuple.
  • centerPoint (tuple) – The point to be rotated about, represented as an (x,y) tuple.
  • angle (float) – The angle to rotate point by, in the counter-clockwise direction.
Returns:

A tuple representing the rotated point, (x,y).

Return type:

tuple

spatial_efd.spatial_efd.saveShapefile(filename, shpinstance, prj=None)[source]

Write the data processed by writeGeometry into a shapefile generated by generateShapefile().

If the filename of a shapfile is passed in as template, the spatial projection of the template shapefile will be applied to the new shapefile. Note that this does not carry out any coordinate transforms, it is merely to apply the same spatial reference to the output data as was present in the input data.

Parameters:
  • filename (string) – A complete path and filename, with or without the .shp extenion, to write the final shapefile data to. Must be a path which exists.
  • shape (shapefile.Writer) – A shapefile object representing the geometry and attributes written by writeGeometry().
  • prj (string) – A complete path and filename, with or without the .shp extenion, to the shapefile that data was loaded from initially, Used to copy the spatial projection information to the new file.

Warning

Code does not test if output paths exist, and if files exist they will be overwritten.

spatial_efd.spatial_efd.writeGeometry(coeffs, x, y, harmonic, shpinstance, ID)[source]

Write the results of inverse_transform() to a shapefile.

Will only produce spatially meaningful data if the input coefficients have not been normalized.

Parameters:
  • coeffs (numpy.ndarray) – A numpy array of shape (n, 4) representing the four coefficients for each harmonic computed.
  • x (list) – A list (or numpy array) of x coordinate values.
  • y (list) – A list (or numpy array) of y coordinate values.
  • harmonic (int) – The number of harmonics to be used to generate coordinates. Must be <= coeffs.shape[0]. Supply a smaller value to produce coordinates for a more generalized shape.
  • shpinstance (shapefile.Writer) – A multipart polygon shapefile to write the data to.
  • ID (int) – An integer ID value which will be written as an attribute alongside the geometry.
Returns:

shpinstance with the new geometry appended.