Source: https://gometry.monicz.dev/api/toplevel/predicates/

# Predicates

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

**Related:** [Predicates & relationships](https://gometry.monicz.dev/guide/predicates/)

## contains

Accepted call forms

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

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

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

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

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

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

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

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

```python
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](https://gometry.monicz.dev/api/toplevel/predicates/#gometry.within "within") : Inverse relation.
[covers](https://gometry.monicz.dev/api/toplevel/predicates/#gometry.covers "covers") : Boundary-inclusive containment.
[intersects](https://gometry.monicz.dev/api/toplevel/predicates/#gometry.intersects "intersects") : Boundary-inclusive point test.

Examples:

```pycon
>>> 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

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

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

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

```python
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](https://gometry.monicz.dev/api/toplevel/predicates/#gometry.contains "contains") : Boundary contact allowed.

Examples:

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

## covered\_by

Accepted call forms

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

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

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

```python
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](https://gometry.monicz.dev/api/toplevel/predicates/#gometry.covers "covers") : Inverse relation.

Examples:

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

## covers

Accepted call forms

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

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

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

```python
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](https://gometry.monicz.dev/api/toplevel/predicates/#gometry.covered_by "covered_by") : Inverse relation.

Examples:

```pycon
>>> 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

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

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

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

```python
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:

```pycon
>>> 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

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

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

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

```python
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](https://gometry.monicz.dev/api/toplevel/predicates/#gometry.intersects "intersects") : Logical negation.

Examples:

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

## dwithin

Accepted call forms

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

```python
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_]
```

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

```python
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](https://gometry.monicz.dev/api/toplevel/measurement/#gometry.distance "distance") : Minimum pairwise distance.
[nearest\_points](https://gometry.monicz.dev/api/toplevel/measurement/#gometry.nearest_points "nearest_points") : Closest-pair witness points.
[shortest\_line](https://gometry.monicz.dev/api/toplevel/measurement/#gometry.shortest_line "shortest_line") : Connecting line between closest points.
[hausdorff\_distance](https://gometry.monicz.dev/api/toplevel/measurement/#gometry.hausdorff_distance "hausdorff_distance") : Hausdorff (set-to-set) similarity distance.
[frechet\_distance](https://gometry.monicz.dev/api/toplevel/measurement/#gometry.frechet_distance "frechet_distance") : Curve-to-curve similarity (linestrings).

Examples:

```pycon
>>> 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

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

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

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

```python
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:

```pycon
>>> 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

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

```python
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_]
```

```python
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_]
```

```python
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:

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

## equals\_identical

Accepted call forms

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

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

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

```python
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:

```pycon
>>> 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

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

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

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

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

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

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

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

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

```python
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](https://gometry.monicz.dev/api/toplevel/predicates/#gometry.disjoint "disjoint") : Logical negation.

Examples:

```pycon
>>> 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

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

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

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

```python
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:

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

## relate

Accepted call forms

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

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

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

```python
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:

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

## relate\_pattern

Accepted call forms

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

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

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

```python
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:

```pycon
>>> 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

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

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

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

```python
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:

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

## within

Accepted call forms

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

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

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

```python
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](https://gometry.monicz.dev/api/toplevel/predicates/#gometry.contains "contains") : Inverse relation (container first).

Examples:

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