Index & join¶

Spatial joins and nearest-neighbor queries over geometry columns.

join ¶

Accepted call forms

join(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, predicate: Literal['dwithin'], distance: float, unit: Literal['planar', 'meters'] | None = None) -> tuple[ndarray[tuple[int], dtype[int64]], ndarray[tuple[int], dtype[int64]]]

join(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, predicate: Literal['intersects', 'contains', 'contains_properly', 'covers', 'within', 'covered_by', 'equals', 'touches', 'crosses', 'overlaps'] = 'intersects', distance: None = None, unit: Literal['planar', 'meters'] | None = None) -> tuple[ndarray[tuple[int], dtype[int64]], ndarray[tuple[int], dtype[int64]]]

Perform a spatial join between two geometry collections via an internal index.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of geometry-like values or None`	The two geometry collections to join. Missing rows produce no pairs; their original row positions are preserved in every returned id.	required
`right`	`Geometry, GeometryArray, or iterable of geometry-like values or None`	The two geometry collections to join. Missing rows produce no pairs; their original row positions are preserved in every returned id.	required
`predicate`	`str`	Spatial predicate each returned pair must satisfy — one of `'intersects'`, `'contains'`, `'contains_properly'`, `'covers'`, `'within'`, `'covered_by'`, `'equals'`, `'dwithin'`, `'touches'`, `'crosses'`, or `'overlaps'`. Topological forms omit `predicate` to use `'intersects'`; `'dwithin'` requires it explicitly.	`'intersects'`
`distance`	`float`	Required when `predicate='dwithin'`: the maximum separation, in CRS-natural units — geodesic meters on a geographic CRS, native linear units on a projected CRS, raw coordinate units when CRS-free. Finite non-negative values and positive infinity are accepted; missing or empty rows produce no pairs.	`None`
`unit`	`('planar', 'meters')`	`None` (the default) follows the CRS: geographic shape area and length use ellipsoidal chart-edge measures while point distances use geodesics; projected measurements use native linear units, and CRS-free measurements use raw coordinate units (area results square the corresponding unit). `'planar'` uses Cartesian coordinate space, with geographic coordinates in their native angular units. `'meters'` uses the CRS-aware metric and requires a CRS.	`'planar'`

Returns:

Type	Description
`tuple of numpy.ndarray`	`(left, right)` parallel int64 row-id columns satisfying the predicate.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.
`GeometryError`	If `predicate` is unknown, `distance` is missing or invalid for `predicate='dwithin'`, or `unit='meters'` is requested for a CRS-free geometry.
`CRSError`	If geographic `dwithin` refinement cannot prove a result within the point-edge evaluation budget.

Examples:

>>> import gometry as gm
>>> stops = gm.GeometryArray([gm.Point(0.5, 0.5), gm.Point(9, 9)])
>>> zones = gm.GeometryArray([gm.box(0, 0, 1, 1)])
>>> left, right = gm.join(stops, zones, predicate='within')
>>> (left, right)
(array([0]), array([0]))

nearest ¶

Accepted call forms

nearest(geom: Geometry, values: Geometry | GeometryArray[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, k: int = 1, max_distance: float | None = None, return_distance: Literal[False] = False, unit: Literal['planar', 'meters'] | None = None, exclusive: bool = False, ties: bool = False) -> ndarray[tuple[int], dtype[int64]]

nearest(geom: Geometry, values: Geometry | GeometryArray[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, k: int = 1, max_distance: float | None = None, return_distance: Literal[True], unit: Literal['planar', 'meters'] | None = None, exclusive: bool = False, ties: bool = False) -> tuple[ndarray[tuple[int], dtype[int64]], NDArray[float64]]

nearest(geom: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry], values: Geometry | GeometryArray[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, k: int = 1, max_distance: float | None = None, return_distance: Literal[False] = False, unit: Literal['planar', 'meters'] | None = None, exclusive: bool = False, ties: bool = False) -> Groups[ndarray[tuple[int], dtype[int64]]]

nearest(geom: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], values: Geometry | GeometryArray[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, k: int = 1, max_distance: float | None = None, return_distance: Literal[False] = False, unit: Literal['planar', 'meters'] | None = None, exclusive: bool = False, ties: bool = False) -> Groups[ndarray[tuple[int], dtype[int64]] | None]

nearest(geom: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry], values: Geometry | GeometryArray[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, k: int = 1, max_distance: float | None = None, return_distance: Literal[True], unit: Literal['planar', 'meters'] | None = None, exclusive: bool = False, ties: bool = False) -> tuple[Groups[ndarray[tuple[int], dtype[int64]]], NDArray[float64]]

nearest(geom: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], values: Geometry | GeometryArray[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, k: int = 1, max_distance: float | None = None, return_distance: Literal[True], unit: Literal['planar', 'meters'] | None = None, exclusive: bool = False, ties: bool = False) -> tuple[Groups[ndarray[tuple[int], dtype[int64]] | None], NDArray[float64]]

nearest(geom: Geometry, values: Geometry | GeometryArray[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, k: int = 1, max_distance: float | None = None, return_distance: bool = False, unit: Literal['planar', 'meters'] | None = None, exclusive: bool = False, ties: bool = False) -> NDArray[int64] | tuple[NDArray[int64], NDArray[float64]]

nearest(geom: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry], values: Geometry | GeometryArray[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, k: int = 1, max_distance: float | None = None, return_distance: bool = False, unit: Literal['planar', 'meters'] | None = None, exclusive: bool = False, ties: bool = False) -> Groups[ndarray[tuple[int], dtype[int64]]] | tuple[Groups[ndarray[tuple[int], dtype[int64]]], NDArray[float64]]

nearest(geom: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], values: Geometry | GeometryArray[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, k: int = 1, max_distance: float | None = None, return_distance: bool = False, unit: Literal['planar', 'meters'] | None = None, exclusive: bool = False, ties: bool = False) -> Groups[NDArray[int64] | None] | tuple[Groups[NDArray[int64] | None], NDArray[float64]]

nearest(geom: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], values: Geometry | GeometryArray[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None], *, k: int = 1, max_distance: float | None = None, return_distance: bool = False, unit: Literal['planar', 'meters'] | None = None, exclusive: bool = False, ties: bool = False) -> ndarray[tuple[int], dtype[int64]] | Groups[ndarray[tuple[int], dtype[int64]] | None] | tuple[ndarray[tuple[int], dtype[int64]], NDArray[float64]] | tuple[Groups[ndarray[tuple[int], dtype[int64]] | None], NDArray[float64]]

Find the nearest of values to each query geometry (builds an index).

Parameters:

Name	Type	Description	Default
`geom`	`Geometry, GeometryArray, or iterable of Geometry or None`	Query geometry or one query per sequence row. Missing rows produce missing result groups and retain their logical positions.	required
`values`	`Geometry, GeometryArray, or iterable of geometry-like values or None`	Candidate geometries to index and search.	required
`k`	`int`	Number of nearest neighbors to return per query; `0` returns no neighbors.	`1`
`max_distance`	`float`	Ignore candidates farther than this from the query. Must be finite and non-negative.	`None`
`return_distance`	`bool`	If `True`, return distances alongside handles — `(indices, distances)` for a scalar query, `(matches, distances)` for an array query. The distance-returning form requires `return_distance=True`.	`False`
`unit`	`('planar', 'meters')`	`None` (the default) follows the CRS: geographic shape area and length use ellipsoidal chart-edge measures while point distances use geodesics; projected measurements use native linear units, and CRS-free measurements use raw coordinate units (area results square the corresponding unit). `'planar'` uses Cartesian coordinate space, with geographic coordinates in their native angular units. `'meters'` uses the CRS-aware metric and requires a CRS.	`'planar'`
`exclusive`	`bool`	If `True`, skip candidates structurally equal to the query geometry (same exact coordinates) — "the nearest other feature".	`False`
`ties`	`bool`	Also return every candidate TYING the k-th nearest distance (exact comparison) — results can then exceed `k`.	`False`

Returns:

Type	Description
`int64 numpy.ndarray, Groups, or tuple`	Indices into `values` of the nearest geometries — an `int64` ndarray for a scalar query, CSR `Groups` for an array or iterable query. With `return_distance=True`, plain tuple field order is `(indices, distances)` for a scalar query or `(matches, distances)` for an array or iterable query (distances parallel to `matches.values`).

Raises:

Type	Description
`GeometryError`	If `k` is negative, `max_distance` is negative or non-finite, or `unit='meters'` is requested for a CRS-free geometry.
`CRSMismatchError`	If query and indexed geometries have different CRS or coordinate-epoch metadata.

Examples:

>>> import gometry as gm
>>> sites = [gm.Point(0, 0), gm.Point(5, 5)]
>>> gm.nearest(gm.Point(4, 4), sites)
array([1])