Predicates¶

Binary spatial relationships, coordinate probes, and DE-9IM predicates.

contains ¶

Accepted call forms

contains(left: Geometry, right: Geometry, *, x: None = None, y: None = None) -> bool

contains(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], *, x: None = None, y: None = None) -> NDArray[bool_]

contains(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], *, x: None = None, y: None = None) -> NDArray[bool_]

contains(left: Geometry, right: None = None, *, x: FloatScalar | ScalarFloatArray, y: FloatScalar | ScalarFloatArray) -> bool

contains(left: Geometry, right: None = None, *, x: FloatColumn | ndarray[tuple[int], dtype[floating[Any] | signedinteger[Any] | unsignedinteger[Any]]], y: FloatInput) -> NDArray[bool_]

contains(left: Geometry, right: None = None, *, x: FloatInput, y: FloatColumn | ndarray[tuple[int], dtype[floating[Any] | signedinteger[Any] | unsignedinteger[Any]]]) -> NDArray[bool_]

contains(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: None = None, *, x: FloatInput, y: FloatInput) -> NDArray[bool_]

contains(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: None = None, *, x: FloatInput, y: FloatInput) -> bool | NDArray[bool_]

contains(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], *, x: None = None, y: None = None) -> bool | NDArray[bool_]

Test whether left contains right or contains the point (x, y).

Returns True if no point of right lies outside left and the interiors of the two geometries share a point. Evaluated from the exact DE-9IM relation matrix; geographic inputs use the longitude and pole quotient.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Container geometry. Array and iterable rows retain their logical positions.	required
`right`	`Geometry, GeometryArray, iterable of Geometry or None`	Candidate geometry; scalar and sequence operands broadcast pairwise, and two sequences must have equal lengths and compatible frames.	required
`x`	`float or sequence of float, keyword-only`	Raw coordinates in `left`'s CRS. Supply both instead of `right`; provide exactly one input mode.	`None`
`y`	`float or sequence of float, keyword-only`	Raw coordinates in `left`'s CRS. Supply both instead of `right`; provide exactly one input mode.	`None`

Returns:

Type	Description
`bool or ndarray`	Whether the relation holds; one result per input pair.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.
`InvalidGeometryError`	If `x` or `y` contains a non-finite coordinate, or the coordinate columns have incompatible lengths.
`TypeError`	If `right` is combined with `x` or `y`, or if only one coordinate keyword is supplied.

See Also

within : Inverse relation. covers : Boundary-inclusive containment. intersects : Boundary-inclusive point test.

Examples:

>>> import gometry as gm
>>> square = gm.box(0, 0, 2, 2)
>>> gm.contains(square, gm.Point(1, 1))
True
>>> gm.contains(square, gm.Point(2, 1))  # boundary: not contained
False
>>> gm.contains(square, x=1, y=1)
True

contains_properly ¶

Accepted call forms

contains_properly(left: Geometry, right: Geometry) -> bool

