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.09.16

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: `FrechetError` - Insufficient number of `points1` or `points2`. `RecursionError` - Recursion depth exceeded, see sys.getrecursionlimit(). `TypeError` - If `distance` is not a callable. Note: Keyword `fraction`, intermediate `points1` and `points2` and fractional indices are not supported in this frechet_ function.