Module frechet

Fréchet distances.

Classes Frechet, FrechetDegrees, FrechetRadians, 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.