contains_properly(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

contains_properly(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

contains_properly(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> bool | NDArray[bool_]

Test whether left contains right with no boundary contact.

Like contains, but right must lie entirely in the interior of left — touching the boundary of left anywhere fails (DE-9IM T**FF*FF*). Evaluated from the exact DE-9IM relation matrix; geographic inputs use the longitude and pole quotient.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Container and candidate rows. Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	Container and candidate rows. Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch.	required

Returns:

Type	Description
`bool or ndarray`	Whether the relation holds; one result per input pair.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.

See Also

contains : Boundary contact allowed.

Examples:

>>> import gometry as gm
>>> gm.contains_properly(gm.box(0, 0, 2, 2), gm.Point(1, 1))
True

covered_by ¶

Accepted call forms

covered_by(left: Geometry, right: Geometry) -> bool

covered_by(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

covered_by(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

covered_by(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> bool | NDArray[bool_]

Test whether left is covered by right; inverse of covers.

Evaluated from the exact DE-9IM relation matrix; geographic inputs use the longitude and pole quotient.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Candidate and container rows. Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	Candidate and container rows. Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch.	required

Returns:

Type	Description
`bool or ndarray`	Whether the relation holds; one result per input pair.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.

See Also

covers : Inverse relation.

Examples:

>>> import gometry as gm
>>> gm.covered_by(gm.Point(2, 1), gm.box(0, 0, 2, 2))  # boundary counts
True

covers ¶

Accepted call forms

covers(left: Geometry, right: Geometry) -> bool

covers(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

covers(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

covers(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> bool | NDArray[bool_]

Test whether left covers right: every point of right lies in left.

Evaluated from the exact DE-9IM relation matrix; geographic inputs use the longitude and pole quotient.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Container and candidate rows. Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	Container and candidate rows. Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch.	required

Returns:

Type	Description
`bool or ndarray`	Whether the relation holds; one result per input pair.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.

See Also

covered_by : Inverse relation.

Examples:

>>> import gometry as gm
>>> square = gm.box(0, 0, 2, 2)
>>> gm.covers(square, gm.Point(2, 1))  # boundary counts
True

crosses ¶

Accepted call forms

crosses(left: Geometry, right: Geometry) -> bool

crosses(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

crosses(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

crosses(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> bool | NDArray[bool_]

Test whether left and right cross.

The dimension pair determines the relation. A line crosses a polygon when part of the line interior is inside the polygon and part is outside. Two curves cross when their interiors meet at a point.

Evaluated from the exact DE-9IM relation matrix; geographic inputs use the longitude and pole quotient.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Operands broadcast pairwise; sequences must have equal lengths and compatible CRS/epoch frames.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	Operands broadcast pairwise; sequences must have equal lengths and compatible CRS/epoch frames.	required

Returns:

Type	Description
`bool or ndarray`	Whether the relation holds; one result per input pair.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.

Examples:

>>> import gometry as gm
>>> rising = gm.LineString([(0, 0), (2, 2)])
>>> falling = gm.LineString([(0, 2), (2, 0)])
>>> gm.crosses(rising, falling)
True

disjoint ¶

Accepted call forms

disjoint(left: Geometry, right: Geometry) -> bool

disjoint(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

disjoint(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

disjoint(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> bool | NDArray[bool_]

Test whether left and right share no point; negation of intersects.

Evaluated from the exact DE-9IM relation matrix; geographic inputs use the longitude and pole quotient.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Operands broadcast pairwise; sequences must have equal lengths and compatible CRS/epoch frames.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	Operands broadcast pairwise; sequences must have equal lengths and compatible CRS/epoch frames.	required

Returns:

Type	Description
`bool or ndarray`	Whether the relation holds; one result per input pair.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.

See Also

intersects : Logical negation.

Examples:

>>> import gometry as gm
>>> gm.disjoint(gm.box(0, 0, 1, 1), gm.box(2, 2, 3, 3))
True

dwithin ¶

Accepted call forms

dwithin(left: Geometry, right: Geometry, distance: float, *, unit: Literal['planar', 'meters'] | None = None) -> bool

dwithin(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], distance: FloatInput, *, unit: Literal['planar', 'meters'] | None = None) -> NDArray[bool_]

dwithin(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], distance: FloatInput, *, unit: Literal['planar', 'meters'] | None = None) -> NDArray[bool_]

dwithin(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], distance: FloatInput, *, unit: Literal['planar', 'meters'] | None = None) -> bool | NDArray[bool_]

Test whether left and right are within distance of each other.

On a geographic CRS, point-to-point distances use ellipsoidal geodesics, and shape edges are straight in the CRS's longitude/latitude chart with short-way longitude across the antimeridian. Filled polygon interiors participate.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch frames.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch frames.	required
`distance`	`float or sequence of float`	CRS-aware distance threshold: geodesic meters on a geographic CRS, native linear units on a projected CRS, raw coordinate units when CRS-free. A scalar applies to every pair; with an array operand, an iterable supplies one threshold per result row. Positive infinity is accepted.	required
`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
`bool or ndarray`	One result per input pair. Array results retain one boolean per input row; missing rows and present empty geometries are `False` rather than being dropped. Positive infinity matches only admitted non-empty operands.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.
`GeometryError`	If `distance` is negative, NaN, or negative infinity, or `unit='meters'` is requested for a CRS-free geometry. Positive infinity is accepted and matches every pair of admitted non-empty operands.
`CRSError`	If geographic point-edge search exhausts its work allowance (a binary64 midpoint-depth factor times the current live frontier, subject to a 16,384-evaluation ceiling) or parameter precision ends without certifying the threshold.

See Also

distance : Minimum pairwise distance. nearest_points : Closest-pair witness points. shortest_line : Connecting line between closest points. hausdorff_distance : Hausdorff (set-to-set) similarity distance. frechet_distance : Curve-to-curve similarity (linestrings).

Examples:

>>> import gometry as gm
>>> a, b = gm.Point(13.0, 52.0, crs=4326), gm.Point(13.1, 52.0, crs=4326)
>>> gm.dwithin(a, b, 7000)
True

equals ¶

Accepted call forms

equals(left: Geometry, right: Geometry) -> bool

equals(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

equals(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

equals(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> bool | NDArray[bool_]

Test whether left and right are spatially equal.

Evaluated from the exact DE-9IM relation matrix; geographic inputs use the longitude and pole quotient.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch frames.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch frames.	required

Returns:

Type	Description
`bool or ndarray`	Whether the two geometries are spatially equal; one result per input pair.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.

Examples:

>>> import gometry as gm
>>> a = gm.from_wkt('LINESTRING (0 0, 2 2)')
>>> b = gm.from_wkt('LINESTRING (2 2, 1 1, 0 0)')
>>> gm.equals(a, b)  # same point set, different vertices
True

equals_exact ¶

Accepted call forms

equals_exact(left: Geometry, right: Geometry, tolerance: float = 0.0, *, include_z: bool = True, include_m: bool = True) -> bool

equals_exact(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], tolerance: FloatInput = 0.0, *, include_z: bool = True, include_m: bool = True) -> NDArray[bool_]

equals_exact(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], tolerance: FloatInput = 0.0, *, include_z: bool = True, include_m: bool = True) -> NDArray[bool_]

equals_exact(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], tolerance: FloatInput = 0.0, *, include_z: bool = True, include_m: bool = True) -> bool | NDArray[bool_]

Test coordinate equality within tolerance, optionally comparing Z/M.

Two geometries are equal when they share the same structure and every paired ordinate agrees to within tolerance (|left - right| <= tolerance). tolerance=0.0 is exact. Like every binary operation, both operands must share one CRS/epoch frame; use equals_identical (the vectorized ==) for full value identity including the frame, or equals for an order-independent topological test.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	The two operands. Scalar and sequence inputs broadcast pairwise; sequences must have equal length and compatible CRS/epoch frames.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	The two operands. Scalar and sequence inputs broadcast pairwise; sequences must have equal length and compatible CRS/epoch frames.	required
`tolerance`	`float or sequence of float`	Maximum permitted per-ordinate difference — a scalar applies to every pair, or pass one value per geometry.	`0.0`
`include_z`	`bool`	Whether the Z and M ordinates participate in the comparison.	`True`
`include_m`	`bool`	Whether the Z and M ordinates participate in the comparison.	`True`

Returns:

Type	Description
`bool or ndarray`	Whether the coordinates match; one result per input pair.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.
`GeometryError`	If `tolerance` is negative or non-finite.

Examples:

>>> import gometry as gm
>>> gm.equals_exact(gm.Point(1, 1), gm.Point(1, 1.0000001), 1e-6)
True

equals_identical ¶

Accepted call forms

equals_identical(left: Geometry, right: Geometry) -> bool

equals_identical(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

equals_identical(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

equals_identical(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> bool | NDArray[bool_]

Test full value identity elementwise: the vectorized ==.

Two geometries are identical when they share the same CRS, coordinate epoch, geometry kind, and every active ordinate bit-for-bit in the same vertex order — exactly the scalar left == right. A frame (CRS/epoch) difference is an unequal value, never an error, so mixed-frame data can be compared safely. Use equals for the order-independent topological test, or equals_exact for tolerance-based coordinate comparison.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	The two operands. Scalar and sequence inputs broadcast pairwise; sequences must have equal length.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	The two operands. Scalar and sequence inputs broadcast pairwise; sequences must have equal length.	required

Returns:

Type	Description
`bool or ndarray`	Whether the values are identical; one result per input pair.

Examples:

>>> import gometry as gm
>>> gm.equals_identical(gm.Point(1, 2), gm.Point(1, 2))
True
>>> gm.equals_identical(gm.Point(1, 2), gm.Point(1, 2, crs=4326))
False

intersects ¶

Accepted call forms

intersects(left: Geometry, right: Geometry, *, x: None = None, y: None = None) -> bool

intersects(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], *, x: None = None, y: None = None) -> NDArray[bool_]

intersects(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], *, x: None = None, y: None = None) -> NDArray[bool_]

intersects(left: Geometry, right: None = None, *, x: FloatScalar | ScalarFloatArray, y: FloatScalar | ScalarFloatArray) -> bool

intersects(left: Geometry, right: None = None, *, x: FloatColumn | ndarray[tuple[int], dtype[floating[Any] | signedinteger[Any] | unsignedinteger[Any]]], y: FloatInput) -> NDArray[bool_]

intersects(left: Geometry, right: None = None, *, x: FloatInput, y: FloatColumn | ndarray[tuple[int], dtype[floating[Any] | signedinteger[Any] | unsignedinteger[Any]]]) -> NDArray[bool_]

intersects(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: None = None, *, x: FloatInput, y: FloatInput) -> NDArray[bool_]

intersects(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: None = None, *, x: FloatInput, y: FloatInput) -> bool | NDArray[bool_]

intersects(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], *, x: None = None, y: None = None) -> bool | NDArray[bool_]

Test whether left and right share any point, or whether left intersects the point (x, y).

Evaluated from the exact DE-9IM relation matrix; geographic inputs use the longitude and pole quotient.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Geometry being tested. Array and iterable rows retain their logical positions.	required
`right`	`Geometry, GeometryArray, iterable of Geometry or None`	Geometry compared with `left`. Scalar and sequence operands broadcast pairwise, and two sequences must have equal lengths and compatible frames.	required
`x`	`float or sequence of float, keyword-only`	Raw coordinates in `left`'s CRS. Supply both instead of `right`; provide exactly one input mode.	`None`
`y`	`float or sequence of float, keyword-only`	Raw coordinates in `left`'s CRS. Supply both instead of `right`; provide exactly one input mode.	`None`

Returns:

Type	Description
`bool or ndarray`	Whether the two geometries share any point; one result per input pair.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.
`InvalidGeometryError`	If `x` or `y` contains a non-finite coordinate, or the coordinate columns have incompatible lengths.
`TypeError`	If `right` is combined with `x` or `y`, or if only one coordinate keyword is supplied.

See Also

disjoint : Logical negation.

Examples:

>>> import gometry as gm
>>> gm.intersects(gm.box(0, 0, 2, 2), gm.box(1, 1, 3, 3))
True
>>> gm.intersects(gm.box(0, 0, 2, 2), x=2, y=1)
True

overlaps ¶

Accepted call forms

overlaps(left: Geometry, right: Geometry) -> bool

overlaps(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

overlaps(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

overlaps(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> bool | NDArray[bool_]

Test whether left and right overlap (same dimension, partial interior overlap).

Evaluated from the exact DE-9IM relation matrix; geographic inputs use the longitude and pole quotient.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Operands broadcast pairwise; sequences must have equal lengths and compatible CRS/epoch frames.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	Operands broadcast pairwise; sequences must have equal lengths and compatible CRS/epoch frames.	required

Returns:

Type	Description
`bool or ndarray`	Whether the relation holds; one result per input pair.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.

Examples:

>>> import gometry as gm
>>> gm.overlaps(gm.box(0, 0, 2, 2), gm.box(1, 1, 3, 3))
True

relate ¶

Accepted call forms

relate(left: Geometry, right: Geometry) -> str

relate(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> list[str | None]

relate(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> list[str | None]

relate(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> str | list[str | None]

Compute the DE-9IM intersection matrix string for left and right.

Evaluated from the exact DE-9IM relation matrix; geographic inputs use the longitude and pole quotient.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch frames.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch frames.	required

Returns:

Type	Description
`str or list of str or None`	The nine-character DE-9IM pattern; one per input pair. A missing input row yields `None` in its result slot.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.

Examples:

>>> import gometry as gm
>>> gm.relate(gm.box(0, 0, 2, 2), gm.Point(1, 1))
'0F2FF1FF2'

relate_pattern ¶

Accepted call forms

relate_pattern(left: Geometry, right: Geometry, pattern: str) -> bool

relate_pattern(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], pattern: str) -> NDArray[bool_]

relate_pattern(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], pattern: str) -> NDArray[bool_]

relate_pattern(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], pattern: str) -> bool | NDArray[bool_]

Test whether two geometries' DE-9IM matrix matches a pattern.

Evaluated from the exact DE-9IM relation matrix; geographic inputs use the longitude and pole quotient.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch frames.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch frames.	required
`pattern`	`str`	A DE-9IM pattern string (`T`/`F`/`*`/`0`/`1`/`2` per cell).	required

Returns:

Type	Description
`bool or ndarray`	Whether the matrix matches; one result per input pair.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.
`GeometryError`	If `pattern` is not a 9-character DE-9IM pattern.

Examples:

>>> import gometry as gm
>>> gm.relate_pattern(gm.box(0, 0, 1, 1), gm.box(0.5, 0.5, 1.5, 1.5), 'T*T***T**')
True

touches ¶

Accepted call forms

touches(left: Geometry, right: Geometry) -> bool

touches(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

touches(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

touches(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> bool | NDArray[bool_]

Test whether left and right touch only at boundaries.

Evaluated from the exact DE-9IM relation matrix; geographic inputs use the longitude and pole quotient.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Operands broadcast pairwise; sequences must have equal lengths and compatible CRS/epoch frames.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	Operands broadcast pairwise; sequences must have equal lengths and compatible CRS/epoch frames.	required

Returns:

Type	Description
`bool or ndarray`	Whether the relation holds; one result per input pair.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.

Examples:

>>> import gometry as gm
>>> gm.touches(gm.box(0, 0, 1, 1), gm.box(1, 0, 2, 1))
True

within ¶

Accepted call forms

within(left: Geometry, right: Geometry) -> bool

within(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

within(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> NDArray[bool_]

within(left: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Geometry | None]) -> bool | NDArray[bool_]

Test whether left lies within right; inverse of contains.

Evaluated from the exact DE-9IM relation matrix; geographic inputs use the longitude and pole quotient.

Parameters:

Name	Type	Description	Default
`left`	`Geometry, GeometryArray, or iterable of Geometry or None`	Candidate and container rows. Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch.	required
`right`	`Geometry, GeometryArray, or iterable of Geometry or None`	Candidate and container rows. Scalar and sequence operands broadcast pairwise; sequences must have equal length and compatible CRS/epoch.	required

Returns:

Type	Description
`bool or ndarray`	Whether the relation holds; one result per input pair.

Raises:

Type	Description
`CRSMismatchError`	If the operands' CRS or coordinate-epoch metadata differ.

See Also

contains : Inverse relation (container first).

Examples:

>>> import gometry as gm
>>> gm.within(gm.Point(1, 1), gm.box(0, 0, 2, 2))
True