API Reference

Complete API reference for all rapidgeo modules.

rapidgeo

rapidgeo: Fast geographic and planar distance calculations

class rapidgeo.LngLat(lng, lat)

Geographic coordinate representing longitude and latitude in decimal degrees.

Coordinates use longitude, latitude ordering (x, y convention). All functions expect coordinates in decimal degrees.

Examples

>>> from rapidgeo import LngLat
>>> sf = LngLat(-122.4194, 37.7749)  # San Francisco
>>> print(sf.lng, sf.lat)
-122.4194 37.7749

lat

Latitude in decimal degrees.

Returns:: Latitude coordinate (-90 to +90)
Return type:: float

lng

Longitude in decimal degrees.

Returns:: Longitude coordinate (-180 to +180)
Return type:: float

rapidgeo.distance

Core distance calculation module.

Distance calculation submodule

class rapidgeo.distance.LngLat(lng, lat)

Geographic coordinate representing longitude and latitude in decimal degrees.

Coordinates use longitude, latitude ordering (x, y convention). All functions expect coordinates in decimal degrees.

Examples

>>> from rapidgeo import LngLat
>>> sf = LngLat(-122.4194, 37.7749)  # San Francisco
>>> print(sf.lng, sf.lat)
-122.4194 37.7749

lat

Latitude in decimal degrees.

Returns:: Latitude coordinate (-90 to +90)
Return type:: float

lng

Longitude in decimal degrees.

Returns:: Longitude coordinate (-180 to +180)
Return type:: float

rapidgeo.distance.geo

Geographic distance functions (Haversine, Vincenty).

Geographic distance functions

rapidgeo.distance.geo.haversine(a, b)

Calculate the great-circle distance between two points using the Haversine formula.

Uses spherical Earth approximation for fast distance calculations. Accurate to within 0.5% for distances under 1000km.

Parameters:

a (LngLat) – First coordinate
b (LngLat) – Second coordinate

Returns:

Distance in meters

Return type:

float

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.distance.geo import haversine
>>> sf = LngLat(-122.4194, 37.7749)
>>> nyc = LngLat(-74.0060, 40.7128)
>>> distance = haversine(sf, nyc)
>>> print(f"Distance: {distance/1000:.0f} km")
Distance: 4135 km

rapidgeo.distance.geo.haversine_km(a, b)

Calculate distance in kilometers using the Haversine formula.

Convenient wrapper that returns distance in kilometers instead of meters. Fast spherical approximation accurate to within 0.5% for distances under 1000km.

Parameters:

a (LngLat) – First coordinate
b (LngLat) – Second coordinate

Returns:

Distance in kilometers

Return type:

float

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.distance.geo import haversine_km
>>> sf = LngLat(-122.4194, 37.7749)
>>> nyc = LngLat(-74.0060, 40.7128)
>>> distance = haversine_km(sf, nyc)
>>> print(f"Distance: {distance:.0f} km")
Distance: 4135 km

rapidgeo.distance.geo.haversine_miles(a, b)

Calculate distance in statute miles using the Haversine formula.

Convenient wrapper that returns distance in statute miles. Fast spherical approximation accurate to within 0.5% for distances under 1000km.

Parameters:

a (LngLat) – First coordinate
b (LngLat) – Second coordinate

Returns:

Distance in statute miles

Return type:

float

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.distance.geo import haversine_miles
>>> sf = LngLat(-122.4194, 37.7749)
>>> nyc = LngLat(-74.0060, 40.7128)
>>> distance = haversine_miles(sf, nyc)
>>> print(f"Distance: {distance:.0f} miles")
Distance: 2570 miles

rapidgeo.distance.geo.haversine_nautical(a, b)

Calculate distance in nautical miles using the Haversine formula.

Convenient wrapper that returns distance in nautical miles. Fast spherical approximation accurate to within 0.5% for distances under 1000km.

Parameters:

a (LngLat) – First coordinate
b (LngLat) – Second coordinate

Returns:

Distance in nautical miles

Return type:

float

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.distance.geo import haversine_nautical
>>> sf = LngLat(-122.4194, 37.7749)
>>> nyc = LngLat(-74.0060, 40.7128)
>>> distance = haversine_nautical(sf, nyc)
>>> print(f"Distance: {distance:.0f} nm")
Distance: 2232 nm

rapidgeo.distance.geo.bearing(from_point, to_point)

Calculate the initial bearing from one point to another.

