Skip to content

Overlay & dissolve

Binary set operations and reductions over geometry collections.

Related: Constructive operations

difference

Accepted call forms 
difference(left: Point, right: Geometry) -> Point

difference(left: MultiPoint, right: Geometry) -> MultiPoint | Point

difference(left: MultiPoint, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT]) -> GeometryArray[MultiPoint | Point]

difference(left: MultiPoint, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT | None]) -> GeometryArray[MultiPoint | Point | None]

difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT]) -> GeometryArray[Point]

difference(left: Point, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT]) -> GeometryArray[Point]

difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[MultiPoint], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT]) -> GeometryArray[MultiPoint | Point]

difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT | None]) -> GeometryArray[Point | None]

difference(left: Point, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT | None]) -> GeometryArray[Point | None]

difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[MultiPoint | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT | None]) -> GeometryArray[MultiPoint | Point | None]

difference(left: Geometry, right: Geometry) -> Geometry

difference(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT]) -> GeometryArray[Geometry]

difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT], right: Geometry) -> GeometryArray[Geometry]

difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT], right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT]) -> GeometryArray[Geometry]

difference(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None]) -> GeometryArray[Geometry | None]

difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None], right: Geometry) -> GeometryArray[Geometry | None]

difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None], right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT | None]) -> GeometryArray[Geometry | None]

difference(left: Geometry | GeometryArray[Geometry | None], right: Geometry | GeometryArray[Geometry | None]) -> Geometry | GeometryArray[Geometry | None]

Compute the set-theoretic difference left - right.

Evaluated in the coordinate plane. In a geographic CRS, topology resolves longitude aliases, seam spellings, and pole longitudes in the CRS-native frame; seam-crossing inputs are split into chart pieces before construction.

Parameters:

Name Type Description Default
left Geometry, GeometryArray, or iterable of Geometry or None

Geometry to subtract from (left) and geometry subtracted (right). Scalar and batch operands broadcast pairwise; batch lengths must match. Operands must share CRS and coordinate epoch.

 required
right Geometry, GeometryArray, or iterable of Geometry or None

Geometry to subtract from (left) and geometry subtracted (right). Scalar and batch operands broadcast pairwise; batch lengths must match. Operands must share CRS and coordinate epoch.

 required

Returns:

Type Description
Geometry or GeometryArray

One result per input pair; missing rows remain missing.

Raises:

Type Description
CRSMismatchError

If the operands' CRS or coordinate-epoch metadata differ.
InvalidGeometryError

If either operand has coordinates outside its geographic CRS domain.
OverflowError

If no adjacent binary64 assignment preserves the exact result topology.
ResourceLimitError

If the bounded embedding search is exhausted.

Examples:

>>> import gometry as gm
>>> left, right = gm.box(0, 0, 2, 1), gm.box(1, 0, 2, 1)
>>> gm.difference(left, right).to_wkt()
'POLYGON ((0 0, 1 0, 1 1, 0 1, 0 0))'

intersection

Accepted call forms 
intersection(left: Point, right: Geometry) -> Point

intersection(left: Geometry, right: Point) -> Point

intersection(left: MultiPoint, right: Geometry) -> MultiPoint | Point

intersection(left: Geometry, right: MultiPoint) -> MultiPoint | Point

intersection(left: MultiPoint, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT]) -> GeometryArray[MultiPoint | Point]

intersection(left: MultiPoint, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT | None]) -> GeometryArray[MultiPoint | Point | None]

intersection(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT]) -> GeometryArray[Point]

intersection(left: Point, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT]) -> GeometryArray[Point]

intersection(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT], right: Point | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point]) -> GeometryArray[Point]

intersection(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point]) -> GeometryArray[Point]

intersection(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[MultiPoint], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT]) -> GeometryArray[MultiPoint | Point]

intersection(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT], right: MultiPoint | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[MultiPoint]) -> GeometryArray[MultiPoint | Point]

intersection(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[MultiPoint]) -> GeometryArray[MultiPoint | Point]

intersection(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT | None]) -> GeometryArray[Point | None]

intersection(left: Point, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT | None]) -> GeometryArray[Point | None]

intersection(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None], right: Point | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | None]) -> GeometryArray[Point | None]

intersection(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | None]) -> GeometryArray[Point | None]

