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

# Module hausdorff

Classes Hausdorff, HausdorffDegrees, HausdorffRadians, HausdorffEquirectangular, HausdorffEuclidean, HausdorffHaversine, HausdorffKarney and HausdorffVincentys to compute Hausdorff distances between two sets of `LatLon`, `NumPy`, `tuples` or other types of points.

Only HausdorffKarney depends on an external package, 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: 20.03.23

Classes
| HausdorffError Hausdorff issue.
| 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 name of the distance `units`.
| Hausdorff Hausdorff base class, requires method Hausdorff.distance to be overloaded.
| HausdorffDegrees Hausdorff base class for distances in `degrees` from `LatLon` points in `degrees`.
| HausdorffRadians Hausdorff base class for distances in `radians` from `LatLon` points converted from `degrees` to `radians`.
| 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_.
| HausdorffHaversine Compute the `Hausdorff` distance based on the angular `Haversine` distance (in radians) from function haversine_.
| HausdorffKarney Compute the `Hausdorff` distance based on the angular distance (in degrees) from Charles Karney's GeographicLib Geodesic Inverse method.
| HausdorffVincentys Compute the `Hausdorff` distance based on the angular `Vincenty` distance (in radians) from function vincentys_.

Functions
hausdorff_(model, target, both=False, early=True, seed=None, units=`'````'`, distance=None, point=<function _point at 0x10c728bd0>) 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. |

Function Details

### hausdorff_(model, target, both=False, early=True, seed=None, units=`'````'`, distance=None, point=<function _point at 0x10c728bd0>) |
Compute the `directed` or `symmetric` Hausdorff distance between 2 sets of points with or without early breaking and random sampling. Parameters: `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, name of the distance units (`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. Parameters: `seed` - Initial, internal Random state (`hashable`). Returns: A function to generatore random ranges. Note: Random `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