Returns the compass bearing (azimuth) in degrees from the first point to the second point along the great circle path.

Parameters:

from_point (LngLat) – Starting coordinate
to_point (LngLat) – Destination coordinate

Returns:

Initial bearing in degrees (0-360°, where 0° is North)

Return type:

float

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.distance.geo import bearing
>>> sf = LngLat(-122.4194, 37.7749)
>>> nyc = LngLat(-74.0060, 40.7128)
>>> bearing_deg = bearing(sf, nyc)
>>> print(f"Bearing: {bearing_deg:.1f}°")
Bearing: 65.4°

rapidgeo.distance.geo.destination(origin, distance_m, bearing_deg)

Calculate the destination point given origin, distance, and bearing.

Uses spherical trigonometry to find the point that is at the specified distance and bearing from the origin point.

Parameters:

origin (LngLat) – Starting coordinate
distance_m (float) – Distance to travel in meters
bearing_deg (float) – Compass bearing in degrees (0-360°, where 0° is North)

Returns:

Destination coordinate

Return type:

LngLat

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.distance.geo import destination
>>> london = LngLat(-0.1278, 51.5074)
>>> dest = destination(london, 100000, 90)  # 100km due east
>>> print(f"Destination: {dest.lng:.4f}, {dest.lat:.4f}")
Destination: 1.2644, 51.5074

rapidgeo.distance.geo.vincenty_distance(a, b)

Calculate high-precision distance using Vincenty’s formulae for the WGS84 ellipsoid.

Provides millimeter accuracy for geodesic distances but slower than Haversine. May fail for nearly antipodal points (opposite sides of Earth).

Parameters:

a (LngLat) – First coordinate
b (LngLat) – Second coordinate

Returns:

Distance in meters with millimeter precision

Return type:

float

Raises:

ValueError – If the algorithm fails to converge for antipodal points

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.distance.geo import vincenty_distance
>>> sf = LngLat(-122.4194, 37.7749)
>>> nyc = LngLat(-74.0060, 40.7128)
>>> distance = vincenty_distance(sf, nyc)
>>> print(f"Precise distance: {distance:.1f} m")
Precise distance: 4134785.2 m

rapidgeo.distance.euclid

Planar/Euclidean distance functions.

Euclidean distance functions

rapidgeo.distance.euclid.euclid(a, b)

Calculate Euclidean distance between coordinates treating them as points on a flat plane.

Uses the Pythagorean theorem: d = √[(x₂-x₁)² + (y₂-y₁)²] Fast but only accurate for small geographic areas or projected coordinates.

Parameters:

a (LngLat) – First coordinate
b (LngLat) – Second coordinate

Returns:

Euclidean distance in decimal degrees

Return type:

float

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.distance.euclid import euclid
>>> p1 = LngLat(0.0, 0.0)
>>> p2 = LngLat(1.0, 1.0)
>>> distance = euclid(p1, p2)
>>> print(f"Distance: {distance:.4f} degrees")
Distance: 1.4142 degrees

rapidgeo.distance.euclid.squared(a, b)

Calculate squared Euclidean distance (avoids expensive square root).

Useful for distance comparisons where you don’t need the actual distance value. Faster than euclid() when you only need to compare relative distances.

Parameters:

a (LngLat) – First coordinate
b (LngLat) – Second coordinate

Returns:

Squared distance in decimal degrees²

Return type:

float

Examples

>>> from rapidgeo.distance.euclid import squared
>>> from rapidgeo import LngLat
>>> p1 = LngLat(0.0, 0.0)
>>> p2 = LngLat(3.0, 4.0)
>>> dist_sq = squared(p1, p2)
>>> print(f"Squared distance: {dist_sq}")
Squared distance: 25.0

rapidgeo.distance.euclid.point_to_segment(point, seg_start, seg_end)

Calculate the minimum Euclidean distance from a point to a line segment.

Projects the point onto the line segment and returns the shortest distance. Uses flat-plane geometry - not suitable for long geographic distances.

Parameters:

point (LngLat) – Point to measure from
seg_start (LngLat) – Start of line segment
seg_end (LngLat) – End of line segment

Returns:

Minimum distance in decimal degrees

Return type:

float

Examples

>>> from rapidgeo.distance.euclid import point_to_segment
>>> from rapidgeo import LngLat
>>> point = LngLat(1.0, 1.0)
>>> seg_start = LngLat(0.0, 0.0)
>>> seg_end = LngLat(2.0, 0.0)
>>> dist = point_to_segment(point, seg_start, seg_end)
>>> print(f"Distance to segment: {dist:.1f}")
Distance to segment: 1.0

