Module frechet

Fréchet distances.

Classes Frechet, FrechetDegrees, FrechetRadians, FrechetCosineAndoyerLambert, FrechetCosineForsytheAndoyerLambert, FrechetCosineLaw, FrechetDistanceTo< FrechetEquirectangular, FrechetEuclidean, FrechetExact, FrechetFlatLocal, FrechetFlatPolar, FrechetHaversine, FrechetHubeny, FrechetKarney, FrechetThomas and FrechetVincentys to compute discrete Fréchet distances between two sets of LatLon, NumPy, tuples or other types of points.

Only FrechetDistanceTo -iff used with ellipsoidalKarney.LatLon points- and FrechetKarney requires installation of Charles Karney's geographiclib.

Typical usage is as follows. First, create a Frechet calculator from one set of LatLon points.

f = FrechetXyz(point1s, ...)

Get the discrete Fréchet distance to another set of LatLon points by

t6 = f.discrete(point2s)

Or, use function frechet_ with a proper distance function passed as keyword arguments as follows

t6 = frechet_(point1s, point2s, ..., distance=...).

In both cases, the returned result t6 is a Frechet6Tuple.

For (lat, lon, ...) points in a NumPy array or plain tuples, wrap the points in a Numpy2LatLon respectively Tuple2LatLon instance, more details in the documentation thereof.

For other points, create a Frechet sub-class with the appropriate distance method overloading Frechet.distance as in this example.

>>> from pygeodesy import Frechet, hypot_
>>>
>>> class F3D(Frechet):
>>>     """Custom Frechet example.
>>>     """
>>>     def distance(self, p1, p2):
>>>         return hypot_(p1.x - p2.x, p1.y - p2.y, p1.z - p2.z)
>>>
>>> f3D = F3D(xyz1, ..., units="...")
>>> t6 = f3D.discrete(xyz2)

Transcribed from the original Computing Discrete Fréchet Distance by Eiter, T. and Mannila, H., 1994, April 25, Technical Report CD-TR 94/64, Information Systems Department/Christian Doppler Laboratory for Expert Systems, Technical University Vienna, Austria.

This Frechet.discrete implementation optionally generates intermediate points for each point set separately. For example, using keyword argument fraction=0.5 adds one additional point halfway between each pair of points. Or using fraction=0.1 interpolates nine additional points between each points pair.

The Frechet6Tuple attributes fi1 and/or fi2 will be fractional indices of type float if keyword argument fraction is used. Otherwise, fi1 and/or fi2 are simply type int indices into the respective points set.

For example, fractional index value 2.5 means an intermediate point halfway between points[2] and points[3]. Use function fractional to obtain the intermediate point for a fractional index in the corresponding set of points.

The Fréchet distance was introduced in 1906 by Maurice Fréchet, see reference [6]. It is a measure of similarity between curves that takes into account the location and ordering of the points. Therefore, it is often a better metric than the well-known Hausdorff distance, see the hausdorff module.