intersection(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[MultiPoint | None], right: Geometry | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT | None]) -> GeometryArray[MultiPoint | Point | None]

intersection(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None], right: MultiPoint | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[MultiPoint | None]) -> GeometryArray[MultiPoint | Point | None]

intersection(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[MultiPoint | None]) -> GeometryArray[MultiPoint | Point | None]

intersection(left: Geometry, right: Geometry) -> Geometry

intersection(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT]) -> GeometryArray[Geometry]

intersection(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT], right: Geometry) -> GeometryArray[Geometry]

intersection(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT], right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT]) -> GeometryArray[Geometry]

intersection(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None]) -> GeometryArray[Geometry | None]

intersection(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None], right: Geometry) -> GeometryArray[Geometry | None]

intersection(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None], right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT | None]) -> GeometryArray[Geometry | None]

intersection(left: Geometry | GeometryArray[Geometry | None], right: Geometry | GeometryArray[Geometry | None]) -> Geometry | GeometryArray[Geometry | None]

Compute the set-theoretic intersection of left and right.

Evaluated in the coordinate plane. In a geographic CRS, topology resolves longitude aliases, seam spellings, and pole longitudes in the CRS-native frame; seam-crossing inputs are split into chart pieces before construction. A closed axis-aligned rectangle containing the other operand's raw bounds retains that operand verbatim when its bounds are sound in the operation's frame.

Parameters:

Name Type Description Default
left Geometry, GeometryArray, or iterable of Geometry or None

Scalar and batch operands broadcast pairwise; batch lengths must match. Operands must share CRS and coordinate epoch.

 required
right Geometry, GeometryArray, or iterable of Geometry or None

Scalar and batch operands broadcast pairwise; batch lengths must match. Operands must share CRS and coordinate epoch.

 required

Returns:

Type Description
Geometry or GeometryArray

One result per input pair; missing rows remain missing.

Raises:

Type Description
CRSMismatchError

If the operands' CRS or coordinate-epoch metadata differ.
InvalidGeometryError

If either operand has coordinates outside its geographic CRS domain.
OverflowError

If no adjacent binary64 assignment preserves the exact result topology.
ResourceLimitError

If the bounded embedding search is exhausted.

Examples:

>>> import gometry as gm
>>> left, right = gm.box(0, 0, 2, 2), gm.box(1, 1, 3, 3)
>>> gm.intersection(left, right).to_wkt()
'POLYGON ((1 1, 2 1, 2 2, 1 2, 1 1))'

intersection_all

Accepted call forms 
intersection_all(values: Point | MultiPoint | GeometryArray[Point | MultiPoint | None] | Iterable[Point | MultiPoint | None]) -> Point | MultiPoint

intersection_all(values: Geometry | GeometryArray[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None]) -> Geometry

Common intersection of many geometries.

The region inside every input. When sound coordinate bounds prove operands disjoint, returns the typed empty directly; in a geographic CRS this requires every operand to be seam-free, pole-free, and canonically spelled. Otherwise, the result is assembled from one joint arrangement. Mixed dimensions narrow to the lowest shared dimension and an empty result keeps that dimension's typed empty.

Parameters:

Name Type Description Default
values Geometry, GeometryArray, or iterable of Geometry

One geometry or geometries to intersect. Missing array rows are skipped.

 required

Returns:

Type Description
Geometry

A single geometry that is the intersection of all inputs.

Raises:

Type Description
CRSMismatchError

If the operands' CRS or coordinate-epoch metadata differ.
OverflowError

If no adjacent binary64 assignment preserves the exact result topology.
ResourceLimitError

If the bounded embedding search is exhausted.
InvalidGeometryError

If values is empty or contains coordinates outside its geographic CRS domain.
See Also

union_all : Union of many geometries into one. polygonize_all : Build polygons from pooled linework.

Examples:

>>> import gometry as gm
>>> panes = [gm.box(0, 0, 3, 3), gm.box(1, 1, 4, 4), gm.box(2, 2, 5, 5)]
>>> gm.intersection_all(panes).to_wkt()
'POLYGON ((2 2, 3 2, 3 3, 2 3, 2 2))'

symmetric_difference

Accepted call forms 
symmetric_difference(left: Point | MultiPoint, right: Point | MultiPoint) -> Point | MultiPoint

