Set operations#

coverage_union(a, b, **kwargs)#

Merges multiple polygons into one. This is an optimized version of union which assumes the polygons to be non-overlapping.

Parameters
aGeometry or array_like
bGeometry or array_like
**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

Examples

>>> from shapely import normalize, Polygon
>>> polygon = Polygon([(0, 0), (0, 1), (1, 1), (1, 0), (0, 0)])
>>> normalize(coverage_union(polygon, Polygon([(1, 0), (1, 1), (2, 1), (2, 0), (1, 0)])))
<POLYGON ((0 0, 0 1, 1 1, 2 1, 2 0, 1 0, 0 0))>

Union with None returns same polygon >>> normalize(coverage_union(polygon, None)) <POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))>

coverage_union_all(geometries, axis=None, **kwargs)#

Returns the union of multiple polygons of a geometry collection. This is an optimized version of union which assumes the polygons to be non-overlapping.

Parameters
geometriesarray_like
axisint, optional

Axis along which the operation is performed. The default (None) performs the operation over all axes, returning a scalar value. Axis may be negative, in which case it counts from the last to the first axis.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

coverage_union

Examples

>>> from shapely import normalize, Polygon
>>> polygon_1 = Polygon([(0, 0), (0, 1), (1, 1), (1, 0), (0, 0)])
>>> polygon_2 = Polygon([(1, 0), (1, 1), (2, 1), (2, 0), (1, 0)])
>>> normalize(coverage_union_all([polygon_1, polygon_2]))
<POLYGON ((0 0, 0 1, 1 1, 2 1, 2 0, 1 0, 0 0))>
difference(a, b, grid_size=None, **kwargs)#

Returns the part of geometry A that does not intersect with geometry B.

If grid_size is nonzero, input coordinates will be snapped to a precision grid of that size and resulting coordinates will be snapped to that same grid. If 0, this operation will use double precision coordinates. If None, the highest precision of the inputs will be used, which may be previously set using set_precision. Note: returned geometry does not have precision set unless specified previously by set_precision.

Parameters
aGeometry or array_like
bGeometry or array_like
grid_sizefloat, optional

Precision grid size; requires GEOS >= 3.9.0. Will use the highest precision of the inputs by default.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

set_precision

Examples

>>> from shapely import box, LineString, normalize, Polygon
>>> line = LineString([(0, 0), (2, 2)])
>>> difference(line, LineString([(1, 1), (3, 3)]))
<LINESTRING (0 0, 1 1)>
>>> difference(line, LineString())
<LINESTRING (0 0, 2 2)>
>>> difference(line, None) is None
True
>>> box1 = box(0, 0, 2, 2)
>>> box2 = box(1, 1, 3, 3)
>>> normalize(difference(box1, box2))
<POLYGON ((0 0, 0 2, 1 2, 1 1, 2 1, 2 0, 0 0))>
>>> box1 = box(0.1, 0.2, 2.1, 2.1)
>>> difference(box1, box2, grid_size=1)
<POLYGON ((2 0, 0 0, 0 2, 1 2, 1 1, 2 1, 2 0))>
intersection(a, b, grid_size=None, **kwargs)#

Returns the geometry that is shared between input geometries.

If grid_size is nonzero, input coordinates will be snapped to a precision grid of that size and resulting coordinates will be snapped to that same grid. If 0, this operation will use double precision coordinates. If None, the highest precision of the inputs will be used, which may be previously set using set_precision. Note: returned geometry does not have precision set unless specified previously by set_precision.

Parameters
aGeometry or array_like
bGeometry or array_like
grid_sizefloat, optional

Precision grid size; requires GEOS >= 3.9.0. Will use the highest precision of the inputs by default.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

intersection_all
set_precision

Examples

>>> from shapely import box, LineString, normalize, Polygon
>>> line = LineString([(0, 0), (2, 2)])
>>> intersection(line, LineString([(1, 1), (3, 3)]))
<LINESTRING (1 1, 2 2)>
>>> box1 = box(0, 0, 2, 2)
>>> box2 = box(1, 1, 3, 3)
>>> normalize(intersection(box1, box2))
<POLYGON ((1 1, 1 2, 2 2, 2 1, 1 1))>
>>> box1 = box(0.1, 0.2, 2.1, 2.1)
>>> intersection(box1, box2, grid_size=1)
<POLYGON ((2 2, 2 1, 1 1, 1 2, 2 2))>
intersection_all(geometries, axis=None, **kwargs)#

Returns the intersection of multiple geometries.

This function ignores None values when other Geometry elements are present. If all elements of the given axis are None, None is returned.

Parameters
geometriesarray_like
axisint, optional

Axis along which the operation is performed. The default (None) performs the operation over all axes, returning a scalar value. Axis may be negative, in which case it counts from the last to the first axis.

**kwargs

For other keyword-only arguments, see the NumPy ufunc.reduce docs.

See also

intersection

Examples

>>> from shapely import LineString
>>> line1 = LineString([(0, 0), (2, 2)])
>>> line2 = LineString([(1, 1), (3, 3)])
>>> intersection_all([line1, line2])
<LINESTRING (1 1, 2 2)>
>>> intersection_all([[line1, line2, None]], axis=1).tolist()
[<LINESTRING (1 1, 2 2)>]
symmetric_difference(a, b, grid_size=None, **kwargs)#

Returns the geometry that represents the portions of input geometries that do not intersect.

If grid_size is nonzero, input coordinates will be snapped to a precision grid of that size and resulting coordinates will be snapped to that same grid. If 0, this operation will use double precision coordinates. If None, the highest precision of the inputs will be used, which may be previously set using set_precision. Note: returned geometry does not have precision set unless specified previously by set_precision.

