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

# Module frechet

Classes Frechet, FrechetDegrees, FrechetRadians, FrechetCosineAndoyerLambert, FrechetCosineForsytheAndoyerLambert, FrechetCosineLaw, FrechetDistanceTo< FrechetEquirectangular, FrechetEuclidean, 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(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: 20.06.17

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` or `radians squared` from `LatLon` points converted from `degrees` to `radians`.
| FrechetCosineAndoyerLambert Compute the `Frechet` distance based on the angular distance in `radians` from function cosineAndoyerLambert_.
| FrechetCosineForsytheAndoyerLambert Compute the `Frechet` distance based on the angular distance in `radians` from function cosineForsytheAndoyerLambert_.
| FrechetCosineLaw Compute the `Frechet` distance based on the angular distance in `radians` from function cosineLaw_.
| FrechetDistanceTo Compute the `Frechet` distance based on the distance from the points' `LatLon.distanceTo` method, conventionally in `meter`.
| 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_.
| FrechetFlatLocal Compute the `Frechet` distance based on the angular distance in `radians squared` like function flatLocal_/hubeny_.
| FrechetFlatPolar Compute the `Frechet` distance based on the angular distance in `radians` from function flatPolar_.
| FrechetHaversine Compute the `Frechet` distance based on the angular distance in `radians` from function haversine_.
| FrechetHubeny Compute the `Frechet` distance based on the angular distance in `radians squared` like function flatLocal_/hubeny_.
| FrechetKarney Compute the `Frechet` distance based on the angular distance in `degrees` from Charles Karney's GeographicLib Geodesic Inverse method.
| FrechetThomas Compute the `Frechet` distance based on the angular distance in `radians` from function thomas_.
| FrechetVincentys Compute the `Frechet` distance based on the angular distance in `radians` from function vincentys_.

Functions
fractional(points, fi, LatLon=None, **LatLon_kwds) 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, **LatLon_kwds) |
Return the point at a given fractional index. Arguments: `points` - The points (`LatLon`[], Numpy2LatLon[], Tuple2LatLon[] or `other`[]). `fi` - The fractional index (`float` or `int`). `LatLon` - Optional class to return the intermediate, fractional point (`LatLon`) or `None`. `LatLon_kwds` - Optional `LatLon` keyword arguments, ignored of `LatLon=None`. Returns: A `LatLon` or if `LatLon` is `None`, a LatLon2Tuple`(lat, lon)` for `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. Arguments: `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: Function frechet_ does not support fractional indices for intermediate `points1` and `points2`.