symmetric_difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | MultiPoint], right: Point | MultiPoint | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | MultiPoint]) -> GeometryArray[Point | MultiPoint]

symmetric_difference(left: Point | MultiPoint, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | MultiPoint]) -> GeometryArray[Point | MultiPoint]

symmetric_difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | MultiPoint | None], right: Point | MultiPoint | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | MultiPoint | None]) -> GeometryArray[Point | MultiPoint | None]

symmetric_difference(left: Point | MultiPoint, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | MultiPoint | None]) -> GeometryArray[Point | MultiPoint | None]

symmetric_difference(left: Geometry, right: Geometry) -> Geometry

symmetric_difference(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT]) -> GeometryArray[Geometry]

symmetric_difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT], right: Geometry) -> GeometryArray[Geometry]

symmetric_difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT], right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT]) -> GeometryArray[Geometry]

symmetric_difference(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None]) -> GeometryArray[Geometry | None]

symmetric_difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None], right: Geometry) -> GeometryArray[Geometry | None]

symmetric_difference(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None], right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT | None]) -> GeometryArray[Geometry | None]

symmetric_difference(left: Geometry | GeometryArray[Geometry | None], right: Geometry | GeometryArray[Geometry | None]) -> Geometry | GeometryArray[Geometry | None]

Compute the set-theoretic symmetric difference of left and right.

Evaluated in the coordinate plane. In a geographic CRS, topology resolves longitude aliases, seam spellings, and pole longitudes in the CRS-native frame; seam-crossing inputs are split into chart pieces before construction.

Parameters:

Name Type Description Default
left Geometry, GeometryArray, or iterable of Geometry or None

Scalar and batch operands broadcast pairwise; batch lengths must match. Operands must share CRS and coordinate epoch.

 required
right Geometry, GeometryArray, or iterable of Geometry or None

Scalar and batch operands broadcast pairwise; batch lengths must match. Operands must share CRS and coordinate epoch.

 required

Returns:

Type Description
Geometry or GeometryArray

One result per input pair; missing rows remain missing.

Raises:

Type Description
CRSMismatchError

If the operands' CRS or coordinate-epoch metadata differ.
InvalidGeometryError

If either operand has coordinates outside its geographic CRS domain.
OverflowError

If no adjacent binary64 assignment preserves the exact result topology.
ResourceLimitError

If the bounded embedding search is exhausted.

Examples:

>>> import gometry as gm
>>> left, right = gm.box(0, 0, 2, 1), gm.box(1, 0, 3, 1)
>>> gm.symmetric_difference(left, right).area
2.0

symmetric_difference_all

Accepted call forms 
symmetric_difference_all(values: Point | MultiPoint | GeometryArray[Point | MultiPoint | None] | Iterable[Point | MultiPoint | None]) -> Point | MultiPoint

symmetric_difference_all(values: Geometry | GeometryArray[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None]) -> Geometry

Symmetric difference of many geometries.

The region covered by an odd number of inputs. Strictly disjoint inputs are assembled independently; inputs that can meet use one joint arrangement. In a geographic CRS, topology resolves longitude aliases and seam and pole equivalence in the native frame. The result is order-independent (▵ is associative and commutative).

Parameters:

Name Type Description Default
values Geometry, GeometryArray, or iterable of Geometry

One geometry or geometries to combine. Missing array rows are skipped.

 required

Returns:

Type Description
Geometry

A single geometry covered by an odd number of inputs.

Raises:

Type Description
CRSMismatchError

If the operands' CRS or coordinate-epoch metadata differ.
OverflowError

If no adjacent binary64 assignment preserves the exact result topology.
ResourceLimitError

If the bounded embedding search is exhausted.
InvalidGeometryError

If values is empty or contains coordinates outside its geographic CRS domain.

Examples:

>>> import gometry as gm
>>> panes = [gm.box(0, 0, 2, 2), gm.box(0, 0, 2, 2), gm.box(1, 1, 3, 3)]
>>> gm.symmetric_difference_all(panes).to_wkt()  # the duplicate cancels
'POLYGON ((1 1, 3 1, 3 3, 1 3, 1 1))'

union

Accepted call forms 
union(left: Point | MultiPoint, right: Point | MultiPoint) -> Point | MultiPoint