rapidgeo.distance.euclid.point_to_segment_squared(point, seg_start, seg_end)

Calculate squared distance from point to line segment (avoids square root).

Faster version of point_to_segment() when you only need relative distances. Useful for finding the closest segment among many options.

Parameters:

point (LngLat) – Point to measure from
seg_start (LngLat) – Start of line segment
seg_end (LngLat) – End of line segment

Returns:

Squared minimum distance in decimal degrees²

Return type:

float

Examples

>>> from rapidgeo.distance.euclid import point_to_segment_squared
>>> from rapidgeo import LngLat
>>> point = LngLat(0.0, 1.0)
>>> seg_start = LngLat(0.0, 0.0)
>>> seg_end = LngLat(1.0, 0.0)
>>> dist_sq = point_to_segment_squared(point, seg_start, seg_end)
>>> print(f"Squared distance: {dist_sq}")
Squared distance: 1.0

rapidgeo.distance.batch

Batch distance operations.

Batch distance and bearing functions

rapidgeo.distance.batch.pairwise_haversine(points)

Calculate haversine distances between consecutive points in a path.

Computes the great-circle distance between each pair of consecutive points using the Haversine formula. Returns a list of distances with length len(points) - 1.

Parameters:: points (list[LngLat]) – List of coordinates representing a path
Returns:: Distances in meters between consecutive points. Length is len(points) - 1.
Return type:: list[float]

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.distance.batch import pairwise_haversine
>>> path = [
...     LngLat(-122.4194, 37.7749),  # San Francisco
...     LngLat(-87.6298, 41.8781),   # Chicago
...     LngLat(-74.0060, 40.7128),   # New York
... ]
>>> distances = pairwise_haversine(path)
>>> [f"{d/1000:.0f} km" for d in distances]
['2984 km', '1145 km']

Notes

Uses spherical Earth approximation (accurate to ±0.5% for distances <1000km)
Releases GIL during computation
For high precision, use Vincenty-based functions

rapidgeo.formats

Coordinate format detection and conversion utilities.

Coordinate format detection and conversion utilities

rapidgeo.formats.coords_to_lnglat(coords)

Converts Python coordinate data to standardized LngLat format.

Automatically detects the input format and converts coordinate data to the internal LngLat representation used throughout the RapidGeo system. All coordinates are normalized to longitude/latitude ordering.

# Arguments

coords - Python coordinate data in one of the supported formats

# Returns

A vector of LngLat objects representing the coordinates in longitude/latitude order.

# Errors

PyTypeError - If the input is not a list or cannot be converted
PyValueError - If coordinate data is malformed (e.g., wrong number of elements)
PyKeyError - If GeoJSON objects are missing required keys

# Format Detection

The function automatically detects the input format by inspecting the first element: - If the first element is a number, treats input as flat array format - If the first element is a dictionary with “coordinates” key, treats as GeoJSON - Otherwise, treats as tuple/list format

# Examples

Tuple Format:

coords = [(1.0, 2.0), (3.0, 4.0)]
result = coords_to_lnglat(coords)  # Returns [LngLat(1.0, 2.0), LngLat(3.0, 4.0)]

Flat Array Format:

coords = [1.0, 2.0, 3.0, 4.0]  # lng1, lat1, lng2, lat2
result = coords_to_lnglat(coords)  # Returns [LngLat(1.0, 2.0), LngLat(3.0, 4.0)]

GeoJSON-like Format:

coords = [
    {"coordinates": [1.0, 2.0]},
    {"coordinates": [3.0, 4.0]}
]
result = coords_to_lnglat(coords)  # Returns [LngLat(1.0, 2.0), LngLat(3.0, 4.0)]

# Performance

The function performs minimal format detection overhead and delegates bulk processing to optimized Rust core functions. Conversion is done in-place where possible to minimize memory allocations.

rapidgeo.polyline

Google Polyline Algorithm encoding and decoding.

Google Polyline Algorithm encoding/decoding with simplification support

rapidgeo.polyline.encode(coordinates, precision=5)

Encode a sequence of coordinates into a Google Polyline Algorithm string.

Compresses coordinate sequences using variable-length encoding and delta compression. Commonly used for GPS tracks, routes, and mapping applications.

Parameters:

