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

# Module hausdorff

Hausdorff distances.

Classes Hausdorff, HausdorffDegrees, HausdorffRadians, HausdorffCosineAndoyerLambert, HausdorffCosineForsytheAndoyerLambert, HausdorffCosineLaw, HausdorffDistanceTo, HausdorffEquirectangular, HausdorffEuclidean, HausdorffFlatLocal, HausdorffFlatPolar, HausdorffHaversine, HausdorffHubeny, HausdorffKarney, HausdorffThomas and HausdorffVincentys to compute Hausdorff distances between two sets of `LatLon`, `NumPy`, `tuples` or other types of points.

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

Typical usage is as follows. First, create a `Hausdorff` calculator from a given set of `LatLon` points, called the `model` or `template` points.

`h = HausdorffXyz(points1, ...)`

Get the `directed` or `symmetric` Hausdorff distance to a second set of `LatLon` points, named the `target` points, by using

`t6 = h.directed(points2)`

respectively

`t6 = h.symmetric(points2)`.

Or, use function `hausdorff_` with a proper `distance` function and optionally a `point` function passed as keyword arguments as follows

`t6 = hausdorff_(points1, points2, ..., distance=..., point=...)`.

In all cases, the returned result `t6` is a Hausdorff6Tuple.

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 Hausdorff sub-class with the appropriate `distance` method overloading Hausdorff.distance and optionally a `point` method overriding Hausdorff.point as the next example.

    >>> from pygeodesy import Hausdorff, hypot_
    >>>
    >>> class H3D(Hausdorff):
    >>>     """Custom Hausdorff example.
    >>>     """
    >>>     def distance(self, p1, p2):
    >>>         return hypot_(p1.x - p2.x, p1.y - p2.y, p1.z - p2.z)
    >>>
    >>> h3D = H3D(xyz1, ..., units="...")
    >>> d6 = h3D.directed(xyz2)

Transcribed from the original SciPy Directed Hausdorff Code version 0.19.0, Copyright (C) Tyler Reddy, Richard Gowers, and Max Linke, 2016, distributed under the same BSD license as SciPy, including `early breaking` and `random sampling` as in Abdel Aziz Taha, Allan Hanbury "An Efficient Algorithm for Calculating the Exact Hausdorff Distance", IEEE Trans. Pattern Analysis Machine Intelligence (PAMI), vol 37, no 11, pp 2153-2163, Nov 2015.

Version: 21.06.01

Classes
| HausdorffError Hausdorff issue.
| Hausdorff Hausdorff base class, requires method Hausdorff.distance to be overloaded.
| HausdorffDegrees Hausdorff base class for distances from `LatLon` points in `degrees`.
| HausdorffRadians Hausdorff base class for distances from `LatLon` points converted from `degrees` to `radians`.
| HausdorffCosineAndoyerLambert Compute the `Hausdorff` distance based on the angular distance in `radians` from function cosineAndoyerLambert_.
| HausdorffCosineForsytheAndoyerLambert Compute the `Hausdorff` distance based on the angular distance in `radians` from function cosineForsytheAndoyerLambert_.
| HausdorffCosineLaw Compute the `Hausdorff` distance based on the angular distance in `radians` from function cosineLaw_.
| HausdorffDistanceTo Compute the `Hausdorff` distance based on the distance from the points' `LatLon.distanceTo` method, conventionally in `meter`.
| HausdorffEquirectangular Compute the `Hausdorff` distance based on the `equirectangular` distance in `radians squared` like function equirectangular_.
| HausdorffEuclidean Compute the `Hausdorff` distance based on the `Euclidean` distance in `radians` from function euclidean_.
| HausdorffExact Compute the `Hausdorff` distance based on the angular distance in `degrees` from method GeodesicExact`.Inverse`.
| HausdorffFlatLocal Compute the `Hausdorff` distance based on the angular distance in `radians squared` like function flatLocal_/hubeny_.
| HausdorffFlatPolar Compute the `Hausdorff` distance based on the angular distance in `radians` from function flatPolar_.
| HausdorffHaversine Compute the `Hausdorff` distance based on the angular distance in `radians` from function haversine_.
| HausdorffHubeny Compute the `Hausdorff` distance based on the angular distance in `radians squared` like function flatLocal_/hubeny_.
| HausdorffKarney Compute the `Hausdorff` distance based on the angular distance in `degrees` from Karney's geographiclib Geodesic Inverse method.
| HausdorffThomas Compute the `Hausdorff` distance based on the angular distance in `radians` from function thomas_.
| HausdorffVincentys Compute the `Hausdorff` distance based on the angular distance in `radians` from function vincentys_.
| Hausdorff6Tuple 6-Tuple `(hd, i, j, mn, md, units)` with the Hausdorff distance `hd`, indices `i` and `j`, the total count `mn`, the `mean Hausdorff` distance `md` and the class or name of both distance `units`.

Functions
hausdorff_(model, target, both=False, early=True, seed=None, units='', distance=None, point=<function _point at 0x7f882ce66c50>) Compute the `directed` or `symmetric` Hausdorff distance between 2 sets of points with or without early breaking and random sampling. |
randomrangenerator(seed) Return a `seed`ed random range function generator. |

Variables
| __all__ = `_ALL_LAZY.hausdorff`

Function Details

### hausdorff_ (model, target, both=False, early=True, seed=None, units='', distance=None, point=<function _point at 0x7f882ce66c50>) |
Compute the `directed` or `symmetric` Hausdorff distance between 2 sets of points with or without early breaking and random sampling. Arguments: `model` - First set of points (`LatLon`[], `Numpy2LatLon`[], `Tuple2LatLon`[] or `other`[]). `target` - Second set of points (`LatLon`[], `Numpy2LatLon`[], `Tuple2LatLon`[] or `other`[]). `both` - Return the `directed` (forward only) or the `symmetric` (combined forward and reverse) `Hausdorff` distance (`bool`). `early` - Enable or disable early breaking (`bool`). `seed` - Random sampling seed (`any`) or `None`, `0` or `False` for no random sampling. `units` - Optional, the distance units (`Unit` or `str`). `distance` - Callable returning the distance between a `model` and `target` point (signature `(point1, point2)`). `point` - Callable returning the `model` or `target` point suitable for `distance` (signature `(point)`). Returns: A Hausdorff6Tuple`(hd, i, j, mn, md, units)`. Raises: `HausdorffError` - Insufficient number of `model` or `target` points. `TypeError` - If `distance` or `point` is not callable.

### randomrangenerator (seed) |
Return a `seed`ed random range function generator. Arguments: `seed` - Initial, internal Random state (`hashable` or `None`). Returns: A function to generate random ranges. Note: Random with `seed=None` seeds from the current time or from a platform-specific randomness source, if available. Example:
    >>> rrange = randomrangenerator('R')
    >>> for r in rrange(n):
    >>>    ...  # r is random in 0..n-1