union(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | MultiPoint], right: Point | MultiPoint | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | MultiPoint]) -> GeometryArray[Point | MultiPoint]

union(left: Point | MultiPoint, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | MultiPoint]) -> GeometryArray[Point | MultiPoint]

union(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | MultiPoint | None], right: Point | MultiPoint | (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | MultiPoint | None]) -> GeometryArray[Point | MultiPoint | None]

union(left: Point | MultiPoint, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[Point | MultiPoint | None]) -> GeometryArray[Point | MultiPoint | None]

union(left: Geometry, right: Geometry) -> Geometry

union(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT]) -> GeometryArray[Geometry]

union(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT], right: Geometry) -> GeometryArray[Geometry]

union(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT], right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT]) -> GeometryArray[Geometry]

union(left: Geometry, right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None]) -> GeometryArray[Geometry | None]

union(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None], right: Geometry) -> GeometryArray[Geometry | None]

union(left: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryT | None], right: (GeometryArray[GeometryRowT] | Iterable[GeometryRowT])[GeometryOtherT | None]) -> GeometryArray[Geometry | None]

union(left: Geometry | GeometryArray[Geometry | None], right: Geometry | GeometryArray[Geometry | None]) -> Geometry | GeometryArray[Geometry | None]

Compute the set-theoretic union of left and right.

Evaluated in the coordinate plane. In a geographic CRS, topology resolves longitude aliases, seam spellings, and pole longitudes in the CRS-native frame; seam-crossing inputs are split into chart pieces before construction.

Parameters:

Name Type Description Default
left Geometry, GeometryArray, or iterable of Geometry or None

Scalar and batch operands broadcast pairwise; batch lengths must match. Operands must share CRS and coordinate epoch.

 required
right Geometry, GeometryArray, or iterable of Geometry or None

Scalar and batch operands broadcast pairwise; batch lengths must match. Operands must share CRS and coordinate epoch.

 required

Returns:

Type Description
Geometry or GeometryArray

One result per input pair; missing rows remain missing.

Raises:

Type Description
CRSMismatchError

If the operands' CRS or coordinate-epoch metadata differ.
InvalidGeometryError

If either operand has coordinates outside its geographic CRS domain.
OverflowError

If no adjacent binary64 assignment preserves the exact result topology.
ResourceLimitError

If the bounded embedding search is exhausted.
See Also

union_all : Union of many geometries at once.

Examples:

>>> import gometry as gm
>>> gm.union(gm.box(0, 0, 1, 2), gm.box(1, 0, 2, 2)).to_wkt()
'POLYGON ((0 0, 2 0, 2 2, 0 2, 0 0))'

union_all

Accepted call forms 
union_all(values: Point | MultiPoint | GeometryArray[Point | MultiPoint | None] | Iterable[Point | MultiPoint | None]) -> Point | MultiPoint

union_all(values: Geometry | GeometryArray[Geometry | None] | Iterable[Geometry | Buffer | Mapping[str, Any] | SupportsGeoInterface | None]) -> Geometry

Union of many geometries into one.

Strictly disjoint inputs are assembled independently; inputs that can meet use one joint arrangement. In a geographic CRS, topology resolves longitude aliases and seam and pole equivalence in the native frame.

Parameters:

Name Type Description Default
values Geometry, GeometryArray, or iterable of Geometry

One geometry or geometries to union. Missing array rows are skipped.

 required

Returns:

Type Description
Geometry

A single geometry that is the union of all inputs.

Raises:

Type Description
CRSMismatchError

If the operands' CRS or coordinate-epoch metadata differ.
OverflowError

If no adjacent binary64 assignment preserves the exact result topology.
ResourceLimitError

If the bounded embedding search is exhausted.
InvalidGeometryError

If values is empty or contains coordinates outside its geographic CRS domain.
See Also

coverage_union_all : Faster dissolve for a valid polygonal coverage. intersection_all : Common region shared by many geometries. polygonize_all : Build polygons from pooled linework.

Examples:

>>> import gometry as gm
>>> panes = [gm.box(0, 0, 2, 2), gm.box(1, 1, 3, 3)]
>>> gm.union_all(panes).to_wkt()
'POLYGON ((0 0, 2 0, 2 1, 3 1, 3 3, 1 3, 1 2, 0 2, 0 0))'