coordinates (List[LngLat]) – Sequence of coordinates to encode
precision (int, optional) – Decimal places of precision (1-11). Defaults to 5. - 5: ~1 meter accuracy (standard) - 6: ~10 centimeter accuracy (high precision)

Returns:

Encoded polyline string

Return type:

str

Raises:

ValueError – If precision is invalid or coordinates cause overflow

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.polyline import encode
>>> coords = [LngLat(-120.2, 38.5), LngLat(-120.95, 40.7)]
>>> polyline = encode(coords, 5)
>>> print(polyline)
'_p~iF~ps|U_ulLnnqC_mqNvxq`@'

rapidgeo.polyline.decode(polyline, precision=5)

Decode a Google Polyline Algorithm string back into coordinates.

Reverses the polyline encoding process to reconstruct the original coordinate sequence. The precision must match what was used during encoding.

Parameters:

polyline (str) – Encoded polyline string
precision (int, optional) – Decimal places used during encoding. Defaults to 5.

Returns:

Decoded coordinate sequence

Return type:

List[LngLat]

Raises:

ValueError – If polyline is malformed or precision is invalid

Examples

>>> from rapidgeo.polyline import decode
>>> polyline = '_p~iF~ps|U_ulLnnqC_mqNvxq`@'
>>> coords = decode(polyline, 5)
>>> print(f"First coord: {coords[0].lng}, {coords[0].lat}")
First coord: -120.2, 38.5

rapidgeo.polyline.encode_simplified(coordinates, tolerance_m, method='great_circle', precision=5)

Encode coordinates with line simplification into a Google Polyline string.

Combines Douglas-Peucker line simplification with polyline encoding in one step. This reduces coordinate count while maintaining essential shape, then compresses the result using Google’s polyline algorithm.

Parameters:

coordinates (List[LngLat]) – Sequence of coordinates to simplify and encode
tolerance_m (float) – Simplification tolerance in meters. Higher values = more simplification.
method (str, optional) – Distance calculation method. Defaults to “great_circle”. - “great_circle”: Accurate geographic distance (recommended) - “planar”: Fast approximation for small areas - “euclidean”: Fastest, treat coordinates as flat plane
precision (int, optional) – Decimal places of precision (1-11). Defaults to 5.

Returns:

Simplified and encoded polyline string

Return type:

str

Raises:

ValueError – If tolerance is negative, method is unknown, or precision is invalid

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.polyline import encode_simplified
>>> # GPS track with noise - simplify to 10 meter tolerance
>>> track = [LngLat(-120.2, 38.5), LngLat(-120.201, 38.501), LngLat(-120.95, 40.7)]
>>> simplified = encode_simplified(track, tolerance_m=10.0)
>>> # Result has fewer points than original track

rapidgeo.polyline.simplify_polyline(polyline, tolerance_m, method='great_circle', precision=5)

Simplify an already-encoded Google Polyline string.

Decodes a polyline string, applies Douglas-Peucker simplification, then re-encodes it. Useful when you have polyline data from external sources that needs simplification without converting back to coordinate arrays.

Parameters:

polyline (str) – Encoded polyline string to simplify
tolerance_m (float) – Simplification tolerance in meters. Higher values = more simplification.
method (str, optional) – Distance calculation method. Defaults to “great_circle”. - “great_circle”: Accurate geographic distance (recommended) - “planar”: Fast approximation for small areas - “euclidean”: Fastest, treat coordinates as flat plane
precision (int, optional) – Decimal places of precision (1-11). Defaults to 5.

Returns:

Simplified polyline string with same precision as input

Return type:

str

Raises:

ValueError – If polyline is malformed, tolerance is negative, method is unknown, or precision is invalid

Examples

>>> from rapidgeo.polyline import simplify_polyline
>>> # Simplify detailed polyline from mapping API to reduce size
>>> detailed = '_p~iF~ps|U_ulLnnqC_c~vLvxq`@'
>>> simplified = simplify_polyline(detailed, tolerance_m=50.0)
>>> # Result string is shorter with fewer encoded points

rapidgeo.polyline.encode_batch(coordinates_list, precision=5)

Encode multiple sequences of coordinates into Google Polyline Algorithm strings.

Batch processing version of encode() that efficiently handles multiple coordinate sequences in parallel. Useful for encoding many routes, tracks, or boundaries at once.

Parameters:

coordinates_list (List[List[LngLat]]) – List of coordinate sequences to encode
precision (int, optional) – Decimal places of precision (1-11). Defaults to 5. - 5: ~1 meter accuracy (standard) - 6: ~10 centimeter accuracy (high precision)

Returns:

List of encoded polyline strings, one for each input sequence

Return type:

List[str]

Raises:

ValueError – If precision is invalid or any coordinates cause overflow

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.polyline import encode_batch
>>> routes = [
...     [LngLat(-120.2, 38.5), LngLat(-120.95, 40.7)],
...     [LngLat(-121.0, 39.0), LngLat(-122.0, 40.0)]
... ]
>>> polylines = encode_batch(routes, 5)
>>> len(polylines)
2

rapidgeo.polyline.decode_batch(polylines, precision=5)

Decode multiple Google Polyline Algorithm strings back into coordinate sequences.

Batch processing version of decode() that efficiently handles multiple polyline strings in parallel. Useful for decoding many encoded routes, tracks, or boundaries at once.

Parameters:

polylines (List[str]) – List of encoded polyline strings to decode
precision (int, optional) – Decimal places used during encoding. Defaults to 5. Must match the precision used when the polylines were originally encoded.

Returns:

List of decoded coordinate sequences, one for each input polyline

Return type:

List[List[LngLat]]

Raises:

ValueError – If any polyline is malformed or precision is invalid

Examples

>>> from rapidgeo.polyline import decode_batch
>>> polylines = [
...     '_p~iF~ps|U_ulLnnqC_mqNvxq`@',
...     'u{~vFvyys@fS]'
... ]
>>> routes = decode_batch(polylines, 5)
>>> len(routes)
2
>>> len(routes[0])  # Number of points in first route
3

rapidgeo.polyline.encode_simplified_batch(coordinates_list, tolerance_m, method='great_circle', precision=5)

Encode multiple coordinate sequences with line simplification into Google Polyline strings.

Batch processing version of encode_simplified() that efficiently handles multiple coordinate sequences in parallel. Combines Douglas-Peucker line simplification with polyline encoding for each sequence. Useful for processing many GPS tracks, routes, or boundaries with noise reduction.

Parameters:

coordinates_list (List[List[LngLat]]) – List of coordinate sequences to simplify and encode
tolerance_m (float) – Simplification tolerance in meters. Higher values = more simplification. Applied uniformly to all sequences in the batch.
method (str, optional) – Distance calculation method. Defaults to “great_circle”. - “great_circle”: Accurate geographic distance (recommended) - “planar”: Fast approximation for small areas - “euclidean”: Fastest, treat coordinates as flat plane
precision (int, optional) – Decimal places of precision (1-11). Defaults to 5.

Returns:

List of simplified and encoded polyline strings, one for each input sequence

Return type:

List[str]

Raises:

ValueError – If tolerance is negative, method is unknown, or precision is invalid

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.polyline import encode_simplified_batch
>>> # Multiple GPS tracks with noise - simplify all to 10 meter tolerance
>>> tracks = [
...     [LngLat(-120.2, 38.5), LngLat(-120.201, 38.501), LngLat(-120.95, 40.7)],
...     [LngLat(-121.0, 39.0), LngLat(-121.001, 39.001), LngLat(-122.0, 40.0)]
... ]
>>> simplified = encode_simplified_batch(tracks, tolerance_m=10.0)
>>> len(simplified)
2
>>> # Each result has fewer points than original tracks

rapidgeo.polyline.encode_column(coordinates_column, precision=5)

Encode an entire pandas column/Series of coordinates to polylines

This is the fastest way to convert coordinate data to polylines. Takes a pandas Series or any iterable of coordinate arrays and returns all polylines in one shot. Uses Rayon parallelization internally for maximum performance.

Parameters:

coordinates_column – pandas Series, list, or iterable of coordinate arrays
precision (int, optional) – Decimal places of precision (1-11). Defaults to 5.

Returns:

List of encoded polyline strings, one per input coordinate array

Return type:

List[str]

Examples

>>> df['polylines'] = rapidgeo.polyline.encode_column(df['coordinates'])
>>> # processes entire column at once with parallel encoding

rapidgeo.simplify

Line simplification using Douglas-Peucker algorithm.

Polyline simplification submodule

rapidgeo.simplify.douglas_peucker(points, tolerance_m, method='great_circle', return_mask=False)

rapidgeo.simplify.batch

Batch simplification operations.

Batch simplification operations

rapidgeo.simplify.batch.simplify_multiple(polylines, tolerance_m, method='great_circle', return_masks=False)