Parameters
aGeometry or array_like
bGeometry or array_like
grid_sizefloat, optional

Precision grid size; requires GEOS >= 3.9.0. Will use the highest precision of the inputs by default.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

symmetric_difference_all
set_precision

Examples

>>> from shapely import box, LineString, normalize
>>> line = LineString([(0, 0), (2, 2)])
>>> symmetric_difference(line, LineString([(1, 1), (3, 3)]))
<MULTILINESTRING ((0 0, 1 1), (2 2, 3 3))>
>>> box1 = box(0, 0, 2, 2)
>>> box2 = box(1, 1, 3, 3)
>>> normalize(symmetric_difference(box1, box2))
<MULTIPOLYGON (((1 2, 1 3, 3 3, 3 1, 2 1, 2 2, 1 2)), ((0 0, 0 2, 1 2, 1 1, ...>
>>> box1 = box(0.1, 0.2, 2.1, 2.1)
>>> symmetric_difference(box1, box2, grid_size=1)
<MULTIPOLYGON (((2 0, 0 0, 0 2, 1 2, 1 1, 2 1, 2 0)), ((2 2, 1 2, 1 3, 3 3, ...>
symmetric_difference_all(geometries, axis=None, **kwargs)#

Returns the symmetric difference of multiple geometries.

This function ignores None values when other Geometry elements are present. If all elements of the given axis are None, None is returned.

Parameters
geometriesarray_like
axisint, optional

Axis along which the operation is performed. The default (None) performs the operation over all axes, returning a scalar value. Axis may be negative, in which case it counts from the last to the first axis.

**kwargs

For other keyword-only arguments, see the NumPy ufunc.reduce docs.

Examples

>>> from shapely import LineString
>>> line1 = LineString([(0, 0), (2, 2)])
>>> line2 = LineString([(1, 1), (3, 3)])
>>> symmetric_difference_all([line1, line2])
<MULTILINESTRING ((0 0, 1 1), (2 2, 3 3))>
>>> symmetric_difference_all([[line1, line2, None]], axis=1).tolist()
[<MULTILINESTRING ((0 0, 1 1), (2 2, 3 3))>]
union(a, b, grid_size=None, **kwargs)#

Merges geometries into one.

If grid_size is nonzero, input coordinates will be snapped to a precision grid of that size and resulting coordinates will be snapped to that same grid. If 0, this operation will use double precision coordinates. If None, the highest precision of the inputs will be used, which may be previously set using set_precision. Note: returned geometry does not have precision set unless specified previously by set_precision.

Parameters
aGeometry or array_like
bGeometry or array_like
grid_sizefloat, optional

Precision grid size; requires GEOS >= 3.9.0. Will use the highest precision of the inputs by default.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

union_all
set_precision

Examples

>>> from shapely import box, LineString, normalize
>>> line = LineString([(0, 0), (2, 2)])
>>> union(line, LineString([(2, 2), (3, 3)]))
<MULTILINESTRING ((0 0, 2 2), (2 2, 3 3))>
>>> union(line, None) is None
True
>>> box1 = box(0, 0, 2, 2)
>>> box2 = box(1, 1, 3, 3)
>>> normalize(union(box1, box2))
<POLYGON ((0 0, 0 2, 1 2, 1 3, 3 3, 3 1, 2 1, 2 0, 0 0))>
>>> box1 = box(0.1, 0.2, 2.1, 2.1)
>>> union(box1, box2, grid_size=1)
<POLYGON ((2 0, 0 0, 0 2, 1 2, 1 3, 3 3, 3 1, 2 1, 2 0))>
union_all(geometries, grid_size=None, axis=None, **kwargs)#

Returns the union of multiple geometries.

This function ignores None values when other Geometry elements are present. If all elements of the given axis are None, None is returned.

If grid_size is nonzero, input coordinates will be snapped to a precision grid of that size and resulting coordinates will be snapped to that same grid. If 0, this operation will use double precision coordinates. If None, the highest precision of the inputs will be used, which may be previously set using set_precision. Note: returned geometry does not have precision set unless specified previously by set_precision.

Parameters
geometriesarray_like
grid_sizefloat, optional

Precision grid size; requires GEOS >= 3.9.0. Will use the highest precision of the inputs by default.

axisint, optional

Axis along which the operation is performed. The default (None) performs the operation over all axes, returning a scalar value. Axis may be negative, in which case it counts from the last to the first axis.

**kwargs

For other keyword-only arguments, see the NumPy ufunc docs.

See also

union
set_precision

Examples

>>> from shapely import box, LineString, normalize
>>> line1 = LineString([(0, 0), (2, 2)])
>>> line2 = LineString([(2, 2), (3, 3)])
>>> union_all([line1, line2])
<MULTILINESTRING ((0 0, 2 2), (2 2, 3 3))>
>>> union_all([[line1, line2, None]], axis=1).tolist()
[<MULTILINESTRING ((0 0, 2 2), (2 2, 3 3))>]
>>> box1 = box(0, 0, 2, 2)
>>> box2 = box(1, 1, 3, 3)
>>> normalize(union_all([box1, box2]))
<POLYGON ((0 0, 0 2, 1 2, 1 3, 3 3, 3 1, 2 1, 2 0, 0 0))>
>>> box1 = box(0.1, 0.2, 2.1, 2.1)
>>> union_all([box1, box2], grid_size=1)
<POLYGON ((2 0, 0 0, 0 2, 1 2, 1 3, 3 3, 3 1, 2 1, 2 0))>