Package pygeodesy :: Module frechet
[frames] | no frames]

Module frechet

Classes Frechet, FrechetDegrees, FrechetRadians, FrechetEquirectangular, FrechetEuclidean, FrechetHaversine, and FrechetVincentys to compute discrete Fréchet distances between two sets of LatLon, NumPy, tuples or other types of points.

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

f = FrechetXyz(points1, ...)

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

t6 = f.discrete(points2)

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

t6 = frechet_(points1, points2, ..., 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.


Version: 19.10.31

Classes
  FrechetError
Fréchet issue.
  Frechet6Tuple
6-Tuple (fd, fi1, fi2, r, n, units) with the discrete Fréchet distance fd, fractional indices fi1 and fi2, the recursion depth r, the number of distances computed n and the name of the distance units.
  Frechet
Frechet base class, requires method Frechet.distance to be overloaded.
  FrechetDegrees
Frechet base class for distances in degrees from LatLon points in degrees.
  FrechetRadians
Frechet base class for distances in radians from LatLon points converted from degrees to radians.
  FrechetEquirectangular
Compute the Frechet distance based on the equirectangular distance (in radians squared) like function equirectangular_.
  FrechetEuclidean
Compute the Frechet distance based on the Euclidean distance (in radians) from function euclidean_.
  FrechetHaversine
Compute the Frechet distance based on the angular Haversine distance (in radians) from function haversine_.
  FrechetVincentys
Compute the Frechet distance based on the angular Vincenty distance (in radians) from function vincentys_.
Functions
 
fractional(points, fi, LatLon=None)
Return the point at a given fractional index.
 
frechet_(points1, points2, distance=None, units='')
Compute the discrete Fréchet distance between two paths given as sets of points.
Function Details

fractional(points, fi, LatLon=None)

 

Return the point at a given fractional index.

Parameters:
  • points - The points (LatLon[], Numpy2LatLon[], Tuple2LatLon[] or other[]).
  • fi - The fractional index (float or int).
  • LatLon - Optional (sub-)class to return the intermediate point (LatLon) or None.
Returns:
A LatLon or a LatLon2Tuple(lat, lon) if LatLon is None with points[fi] if fractional index fi is int, otherwise the intermediate point between points[int(fi)] and points[int(fi)+1] for float fractional index fi.
Raises:
  • IndexError - Fractional index fi invalid or points not subscriptable.

frechet_(points1, points2, distance=None, units='')

 

Compute the discrete Fréchet distance between two paths given as sets of points.

Parameters:
  • points1 - First set of points (LatLon[], Numpy2LatLon[], Tuple2LatLon[] or other[]).
  • points2 - Second set of points (LatLon[], Numpy2LatLon[], Tuple2LatLon[] or other[]).
  • distance - Callable returning the distance between a points1 and a points2 point (signature (point1, point2)).
  • units - Optional, name of the distance units (str).
Returns:
A Frechet6Tuple(fd, fi1, fi2, r, n, units) where fi1 and fi2 are type int indices into points1 respectively points2.
Raises:

Note: Keyword fraction, intermediate points1 and points2 and fractional indices are not supported in this frechet_ function.