rapidgeo.similarity

Curve similarity measures (Fréchet and Hausdorff distance).

Curve similarity measures for geographic polylines.

This module provides algorithms for measuring the similarity between two polygonal curves:

Fréchet distance: Considers point ordering along curves, ideal for trajectories
Hausdorff distance: Maximum distance between point sets, order-independent

All functions work with sequences of LngLat coordinates and return distances in meters.

rapidgeo.similarity.frechet

Discrete Fréchet distance implementation.

The Fréchet distance measures similarity between polygonal curves while considering the ordering of points along each curve. Often described as the “dog walking” distance.

rapidgeo.similarity.frechet.discrete_frechet(polyline_a, polyline_b)

Calculate discrete Fréchet distance between two polylines.

The Fréchet distance measures the similarity between two polygonal curves. It considers the ordering of points along each curve, making it suitable for comparing trajectories, paths, or time-series data.

This implementation uses dynamic programming for optimal alignment between curves. Uses Haversine distance for point-to-point calculations.

Parameters:

polyline_a (List[LngLat]) – First polyline as list of coordinates
polyline_b (List[LngLat]) – Second polyline as list of coordinates

Returns:

Fréchet distance in meters

Return type:

float

Raises:

ValueError – If either polyline is empty

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.similarity.frechet import discrete_frechet
>>> path1 = [LngLat(0.0, 0.0), LngLat(1.0, 0.0)]
>>> path2 = [LngLat(0.0, 1.0), LngLat(1.0, 1.0)]
>>> distance = discrete_frechet(path1, path2)

rapidgeo.similarity.frechet.discrete_frechet_with_threshold(polyline_a, polyline_b, threshold)

Calculate discrete Fréchet distance with early termination threshold.

Optimized version that can terminate early if the distance exceeds a threshold. Useful when you only need to know if curves are within a certain similarity bound.

Parameters:

polyline_a (List[LngLat]) – First polyline as list of coordinates
polyline_b (List[LngLat]) – Second polyline as list of coordinates
threshold (float) – Maximum distance threshold in meters

Returns:

Fréchet distance in meters, or value > threshold if exceeded

Return type:

float

Raises:

ValueError – If either polyline is empty

Examples

>>> from rapidgeo.similarity.frechet import discrete_frechet_with_threshold
>>> distance = discrete_frechet_with_threshold(path1, path2, 1000.0)

rapidgeo.similarity.hausdorff

Hausdorff distance implementation.

The Hausdorff distance measures the maximum distance between any point in one set and the closest point in another set. Order-independent similarity measure.

rapidgeo.similarity.hausdorff.hausdorff(polyline_a, polyline_b)

Calculate Hausdorff distance between two polylines.

The Hausdorff distance measures the maximum distance between any point in one set and the closest point in another set. Unlike Fréchet distance, it doesn’t consider the ordering of points along curves.

This is the symmetric version: max(directed_hausdorff(A,B), directed_hausdorff(B,A)). Uses Haversine distance for point-to-point calculations.

Parameters:

polyline_a (List[LngLat]) – First polyline as list of coordinates
polyline_b (List[LngLat]) – Second polyline as list of coordinates

Returns:

Hausdorff distance in meters

Return type:

float

Raises:

ValueError – If either polyline is empty

Examples

>>> from rapidgeo import LngLat
>>> from rapidgeo.similarity.hausdorff import hausdorff
>>> points1 = [LngLat(0.0, 0.0), LngLat(1.0, 0.0)]
>>> points2 = [LngLat(0.0, 1.0), LngLat(1.0, 1.0)]
>>> distance = hausdorff(points1, points2)

rapidgeo.similarity.hausdorff.hausdorff_with_threshold(polyline_a, polyline_b, threshold)

Calculate Hausdorff distance with early termination threshold.

Optimized version that can terminate early if the distance exceeds a threshold. Useful for filtering point sets based on similarity bounds.

Parameters:

polyline_a (List[LngLat]) – First polyline as list of coordinates
polyline_b (List[LngLat]) – Second polyline as list of coordinates
threshold (float) – Maximum distance threshold in meters

Returns:

Hausdorff distance in meters, or value > threshold if exceeded

Return type:

float

Raises:

ValueError – If either polyline is empty

Examples

>>> from rapidgeo.similarity.hausdorff import hausdorff_with_threshold
>>> distance = hausdorff_with_threshold(points1, points2, 500.0)