Skip to content

GeoKDTree

GeoKDTree

GeoKDTree(lat: Any, lon: Any)

A great-circle k-NN / radius index over lat/lon points (EPSG:4326).

The single spatial-join primitive shared by find_nearest_stations, multimodal and osm. Built on scipy.spatial.cKDTree over a 3-D unit-sphere embedding, so queries are exact great-circle distances in metres (no flat-earth error near the poles or the antimeridian).

Parameters:

Name Type Description Default
lat array - like

Point coordinates in degrees (EPSG:4326).

required
lon array - like

Point coordinates in degrees (EPSG:4326).

required
See Also

find_nearest_stations : k-nearest queries on this index. stations_near : Radius queries on this index. features_within : Buffer joins on this index.

Source code in src/gbfs_toolkit/spatial/geometry.py
def __init__(self, lat: Any, lon: Any) -> None:
    from scipy.spatial import cKDTree

    self._xyz = _to_xyz(lat, lon)
    self._tree = cKDTree(self._xyz)

query

query(lat: Any, lon: Any, k: int = 1) -> tuple[ndarray, ndarray]

Nearest k indices and great-circle distances (metres) for each query point.

Source code in src/gbfs_toolkit/spatial/geometry.py
def query(self, lat: Any, lon: Any, k: int = 1) -> tuple[np.ndarray, np.ndarray]:
    """Nearest ``k`` indices and great-circle distances (metres) for each query point."""
    chord, idx = self._tree.query(_to_xyz(lat, lon), k=k)
    return _chord_to_arc_m(np.asarray(chord)), np.asarray(idx)

query_radius

query_radius(lat: Any, lon: Any, radius_m: float) -> list[ndarray]

Indices within radius_m great-circle metres of each query point.

Source code in src/gbfs_toolkit/spatial/geometry.py
def query_radius(self, lat: Any, lon: Any, radius_m: float) -> list[np.ndarray]:
    """Indices within ``radius_m`` great-circle metres of each query point."""
    pts = _to_xyz(np.atleast_1d(lat), np.atleast_1d(lon))
    hits = self._tree.query_ball_point(pts, _arc_to_chord_m(radius_m))
    return [np.asarray(h, dtype=int) for h in hits]