Geometry
Contents
Geometry#
Shapely geometry classes, such as shapely.Point
, are the central data types
in Shapely. Each geometry class extends the shapely.Geometry
base class,
which is a container of the underlying GEOS geometry object, to provide geometry
type-specific attributes and behavior. The Geometry
object keeps track of
the underlying GEOS geometry and lets the python garbage collector free its
memory when it is not used anymore.
Geometry objects are immutable. This means that after constructed, they cannot be changed in place. Every Shapely operation will result in a new object being returned.
Construction#
Geometries can be constructed directly using Shapely geometry classes:
>>> from shapely import Point, LineString
>>> Point(5.2, 52.1)
<POINT (5.2 52.1)>
>>> LineString([(0, 0), (1, 2)])
<LINESTRING (0 0, 1 2)>
Geometries can also be constructed from a WKT (Well-Known Text) or WKB (Well-Known Binary) representation:
>>> from shapely import from_wkb, from_wkt
>>> from_wkt("POINT (5.2 52.1)")
<POINT (5.2 52.1)>
>>> from_wkb(b"\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\xf0?\x00\x00\x00\x00\x00\x00\xf0?")
<POINT (1 1)>
A more efficient way of constructing geometries is by making use of the (vectorized)
functions described in shapely.creation
.
Pickling#
Geometries can be serialized using pickle:
>>> import pickle
>>> from shapely import Point
>>> pickled = pickle.dumps(Point(1, 1))
>>> pickle.loads(pickled)
<POINT (1 1)>
Warning
Pickling will convert linearrings to linestrings.
See shapely.io.to_wkb()
for a complete list of limitations.
Hashing#
Geometries can be used as elements in sets or as keys in dictionaries. Python uses a technique called hashing for lookups in these datastructures. Shapely generates this hash from the WKB representation. Therefore, geometries are equal if and only if their WKB representations are equal.
>>> from shapely import Point
>>> point_1 = Point(5.2, 52.1)
>>> point_2 = Point(1, 1)
>>> point_3 = Point(5.2, 52.1)
>>> {point_1, point_2, point_3}
{<POINT (1 1)>, <POINT (5.2 52.1)>}
Warning
Due to limitations of WKB, linearrings will equal linestrings if they contain the exact same points.
See shapely.io.to_wkb()
.
Comparing two geometries directly is also supported.
This is the same as using shapely.predicates.equals_exact()
with a tolerance
value of zero.
>>> point_1 == point_2
False
>>> point_1 == point_3
True
>>> point_1 != point_2
True
Geometry types#
Geometry classes and factories
- class GeometryCollection(geoms=None)#
Bases:
shapely.geometry.base.BaseMultipartGeometry
A collection of one or more geometries that may contain more than one type of geometry.
- Parameters
- geomslist
A list of shapely geometry instances, which may be of varying geometry types.
Examples
Create a GeometryCollection with a Point and a LineString
>>> from shapely import LineString, Point >>> p = Point(51, -1) >>> l = LineString([(52, -1), (49, 2)]) >>> gc = GeometryCollection([p, l])
- Attributes
- geomssequence
A sequence of Shapely geometry instances
Methods
almost_equals
(other[, decimal])True if geometries are equal at all coordinates to a specified decimal place.
buffer
(distance[, resolution, quadsegs, ...])Get a geometry that represents all points within a distance of this geometry.
contains
(other)Returns True if the geometry contains the other, else False
covered_by
(other)Returns True if the geometry is covered by the other, else False
covers
(other)Returns True if the geometry covers the other, else False
crosses
(other)Returns True if the geometries cross, else False
difference
(other)Returns the difference of the geometries
disjoint
(other)Returns True if geometries are disjoint, else False
distance
(other)Unitless distance to other geometry (float)
equals
(other)Returns True if geometries are equal, else False.
equals_exact
(other, tolerance)True if geometries are equal to within a specified tolerance.
hausdorff_distance
(other)Unitless hausdorff distance to other geometry (float)
interpolate
(distance[, normalized])Return a point at the specified distance along a linear geometry
intersection
(other)Returns the intersection of the geometries
intersects
(other)Returns True if geometries intersect, else False
line_interpolate_point
(distance[, normalized])Return a point at the specified distance along a linear geometry
line_locate_point
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
Converts geometry to normal form (or canonical form).
overlaps
(other)Returns True if geometries overlap, else False
Returns a point guaranteed to be within the object, cheaply.
project
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
relate
(other)Returns the DE-9IM intersection matrix for the two geometries (string)
relate_pattern
(other, pattern)Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
Returns a point guaranteed to be within the object, cheaply.
reverse
()Returns a copy of this geometry with the order of coordinates reversed.
segmentize
(tolerance)Adds vertices to line segments based on tolerance.
simplify
(tolerance[, preserve_topology])Returns a simplified geometry produced by the Douglas-Peucker algorithm
svg
([scale_factor, color])Returns a group of SVG elements for the multipart geometry.
symmetric_difference
(other)Returns the symmetric difference of the geometries (Shapely geometry)
touches
(other)Returns True if geometries touch, else False
union
(other)Returns the union of the geometries (Shapely geometry)
within
(other)Returns True if geometry is within the other, else False
geometryType
- __eq__(value, /)#
Return self==value.
- __ge__(value, /)#
Return self>=value.
- property __geo_interface__#
Dictionary representation of the geometry
- __gt__(value, /)#
Return self>value.
- __hash__(/)#
Return hash(self).
- __le__(value, /)#
Return self<=value.
- __lt__(value, /)#
Return self<value.
- __ne__(value, /)#
Return self!=value.
- static __new__(self, geoms=None)#
- __or__(other)#
Return self|value.
- __reduce__()#
Helper for pickle.
- __repr__()#
Return repr(self).
- __str__()#
Return str(self).
- almost_equals(other, decimal=6)#
True if geometries are equal at all coordinates to a specified decimal place.
Deprecated since version 1.8.0: The ‘almost_equals()’ method is deprecated and will be removed in Shapely 2.0 because the name is confusing. The ‘equals_exact()’ method should be used instead.
Refers to approximate coordinate equality, which requires coordinates to be approximately equal and in the same order for all components of a geometry.
Because of this it is possible for “equals()” to be True for two geometries and “almost_equals()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property area#
Unitless area of the geometry (float)
- property boundary#
Returns a lower dimension geometry that bounds the object
The boundary of a polygon is a line, the boundary of a line is a collection of points. The boundary of a point is an empty (null) collection.
- property bounds#
Returns minimum bounding region (minx, miny, maxx, maxy)
- buffer(distance, resolution=16, quadsegs=None, cap_style=1, join_style=1, mitre_limit=5.0, single_sided=False)#
Get a geometry that represents all points within a distance of this geometry.
A positive distance produces a dilation, a negative distance an erosion. A very small or zero distance may sometimes be used to “tidy” a polygon.
- Parameters
- distancefloat
The distance to buffer around the object.
- resolutionint, optional
The resolution of the buffer around each vertex of the object.
- quadsegsint, optional
Sets the number of line segments used to approximate an angle fillet. Note: the use of a quadsegs parameter is deprecated and will be gone from the next major release.
- cap_styleint, optional
The styles of caps are: CAP_STYLE.round (1), CAP_STYLE.flat (2), and CAP_STYLE.square (3).
- join_styleint, optional
The styles of joins between offset segments are: JOIN_STYLE.round (1), JOIN_STYLE.mitre (2), and JOIN_STYLE.bevel (3).
- mitre_limitfloat, optional
The mitre limit ratio is used for very sharp corners. The mitre ratio is the ratio of the distance from the corner to the end of the mitred offset corner. When two line segments meet at a sharp angle, a miter join will extend the original geometry. To prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. Corners with a ratio which exceed the limit will be beveled.
- single_sidebool, optional
The side used is determined by the sign of the buffer distance:
a positive distance indicates the left-hand side a negative distance indicates the right-hand side
The single-sided buffer of point geometries is the same as the regular buffer. The End Cap Style for single-sided buffers is always ignored, and forced to the equivalent of CAP_FLAT.
- Returns
- Geometry
Notes
The return value is a strictly two-dimensional geometry. All Z coordinates of the original geometry will be ignored.
Examples
>>> from shapely.wkt import loads >>> g = loads('POINT (0.0 0.0)')
16-gon approx of a unit radius circle:
>>> g.buffer(1.0).area 3.1365484905459...
128-gon approximation:
>>> g.buffer(1.0, 128).area 3.141513801144...
triangle approximation:
>>> g.buffer(1.0, 3).area 3.0 >>> list(g.buffer(1.0, cap_style=CAP_STYLE.square).exterior.coords) [(1.0, 1.0), (1.0, -1.0), (-1.0, -1.0), (-1.0, 1.0), (1.0, 1.0)] >>> g.buffer(1.0, cap_style=CAP_STYLE.square).area 4.0
- property centroid#
Returns the geometric center of the object
- contains(other)#
Returns True if the geometry contains the other, else False
- property convex_hull#
Imagine an elastic band stretched around the geometry: that’s a convex hull, more or less
The convex hull of a three member multipoint, for example, is a triangular polygon.
- property coords#
Access to geometry’s coordinates (CoordinateSequence)
- covered_by(other)#
Returns True if the geometry is covered by the other, else False
- covers(other)#
Returns True if the geometry covers the other, else False
- crosses(other)#
Returns True if the geometries cross, else False
- difference(other)#
Returns the difference of the geometries
- disjoint(other)#
Returns True if geometries are disjoint, else False
- distance(other)#
Unitless distance to other geometry (float)
- property envelope#
A figure that envelopes the geometry
- equals(other)#
Returns True if geometries are equal, else False.
This method considers point-set equality (or topological equality), and is equivalent to (self.within(other) & self.contains(other)).
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals( ... LineString([(0, 0), (1, 1), (2, 2)]) ... ) True
- equals_exact(other, tolerance)#
True if geometries are equal to within a specified tolerance.
- Parameters
- otherBaseGeometry
The other geometry object in this comparison.
- tolerancefloat
Absolute tolerance in the same units as coordinates.
- This method considers coordinate equality, which requires
- coordinates to be equal and in the same order for all components
- of a geometry.
- Because of this it is possible for “equals()” to be True for two
- geometries and “equals_exact()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property geom_type#
Name of the geometry’s type, such as ‘Point’
- property has_z#
True if the geometry’s coordinate sequence(s) have z values (are 3-dimensional)
- hausdorff_distance(other)#
Unitless hausdorff distance to other geometry (float)
- interpolate(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of line_interpolate_point.
- intersection(other)#
Returns the intersection of the geometries
- intersects(other)#
Returns True if geometries intersect, else False
- property is_closed#
True if the geometry is closed, else False
Applicable only to 1-D geometries.
- property is_empty#
True if the set of points in this geometry is empty, else False
- property is_ring#
True if the geometry is a closed ring, else False
- property is_simple#
True if the geometry is simple, meaning that any self-intersections are only at boundary points, else False
- property is_valid#
True if the geometry is valid (definition depends on sub-class), else False
- property length#
Unitless length of the geometry (float)
- line_interpolate_point(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of interpolate.
- line_locate_point(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of project.
- property minimum_clearance#
Unitless distance by which a node could be moved to produce an invalid geometry (float)
- property minimum_rotated_rectangle#
Returns the general minimum bounding rectangle of the geometry. Can possibly be rotated. If the convex hull of the object is a degenerate (line or point) this same degenerate is returned.
- normalize()#
Converts geometry to normal form (or canonical form).
This method orders the coordinates, rings of a polygon and parts of multi geometries consistently. Typically useful for testing purposes (for example in combination with equals_exact).
Examples
>>> from shapely import MultiLineString >>> line = MultiLineString([[(0, 0), (1, 1)], [(3, 3), (2, 2)]]) >>> line.normalize() <MULTILINESTRING ((2 2, 3 3), (0 0, 1 1))>
- overlaps(other)#
Returns True if geometries overlap, else False
- point_on_surface()#
Returns a point guaranteed to be within the object, cheaply.
Alias of representative_point.
- project(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of line_locate_point.
- relate(other)#
Returns the DE-9IM intersection matrix for the two geometries (string)
- relate_pattern(other, pattern)#
Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
- representative_point()#
Returns a point guaranteed to be within the object, cheaply.
Alias of point_on_surface.
- reverse()#
Returns a copy of this geometry with the order of coordinates reversed.
If the geometry is a polygon with interior rings, the interior rings are also reversed.
Points are unchanged.
See also
is_ccw
Checks if a geometry is clockwise.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (1, 2)]).reverse() <LINESTRING (1 2, 0 0)> >>> Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]).reverse() <POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))>
- segmentize(tolerance)#
Adds vertices to line segments based on tolerance.
Additional vertices will be added to every line segment in an input geometry so that segments are no greater than tolerance. New vertices will evenly subdivide each segment.
Only linear components of input geometries are densified; other geometries are returned unmodified.
- Parameters
- tolerancefloat or array_like
Additional vertices will be added so that all line segments are no greater than this value. Must be greater than 0.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (0, 10)]).segmentize(tolerance=5) <LINESTRING (0 0, 0 5, 0 10)> >>> Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]).segmentize(tolerance=5) <POLYGON ((0 0, 5 0, 10 0, 10 5, 10 10, 5 10, 0 10, 0 5, 0 0))>
- simplify(tolerance, preserve_topology=True)#
Returns a simplified geometry produced by the Douglas-Peucker algorithm
Coordinates of the simplified geometry will be no more than the tolerance distance from the original. Unless the topology preserving option is used, the algorithm may produce self-intersecting or otherwise invalid geometries.
- svg(scale_factor=1.0, color=None)#
Returns a group of SVG elements for the multipart geometry.
- Parameters
- scale_factorfloat
Multiplication factor for the SVG stroke-width. Default is 1.
- colorstr, optional
Hex string for stroke or fill color. Default is to use “#66cc99” if geometry is valid, and “#ff3333” if invalid.
- symmetric_difference(other)#
Returns the symmetric difference of the geometries (Shapely geometry)
- touches(other)#
Returns True if geometries touch, else False
- union(other)#
Returns the union of the geometries (Shapely geometry)
- within(other)#
Returns True if geometry is within the other, else False
- property wkb#
WKB representation of the geometry
- property wkb_hex#
WKB hex representation of the geometry
- property wkt#
WKT representation of the geometry
- property xy#
Separate arrays of X and Y coordinate values
- class LineString(coordinates=None)#
Bases:
shapely.geometry.base.BaseGeometry
A geometry type composed of one or more line segments.
A LineString is a one-dimensional feature and has a non-zero length but zero area. It may approximate a curve and need not be straight. Unlike a LinearRing, a LineString is not closed.
- Parameters
- coordinatessequence
A sequence of (x, y, [,z]) numeric coordinate pairs or triples, or an array-like with shape (N, 2) or (N, 3). Also can be a sequence of Point objects.
Examples
Create a LineString with two segments
>>> a = LineString([[0, 0], [1, 0], [1, 1]]) >>> a.length 2.0
- Attributes
area
Unitless area of the geometry (float)
boundary
Returns a lower dimension geometry that bounds the object
bounds
Returns minimum bounding region (minx, miny, maxx, maxy)
centroid
Returns the geometric center of the object
convex_hull
Imagine an elastic band stretched around the geometry: that’s a
coords
Access to geometry’s coordinates (CoordinateSequence)
envelope
A figure that envelopes the geometry
geom_type
Name of the geometry’s type, such as ‘Point’
has_z
True if the geometry’s coordinate sequence(s) have z values (are
is_closed
True if the geometry is closed, else False
is_empty
True if the set of points in this geometry is empty, else False
is_ring
True if the geometry is a closed ring, else False
is_simple
True if the geometry is simple, meaning that any self-intersections
is_valid
True if the geometry is valid (definition depends on sub-class),
length
Unitless length of the geometry (float)
minimum_clearance
Unitless distance by which a node could be moved to produce an invalid geometry (float)
minimum_rotated_rectangle
Returns the general minimum bounding rectangle of the geometry.
- type
wkb
WKB representation of the geometry
wkb_hex
WKB hex representation of the geometry
wkt
WKT representation of the geometry
xy
Separate arrays of X and Y coordinate values
Methods
almost_equals
(other[, decimal])True if geometries are equal at all coordinates to a specified decimal place.
buffer
(distance[, resolution, quadsegs, ...])Get a geometry that represents all points within a distance of this geometry.
contains
(other)Returns True if the geometry contains the other, else False
covered_by
(other)Returns True if the geometry is covered by the other, else False
covers
(other)Returns True if the geometry covers the other, else False
crosses
(other)Returns True if the geometries cross, else False
difference
(other)Returns the difference of the geometries
disjoint
(other)Returns True if geometries are disjoint, else False
distance
(other)Unitless distance to other geometry (float)
equals
(other)Returns True if geometries are equal, else False.
equals_exact
(other, tolerance)True if geometries are equal to within a specified tolerance.
hausdorff_distance
(other)Unitless hausdorff distance to other geometry (float)
interpolate
(distance[, normalized])Return a point at the specified distance along a linear geometry
intersection
(other)Returns the intersection of the geometries
intersects
(other)Returns True if geometries intersect, else False
line_interpolate_point
(distance[, normalized])Return a point at the specified distance along a linear geometry
line_locate_point
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
Converts geometry to normal form (or canonical form).
overlaps
(other)Returns True if geometries overlap, else False
parallel_offset
(distance[, side, ...])Returns a LineString or MultiLineString geometry at a distance from the object on its right or its left side.
Returns a point guaranteed to be within the object, cheaply.
project
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
relate
(other)Returns the DE-9IM intersection matrix for the two geometries (string)
relate_pattern
(other, pattern)Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
Returns a point guaranteed to be within the object, cheaply.
reverse
()Returns a copy of this geometry with the order of coordinates reversed.
segmentize
(tolerance)Adds vertices to line segments based on tolerance.
simplify
(tolerance[, preserve_topology])Returns a simplified geometry produced by the Douglas-Peucker algorithm
svg
([scale_factor, stroke_color, opacity])Returns SVG polyline element for the LineString geometry.
symmetric_difference
(other)Returns the symmetric difference of the geometries (Shapely geometry)
touches
(other)Returns True if geometries touch, else False
union
(other)Returns the union of the geometries (Shapely geometry)
within
(other)Returns True if geometry is within the other, else False
geometryType
- __eq__(value, /)#
Return self==value.
- __ge__(value, /)#
Return self>=value.
- property __geo_interface__#
Dictionary representation of the geometry
- __gt__(value, /)#
Return self>value.
- __hash__(/)#
Return hash(self).
- __le__(value, /)#
Return self<=value.
- __lt__(value, /)#
Return self<value.
- __ne__(value, /)#
Return self!=value.
- static __new__(self, coordinates=None)#
- __or__(other)#
Return self|value.
- __reduce__()#
Helper for pickle.
- __repr__()#
Return repr(self).
- __str__()#
Return str(self).
- almost_equals(other, decimal=6)#
True if geometries are equal at all coordinates to a specified decimal place.
Deprecated since version 1.8.0: The ‘almost_equals()’ method is deprecated and will be removed in Shapely 2.0 because the name is confusing. The ‘equals_exact()’ method should be used instead.
Refers to approximate coordinate equality, which requires coordinates to be approximately equal and in the same order for all components of a geometry.
Because of this it is possible for “equals()” to be True for two geometries and “almost_equals()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property area#
Unitless area of the geometry (float)
- property boundary#
Returns a lower dimension geometry that bounds the object
The boundary of a polygon is a line, the boundary of a line is a collection of points. The boundary of a point is an empty (null) collection.
- property bounds#
Returns minimum bounding region (minx, miny, maxx, maxy)
- buffer(distance, resolution=16, quadsegs=None, cap_style=1, join_style=1, mitre_limit=5.0, single_sided=False)#
Get a geometry that represents all points within a distance of this geometry.
A positive distance produces a dilation, a negative distance an erosion. A very small or zero distance may sometimes be used to “tidy” a polygon.
- Parameters
- distancefloat
The distance to buffer around the object.
- resolutionint, optional
The resolution of the buffer around each vertex of the object.
- quadsegsint, optional
Sets the number of line segments used to approximate an angle fillet. Note: the use of a quadsegs parameter is deprecated and will be gone from the next major release.
- cap_styleint, optional
The styles of caps are: CAP_STYLE.round (1), CAP_STYLE.flat (2), and CAP_STYLE.square (3).
- join_styleint, optional
The styles of joins between offset segments are: JOIN_STYLE.round (1), JOIN_STYLE.mitre (2), and JOIN_STYLE.bevel (3).
- mitre_limitfloat, optional
The mitre limit ratio is used for very sharp corners. The mitre ratio is the ratio of the distance from the corner to the end of the mitred offset corner. When two line segments meet at a sharp angle, a miter join will extend the original geometry. To prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. Corners with a ratio which exceed the limit will be beveled.
- single_sidebool, optional
The side used is determined by the sign of the buffer distance:
a positive distance indicates the left-hand side a negative distance indicates the right-hand side
The single-sided buffer of point geometries is the same as the regular buffer. The End Cap Style for single-sided buffers is always ignored, and forced to the equivalent of CAP_FLAT.
- Returns
- Geometry
Notes
The return value is a strictly two-dimensional geometry. All Z coordinates of the original geometry will be ignored.
Examples
>>> from shapely.wkt import loads >>> g = loads('POINT (0.0 0.0)')
16-gon approx of a unit radius circle:
>>> g.buffer(1.0).area 3.1365484905459...
128-gon approximation:
>>> g.buffer(1.0, 128).area 3.141513801144...
triangle approximation:
>>> g.buffer(1.0, 3).area 3.0 >>> list(g.buffer(1.0, cap_style=CAP_STYLE.square).exterior.coords) [(1.0, 1.0), (1.0, -1.0), (-1.0, -1.0), (-1.0, 1.0), (1.0, 1.0)] >>> g.buffer(1.0, cap_style=CAP_STYLE.square).area 4.0
- property centroid#
Returns the geometric center of the object
- contains(other)#
Returns True if the geometry contains the other, else False
- property convex_hull#
Imagine an elastic band stretched around the geometry: that’s a convex hull, more or less
The convex hull of a three member multipoint, for example, is a triangular polygon.
- property coords#
Access to geometry’s coordinates (CoordinateSequence)
- covered_by(other)#
Returns True if the geometry is covered by the other, else False
- covers(other)#
Returns True if the geometry covers the other, else False
- crosses(other)#
Returns True if the geometries cross, else False
- difference(other)#
Returns the difference of the geometries
- disjoint(other)#
Returns True if geometries are disjoint, else False
- distance(other)#
Unitless distance to other geometry (float)
- property envelope#
A figure that envelopes the geometry
- equals(other)#
Returns True if geometries are equal, else False.
This method considers point-set equality (or topological equality), and is equivalent to (self.within(other) & self.contains(other)).
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals( ... LineString([(0, 0), (1, 1), (2, 2)]) ... ) True
- equals_exact(other, tolerance)#
True if geometries are equal to within a specified tolerance.
- Parameters
- otherBaseGeometry
The other geometry object in this comparison.
- tolerancefloat
Absolute tolerance in the same units as coordinates.
- This method considers coordinate equality, which requires
- coordinates to be equal and in the same order for all components
- of a geometry.
- Because of this it is possible for “equals()” to be True for two
- geometries and “equals_exact()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property geom_type#
Name of the geometry’s type, such as ‘Point’
- property has_z#
True if the geometry’s coordinate sequence(s) have z values (are 3-dimensional)
- hausdorff_distance(other)#
Unitless hausdorff distance to other geometry (float)
- interpolate(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of line_interpolate_point.
- intersection(other)#
Returns the intersection of the geometries
- intersects(other)#
Returns True if geometries intersect, else False
- property is_closed#
True if the geometry is closed, else False
Applicable only to 1-D geometries.
- property is_empty#
True if the set of points in this geometry is empty, else False
- property is_ring#
True if the geometry is a closed ring, else False
- property is_simple#
True if the geometry is simple, meaning that any self-intersections are only at boundary points, else False
- property is_valid#
True if the geometry is valid (definition depends on sub-class), else False
- property length#
Unitless length of the geometry (float)
- line_interpolate_point(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of interpolate.
- line_locate_point(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of project.
- property minimum_clearance#
Unitless distance by which a node could be moved to produce an invalid geometry (float)
- property minimum_rotated_rectangle#
Returns the general minimum bounding rectangle of the geometry. Can possibly be rotated. If the convex hull of the object is a degenerate (line or point) this same degenerate is returned.
- normalize()#
Converts geometry to normal form (or canonical form).
This method orders the coordinates, rings of a polygon and parts of multi geometries consistently. Typically useful for testing purposes (for example in combination with equals_exact).
Examples
>>> from shapely import MultiLineString >>> line = MultiLineString([[(0, 0), (1, 1)], [(3, 3), (2, 2)]]) >>> line.normalize() <MULTILINESTRING ((2 2, 3 3), (0 0, 1 1))>
- overlaps(other)#
Returns True if geometries overlap, else False
- parallel_offset(distance, side='right', resolution=16, join_style=1, mitre_limit=5.0)#
Returns a LineString or MultiLineString geometry at a distance from the object on its right or its left side.
The side parameter may be ‘left’ or ‘right’ (default is ‘right’). The resolution of the buffer around each vertex of the object increases by increasing the resolution keyword parameter or third positional parameter. Vertices of right hand offset lines will be ordered in reverse.
The join style is for outside corners between line segments. Accepted values are JOIN_STYLE.round (1), JOIN_STYLE.mitre (2), and JOIN_STYLE.bevel (3).
The mitre ratio limit is used for very sharp corners. It is the ratio of the distance from the corner to the end of the mitred offset corner. When two line segments meet at a sharp angle, a miter join will extend far beyond the original geometry. To prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. Corners with a ratio which exceed the limit will be beveled.
- point_on_surface()#
Returns a point guaranteed to be within the object, cheaply.
Alias of representative_point.
- project(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of line_locate_point.
- relate(other)#
Returns the DE-9IM intersection matrix for the two geometries (string)
- relate_pattern(other, pattern)#
Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
- representative_point()#
Returns a point guaranteed to be within the object, cheaply.
Alias of point_on_surface.
- reverse()#
Returns a copy of this geometry with the order of coordinates reversed.
If the geometry is a polygon with interior rings, the interior rings are also reversed.
Points are unchanged.
See also
is_ccw
Checks if a geometry is clockwise.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (1, 2)]).reverse() <LINESTRING (1 2, 0 0)> >>> Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]).reverse() <POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))>
- segmentize(tolerance)#
Adds vertices to line segments based on tolerance.
Additional vertices will be added to every line segment in an input geometry so that segments are no greater than tolerance. New vertices will evenly subdivide each segment.
Only linear components of input geometries are densified; other geometries are returned unmodified.
- Parameters
- tolerancefloat or array_like
Additional vertices will be added so that all line segments are no greater than this value. Must be greater than 0.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (0, 10)]).segmentize(tolerance=5) <LINESTRING (0 0, 0 5, 0 10)> >>> Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]).segmentize(tolerance=5) <POLYGON ((0 0, 5 0, 10 0, 10 5, 10 10, 5 10, 0 10, 0 5, 0 0))>
- simplify(tolerance, preserve_topology=True)#
Returns a simplified geometry produced by the Douglas-Peucker algorithm
Coordinates of the simplified geometry will be no more than the tolerance distance from the original. Unless the topology preserving option is used, the algorithm may produce self-intersecting or otherwise invalid geometries.
- svg(scale_factor=1.0, stroke_color=None, opacity=None)#
Returns SVG polyline element for the LineString geometry.
- Parameters
- scale_factorfloat
Multiplication factor for the SVG stroke-width. Default is 1.
- stroke_colorstr, optional
Hex string for stroke color. Default is to use “#66cc99” if geometry is valid, and “#ff3333” if invalid.
- opacityfloat
Float number between 0 and 1 for color opacity. Default value is 0.8
- symmetric_difference(other)#
Returns the symmetric difference of the geometries (Shapely geometry)
- touches(other)#
Returns True if geometries touch, else False
- union(other)#
Returns the union of the geometries (Shapely geometry)
- within(other)#
Returns True if geometry is within the other, else False
- property wkb#
WKB representation of the geometry
- property wkb_hex#
WKB hex representation of the geometry
- property wkt#
WKT representation of the geometry
- property xy#
Separate arrays of X and Y coordinate values
Example:
>>> x, y = LineString([(0, 0), (1, 1)]).xy >>> list(x) [0.0, 1.0] >>> list(y) [0.0, 1.0]
- class LinearRing(coordinates=None)#
Bases:
shapely.geometry.linestring.LineString
A geometry type composed of one or more line segments that forms a closed loop.
A LinearRing is a closed, one-dimensional feature. A LinearRing that crosses itself or touches itself at a single point is invalid and operations on it may fail.
- Parameters
- coordinatessequence
A sequence of (x, y [,z]) numeric coordinate pairs or triples, or an array-like with shape (N, 2) or (N, 3). Also can be a sequence of Point objects.
Notes
Rings are automatically closed. There is no need to specify a final coordinate pair identical to the first.
Examples
Construct a square ring.
>>> ring = LinearRing( ((0, 0), (0, 1), (1 ,1 ), (1 , 0)) ) >>> ring.is_closed True >>> list(ring.coords) [(0.0, 0.0), (0.0, 1.0), (1.0, 1.0), (1.0, 0.0), (0.0, 0.0)] >>> ring.length 4.0
- Attributes
area
Unitless area of the geometry (float)
boundary
Returns a lower dimension geometry that bounds the object
bounds
Returns minimum bounding region (minx, miny, maxx, maxy)
centroid
Returns the geometric center of the object
convex_hull
Imagine an elastic band stretched around the geometry: that’s a
coords
Access to geometry’s coordinates (CoordinateSequence)
envelope
A figure that envelopes the geometry
geom_type
Name of the geometry’s type, such as ‘Point’
has_z
True if the geometry’s coordinate sequence(s) have z values (are
is_ccw
True is the ring is oriented counter clock-wise
is_closed
True if the geometry is closed, else False
is_empty
True if the set of points in this geometry is empty, else False
is_ring
True if the geometry is a closed ring, else False
is_simple
True if the geometry is simple, meaning that any self-intersections
is_valid
True if the geometry is valid (definition depends on sub-class),
length
Unitless length of the geometry (float)
minimum_clearance
Unitless distance by which a node could be moved to produce an invalid geometry (float)
minimum_rotated_rectangle
Returns the general minimum bounding rectangle of the geometry.
- type
wkb
WKB representation of the geometry
wkb_hex
WKB hex representation of the geometry
wkt
WKT representation of the geometry
xy
Separate arrays of X and Y coordinate values
Methods
almost_equals
(other[, decimal])True if geometries are equal at all coordinates to a specified decimal place.
buffer
(distance[, resolution, quadsegs, ...])Get a geometry that represents all points within a distance of this geometry.
contains
(other)Returns True if the geometry contains the other, else False
covered_by
(other)Returns True if the geometry is covered by the other, else False
covers
(other)Returns True if the geometry covers the other, else False
crosses
(other)Returns True if the geometries cross, else False
difference
(other)Returns the difference of the geometries
disjoint
(other)Returns True if geometries are disjoint, else False
distance
(other)Unitless distance to other geometry (float)
equals
(other)Returns True if geometries are equal, else False.
equals_exact
(other, tolerance)True if geometries are equal to within a specified tolerance.
hausdorff_distance
(other)Unitless hausdorff distance to other geometry (float)
interpolate
(distance[, normalized])Return a point at the specified distance along a linear geometry
intersection
(other)Returns the intersection of the geometries
intersects
(other)Returns True if geometries intersect, else False
line_interpolate_point
(distance[, normalized])Return a point at the specified distance along a linear geometry
line_locate_point
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
Converts geometry to normal form (or canonical form).
overlaps
(other)Returns True if geometries overlap, else False
parallel_offset
(distance[, side, ...])Returns a LineString or MultiLineString geometry at a distance from the object on its right or its left side.
Returns a point guaranteed to be within the object, cheaply.
project
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
relate
(other)Returns the DE-9IM intersection matrix for the two geometries (string)
relate_pattern
(other, pattern)Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
Returns a point guaranteed to be within the object, cheaply.
reverse
()Returns a copy of this geometry with the order of coordinates reversed.
segmentize
(tolerance)Adds vertices to line segments based on tolerance.
simplify
(tolerance[, preserve_topology])Returns a simplified geometry produced by the Douglas-Peucker algorithm
svg
([scale_factor, stroke_color, opacity])Returns SVG polyline element for the LineString geometry.
symmetric_difference
(other)Returns the symmetric difference of the geometries (Shapely geometry)
touches
(other)Returns True if geometries touch, else False
union
(other)Returns the union of the geometries (Shapely geometry)
within
(other)Returns True if geometry is within the other, else False
geometryType
- __eq__(value, /)#
Return self==value.
- __ge__(value, /)#
Return self>=value.
- property __geo_interface__#
Dictionary representation of the geometry
- __gt__(value, /)#
Return self>value.
- __hash__(/)#
Return hash(self).
- __le__(value, /)#
Return self<=value.
- __lt__(value, /)#
Return self<value.
- __ne__(value, /)#
Return self!=value.
- static __new__(self, coordinates=None)#
- __or__(other)#
Return self|value.
- __reduce__()#
WKB doesn’t differentiate between LineString and LinearRing so we need to move the coordinate sequence into the correct geometry type
- __repr__()#
Return repr(self).
- __str__()#
Return str(self).
- almost_equals(other, decimal=6)#
True if geometries are equal at all coordinates to a specified decimal place.
Deprecated since version 1.8.0: The ‘almost_equals()’ method is deprecated and will be removed in Shapely 2.0 because the name is confusing. The ‘equals_exact()’ method should be used instead.
Refers to approximate coordinate equality, which requires coordinates to be approximately equal and in the same order for all components of a geometry.
Because of this it is possible for “equals()” to be True for two geometries and “almost_equals()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property area#
Unitless area of the geometry (float)
- property boundary#
Returns a lower dimension geometry that bounds the object
The boundary of a polygon is a line, the boundary of a line is a collection of points. The boundary of a point is an empty (null) collection.
- property bounds#
Returns minimum bounding region (minx, miny, maxx, maxy)
- buffer(distance, resolution=16, quadsegs=None, cap_style=1, join_style=1, mitre_limit=5.0, single_sided=False)#
Get a geometry that represents all points within a distance of this geometry.
A positive distance produces a dilation, a negative distance an erosion. A very small or zero distance may sometimes be used to “tidy” a polygon.
- Parameters
- distancefloat
The distance to buffer around the object.
- resolutionint, optional
The resolution of the buffer around each vertex of the object.
- quadsegsint, optional
Sets the number of line segments used to approximate an angle fillet. Note: the use of a quadsegs parameter is deprecated and will be gone from the next major release.
- cap_styleint, optional
The styles of caps are: CAP_STYLE.round (1), CAP_STYLE.flat (2), and CAP_STYLE.square (3).
- join_styleint, optional
The styles of joins between offset segments are: JOIN_STYLE.round (1), JOIN_STYLE.mitre (2), and JOIN_STYLE.bevel (3).
- mitre_limitfloat, optional
The mitre limit ratio is used for very sharp corners. The mitre ratio is the ratio of the distance from the corner to the end of the mitred offset corner. When two line segments meet at a sharp angle, a miter join will extend the original geometry. To prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. Corners with a ratio which exceed the limit will be beveled.
- single_sidebool, optional
The side used is determined by the sign of the buffer distance:
a positive distance indicates the left-hand side a negative distance indicates the right-hand side
The single-sided buffer of point geometries is the same as the regular buffer. The End Cap Style for single-sided buffers is always ignored, and forced to the equivalent of CAP_FLAT.
- Returns
- Geometry
Notes
The return value is a strictly two-dimensional geometry. All Z coordinates of the original geometry will be ignored.
Examples
>>> from shapely.wkt import loads >>> g = loads('POINT (0.0 0.0)')
16-gon approx of a unit radius circle:
>>> g.buffer(1.0).area 3.1365484905459...
128-gon approximation:
>>> g.buffer(1.0, 128).area 3.141513801144...
triangle approximation:
>>> g.buffer(1.0, 3).area 3.0 >>> list(g.buffer(1.0, cap_style=CAP_STYLE.square).exterior.coords) [(1.0, 1.0), (1.0, -1.0), (-1.0, -1.0), (-1.0, 1.0), (1.0, 1.0)] >>> g.buffer(1.0, cap_style=CAP_STYLE.square).area 4.0
- property centroid#
Returns the geometric center of the object
- contains(other)#
Returns True if the geometry contains the other, else False
- property convex_hull#
Imagine an elastic band stretched around the geometry: that’s a convex hull, more or less
The convex hull of a three member multipoint, for example, is a triangular polygon.
- property coords#
Access to geometry’s coordinates (CoordinateSequence)
- covered_by(other)#
Returns True if the geometry is covered by the other, else False
- covers(other)#
Returns True if the geometry covers the other, else False
- crosses(other)#
Returns True if the geometries cross, else False
- difference(other)#
Returns the difference of the geometries
- disjoint(other)#
Returns True if geometries are disjoint, else False
- distance(other)#
Unitless distance to other geometry (float)
- property envelope#
A figure that envelopes the geometry
- equals(other)#
Returns True if geometries are equal, else False.
This method considers point-set equality (or topological equality), and is equivalent to (self.within(other) & self.contains(other)).
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals( ... LineString([(0, 0), (1, 1), (2, 2)]) ... ) True
- equals_exact(other, tolerance)#
True if geometries are equal to within a specified tolerance.
- Parameters
- otherBaseGeometry
The other geometry object in this comparison.
- tolerancefloat
Absolute tolerance in the same units as coordinates.
- This method considers coordinate equality, which requires
- coordinates to be equal and in the same order for all components
- of a geometry.
- Because of this it is possible for “equals()” to be True for two
- geometries and “equals_exact()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property geom_type#
Name of the geometry’s type, such as ‘Point’
- property has_z#
True if the geometry’s coordinate sequence(s) have z values (are 3-dimensional)
- hausdorff_distance(other)#
Unitless hausdorff distance to other geometry (float)
- interpolate(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of line_interpolate_point.
- intersection(other)#
Returns the intersection of the geometries
- intersects(other)#
Returns True if geometries intersect, else False
- property is_ccw#
True is the ring is oriented counter clock-wise
- property is_closed#
True if the geometry is closed, else False
Applicable only to 1-D geometries.
- property is_empty#
True if the set of points in this geometry is empty, else False
- property is_ring#
True if the geometry is a closed ring, else False
- property is_simple#
True if the geometry is simple, meaning that any self-intersections are only at boundary points, else False
- property is_valid#
True if the geometry is valid (definition depends on sub-class), else False
- property length#
Unitless length of the geometry (float)
- line_interpolate_point(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of interpolate.
- line_locate_point(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of project.
- property minimum_clearance#
Unitless distance by which a node could be moved to produce an invalid geometry (float)
- property minimum_rotated_rectangle#
Returns the general minimum bounding rectangle of the geometry. Can possibly be rotated. If the convex hull of the object is a degenerate (line or point) this same degenerate is returned.
- normalize()#
Converts geometry to normal form (or canonical form).
This method orders the coordinates, rings of a polygon and parts of multi geometries consistently. Typically useful for testing purposes (for example in combination with equals_exact).
Examples
>>> from shapely import MultiLineString >>> line = MultiLineString([[(0, 0), (1, 1)], [(3, 3), (2, 2)]]) >>> line.normalize() <MULTILINESTRING ((2 2, 3 3), (0 0, 1 1))>
- overlaps(other)#
Returns True if geometries overlap, else False
- parallel_offset(distance, side='right', resolution=16, join_style=1, mitre_limit=5.0)#
Returns a LineString or MultiLineString geometry at a distance from the object on its right or its left side.
The side parameter may be ‘left’ or ‘right’ (default is ‘right’). The resolution of the buffer around each vertex of the object increases by increasing the resolution keyword parameter or third positional parameter. Vertices of right hand offset lines will be ordered in reverse.
The join style is for outside corners between line segments. Accepted values are JOIN_STYLE.round (1), JOIN_STYLE.mitre (2), and JOIN_STYLE.bevel (3).
The mitre ratio limit is used for very sharp corners. It is the ratio of the distance from the corner to the end of the mitred offset corner. When two line segments meet at a sharp angle, a miter join will extend far beyond the original geometry. To prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. Corners with a ratio which exceed the limit will be beveled.
- point_on_surface()#
Returns a point guaranteed to be within the object, cheaply.
Alias of representative_point.
- project(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of line_locate_point.
- relate(other)#
Returns the DE-9IM intersection matrix for the two geometries (string)
- relate_pattern(other, pattern)#
Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
- representative_point()#
Returns a point guaranteed to be within the object, cheaply.
Alias of point_on_surface.
- reverse()#
Returns a copy of this geometry with the order of coordinates reversed.
If the geometry is a polygon with interior rings, the interior rings are also reversed.
Points are unchanged.
See also
is_ccw
Checks if a geometry is clockwise.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (1, 2)]).reverse() <LINESTRING (1 2, 0 0)> >>> Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]).reverse() <POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))>
- segmentize(tolerance)#
Adds vertices to line segments based on tolerance.
Additional vertices will be added to every line segment in an input geometry so that segments are no greater than tolerance. New vertices will evenly subdivide each segment.
Only linear components of input geometries are densified; other geometries are returned unmodified.
- Parameters
- tolerancefloat or array_like
Additional vertices will be added so that all line segments are no greater than this value. Must be greater than 0.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (0, 10)]).segmentize(tolerance=5) <LINESTRING (0 0, 0 5, 0 10)> >>> Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]).segmentize(tolerance=5) <POLYGON ((0 0, 5 0, 10 0, 10 5, 10 10, 5 10, 0 10, 0 5, 0 0))>
- simplify(tolerance, preserve_topology=True)#
Returns a simplified geometry produced by the Douglas-Peucker algorithm
Coordinates of the simplified geometry will be no more than the tolerance distance from the original. Unless the topology preserving option is used, the algorithm may produce self-intersecting or otherwise invalid geometries.
- svg(scale_factor=1.0, stroke_color=None, opacity=None)#
Returns SVG polyline element for the LineString geometry.
- Parameters
- scale_factorfloat
Multiplication factor for the SVG stroke-width. Default is 1.
- stroke_colorstr, optional
Hex string for stroke color. Default is to use “#66cc99” if geometry is valid, and “#ff3333” if invalid.
- opacityfloat
Float number between 0 and 1 for color opacity. Default value is 0.8
- symmetric_difference(other)#
Returns the symmetric difference of the geometries (Shapely geometry)
- touches(other)#
Returns True if geometries touch, else False
- union(other)#
Returns the union of the geometries (Shapely geometry)
- within(other)#
Returns True if geometry is within the other, else False
- property wkb#
WKB representation of the geometry
- property wkb_hex#
WKB hex representation of the geometry
- property wkt#
WKT representation of the geometry
- property xy#
Separate arrays of X and Y coordinate values
Example:
>>> x, y = LineString([(0, 0), (1, 1)]).xy >>> list(x) [0.0, 1.0] >>> list(y) [0.0, 1.0]
- class MultiLineString(lines=None)#
Bases:
shapely.geometry.base.BaseMultipartGeometry
A collection of one or more LineStrings.
A MultiLineString has non-zero length and zero area.
- Parameters
- linessequence
A sequence LineStrings, or a sequence of line-like coordinate sequences or array-likes (see accepted input for LineString).
Examples
Construct a MultiLineString containing two LineStrings.
>>> lines = MultiLineString([[[0, 0], [1, 2]], [[4, 4], [5, 6]]])
- Attributes
- geomssequence
A sequence of LineStrings
Methods
almost_equals
(other[, decimal])True if geometries are equal at all coordinates to a specified decimal place.
buffer
(distance[, resolution, quadsegs, ...])Get a geometry that represents all points within a distance of this geometry.
contains
(other)Returns True if the geometry contains the other, else False
covered_by
(other)Returns True if the geometry is covered by the other, else False
covers
(other)Returns True if the geometry covers the other, else False
crosses
(other)Returns True if the geometries cross, else False
difference
(other)Returns the difference of the geometries
disjoint
(other)Returns True if geometries are disjoint, else False
distance
(other)Unitless distance to other geometry (float)
equals
(other)Returns True if geometries are equal, else False.
equals_exact
(other, tolerance)True if geometries are equal to within a specified tolerance.
hausdorff_distance
(other)Unitless hausdorff distance to other geometry (float)
interpolate
(distance[, normalized])Return a point at the specified distance along a linear geometry
intersection
(other)Returns the intersection of the geometries
intersects
(other)Returns True if geometries intersect, else False
line_interpolate_point
(distance[, normalized])Return a point at the specified distance along a linear geometry
line_locate_point
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
Converts geometry to normal form (or canonical form).
overlaps
(other)Returns True if geometries overlap, else False
Returns a point guaranteed to be within the object, cheaply.
project
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
relate
(other)Returns the DE-9IM intersection matrix for the two geometries (string)
relate_pattern
(other, pattern)Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
Returns a point guaranteed to be within the object, cheaply.
reverse
()Returns a copy of this geometry with the order of coordinates reversed.
segmentize
(tolerance)Adds vertices to line segments based on tolerance.
simplify
(tolerance[, preserve_topology])Returns a simplified geometry produced by the Douglas-Peucker algorithm
svg
([scale_factor, stroke_color, opacity])Returns a group of SVG polyline elements for the LineString geometry.
symmetric_difference
(other)Returns the symmetric difference of the geometries (Shapely geometry)
touches
(other)Returns True if geometries touch, else False
union
(other)Returns the union of the geometries (Shapely geometry)
within
(other)Returns True if geometry is within the other, else False
geometryType
- __eq__(value, /)#
Return self==value.
- __ge__(value, /)#
Return self>=value.
- property __geo_interface__#
Dictionary representation of the geometry
- __gt__(value, /)#
Return self>value.
- __hash__(/)#
Return hash(self).
- __le__(value, /)#
Return self<=value.
- __lt__(value, /)#
Return self<value.
- __ne__(value, /)#
Return self!=value.
- static __new__(self, lines=None)#
- __or__(other)#
Return self|value.
- __reduce__()#
Helper for pickle.
- __repr__()#
Return repr(self).
- __str__()#
Return str(self).
- almost_equals(other, decimal=6)#
True if geometries are equal at all coordinates to a specified decimal place.
Deprecated since version 1.8.0: The ‘almost_equals()’ method is deprecated and will be removed in Shapely 2.0 because the name is confusing. The ‘equals_exact()’ method should be used instead.
Refers to approximate coordinate equality, which requires coordinates to be approximately equal and in the same order for all components of a geometry.
Because of this it is possible for “equals()” to be True for two geometries and “almost_equals()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property area#
Unitless area of the geometry (float)
- property boundary#
Returns a lower dimension geometry that bounds the object
The boundary of a polygon is a line, the boundary of a line is a collection of points. The boundary of a point is an empty (null) collection.
- property bounds#
Returns minimum bounding region (minx, miny, maxx, maxy)
- buffer(distance, resolution=16, quadsegs=None, cap_style=1, join_style=1, mitre_limit=5.0, single_sided=False)#
Get a geometry that represents all points within a distance of this geometry.
A positive distance produces a dilation, a negative distance an erosion. A very small or zero distance may sometimes be used to “tidy” a polygon.
- Parameters
- distancefloat
The distance to buffer around the object.
- resolutionint, optional
The resolution of the buffer around each vertex of the object.
- quadsegsint, optional
Sets the number of line segments used to approximate an angle fillet. Note: the use of a quadsegs parameter is deprecated and will be gone from the next major release.
- cap_styleint, optional
The styles of caps are: CAP_STYLE.round (1), CAP_STYLE.flat (2), and CAP_STYLE.square (3).
- join_styleint, optional
The styles of joins between offset segments are: JOIN_STYLE.round (1), JOIN_STYLE.mitre (2), and JOIN_STYLE.bevel (3).
- mitre_limitfloat, optional
The mitre limit ratio is used for very sharp corners. The mitre ratio is the ratio of the distance from the corner to the end of the mitred offset corner. When two line segments meet at a sharp angle, a miter join will extend the original geometry. To prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. Corners with a ratio which exceed the limit will be beveled.
- single_sidebool, optional
The side used is determined by the sign of the buffer distance:
a positive distance indicates the left-hand side a negative distance indicates the right-hand side
The single-sided buffer of point geometries is the same as the regular buffer. The End Cap Style for single-sided buffers is always ignored, and forced to the equivalent of CAP_FLAT.
- Returns
- Geometry
Notes
The return value is a strictly two-dimensional geometry. All Z coordinates of the original geometry will be ignored.
Examples
>>> from shapely.wkt import loads >>> g = loads('POINT (0.0 0.0)')
16-gon approx of a unit radius circle:
>>> g.buffer(1.0).area 3.1365484905459...
128-gon approximation:
>>> g.buffer(1.0, 128).area 3.141513801144...
triangle approximation:
>>> g.buffer(1.0, 3).area 3.0 >>> list(g.buffer(1.0, cap_style=CAP_STYLE.square).exterior.coords) [(1.0, 1.0), (1.0, -1.0), (-1.0, -1.0), (-1.0, 1.0), (1.0, 1.0)] >>> g.buffer(1.0, cap_style=CAP_STYLE.square).area 4.0
- property centroid#
Returns the geometric center of the object
- contains(other)#
Returns True if the geometry contains the other, else False
- property convex_hull#
Imagine an elastic band stretched around the geometry: that’s a convex hull, more or less
The convex hull of a three member multipoint, for example, is a triangular polygon.
- property coords#
Access to geometry’s coordinates (CoordinateSequence)
- covered_by(other)#
Returns True if the geometry is covered by the other, else False
- covers(other)#
Returns True if the geometry covers the other, else False
- crosses(other)#
Returns True if the geometries cross, else False
- difference(other)#
Returns the difference of the geometries
- disjoint(other)#
Returns True if geometries are disjoint, else False
- distance(other)#
Unitless distance to other geometry (float)
- property envelope#
A figure that envelopes the geometry
- equals(other)#
Returns True if geometries are equal, else False.
This method considers point-set equality (or topological equality), and is equivalent to (self.within(other) & self.contains(other)).
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals( ... LineString([(0, 0), (1, 1), (2, 2)]) ... ) True
- equals_exact(other, tolerance)#
True if geometries are equal to within a specified tolerance.
- Parameters
- otherBaseGeometry
The other geometry object in this comparison.
- tolerancefloat
Absolute tolerance in the same units as coordinates.
- This method considers coordinate equality, which requires
- coordinates to be equal and in the same order for all components
- of a geometry.
- Because of this it is possible for “equals()” to be True for two
- geometries and “equals_exact()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property geom_type#
Name of the geometry’s type, such as ‘Point’
- property has_z#
True if the geometry’s coordinate sequence(s) have z values (are 3-dimensional)
- hausdorff_distance(other)#
Unitless hausdorff distance to other geometry (float)
- interpolate(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of line_interpolate_point.
- intersection(other)#
Returns the intersection of the geometries
- intersects(other)#
Returns True if geometries intersect, else False
- property is_closed#
True if the geometry is closed, else False
Applicable only to 1-D geometries.
- property is_empty#
True if the set of points in this geometry is empty, else False
- property is_ring#
True if the geometry is a closed ring, else False
- property is_simple#
True if the geometry is simple, meaning that any self-intersections are only at boundary points, else False
- property is_valid#
True if the geometry is valid (definition depends on sub-class), else False
- property length#
Unitless length of the geometry (float)
- line_interpolate_point(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of interpolate.
- line_locate_point(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of project.
- property minimum_clearance#
Unitless distance by which a node could be moved to produce an invalid geometry (float)
- property minimum_rotated_rectangle#
Returns the general minimum bounding rectangle of the geometry. Can possibly be rotated. If the convex hull of the object is a degenerate (line or point) this same degenerate is returned.
- normalize()#
Converts geometry to normal form (or canonical form).
This method orders the coordinates, rings of a polygon and parts of multi geometries consistently. Typically useful for testing purposes (for example in combination with equals_exact).
Examples
>>> from shapely import MultiLineString >>> line = MultiLineString([[(0, 0), (1, 1)], [(3, 3), (2, 2)]]) >>> line.normalize() <MULTILINESTRING ((2 2, 3 3), (0 0, 1 1))>
- overlaps(other)#
Returns True if geometries overlap, else False
- point_on_surface()#
Returns a point guaranteed to be within the object, cheaply.
Alias of representative_point.
- project(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of line_locate_point.
- relate(other)#
Returns the DE-9IM intersection matrix for the two geometries (string)
- relate_pattern(other, pattern)#
Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
- representative_point()#
Returns a point guaranteed to be within the object, cheaply.
Alias of point_on_surface.
- reverse()#
Returns a copy of this geometry with the order of coordinates reversed.
If the geometry is a polygon with interior rings, the interior rings are also reversed.
Points are unchanged.
See also
is_ccw
Checks if a geometry is clockwise.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (1, 2)]).reverse() <LINESTRING (1 2, 0 0)> >>> Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]).reverse() <POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))>
- segmentize(tolerance)#
Adds vertices to line segments based on tolerance.
Additional vertices will be added to every line segment in an input geometry so that segments are no greater than tolerance. New vertices will evenly subdivide each segment.
Only linear components of input geometries are densified; other geometries are returned unmodified.
- Parameters
- tolerancefloat or array_like
Additional vertices will be added so that all line segments are no greater than this value. Must be greater than 0.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (0, 10)]).segmentize(tolerance=5) <LINESTRING (0 0, 0 5, 0 10)> >>> Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]).segmentize(tolerance=5) <POLYGON ((0 0, 5 0, 10 0, 10 5, 10 10, 5 10, 0 10, 0 5, 0 0))>
- simplify(tolerance, preserve_topology=True)#
Returns a simplified geometry produced by the Douglas-Peucker algorithm
Coordinates of the simplified geometry will be no more than the tolerance distance from the original. Unless the topology preserving option is used, the algorithm may produce self-intersecting or otherwise invalid geometries.
- svg(scale_factor=1.0, stroke_color=None, opacity=None)#
Returns a group of SVG polyline elements for the LineString geometry.
- Parameters
- scale_factorfloat
Multiplication factor for the SVG stroke-width. Default is 1.
- stroke_colorstr, optional
Hex string for stroke color. Default is to use “#66cc99” if geometry is valid, and “#ff3333” if invalid.
- opacityfloat
Float number between 0 and 1 for color opacity. Default value is 0.8
- symmetric_difference(other)#
Returns the symmetric difference of the geometries (Shapely geometry)
- touches(other)#
Returns True if geometries touch, else False
- union(other)#
Returns the union of the geometries (Shapely geometry)
- within(other)#
Returns True if geometry is within the other, else False
- property wkb#
WKB representation of the geometry
- property wkb_hex#
WKB hex representation of the geometry
- property wkt#
WKT representation of the geometry
- property xy#
Separate arrays of X and Y coordinate values
- class MultiPoint(points=None)#
Bases:
shapely.geometry.base.BaseMultipartGeometry
A collection of one or more Points.
A MultiPoint has zero area and zero length.
- Parameters
- pointssequence
A sequence of Points, or a sequence of (x, y [,z]) numeric coordinate pairs or triples, or an array-like of shape (N, 2) or (N, 3).
Examples
Construct a MultiPoint containing two Points
>>> from shapely import Point >>> ob = MultiPoint([[0.0, 0.0], [1.0, 2.0]]) >>> len(ob.geoms) 2 >>> type(ob.geoms[0]) == Point True
- Attributes
- geomssequence
A sequence of Points
Methods
almost_equals
(other[, decimal])True if geometries are equal at all coordinates to a specified decimal place.
buffer
(distance[, resolution, quadsegs, ...])Get a geometry that represents all points within a distance of this geometry.
contains
(other)Returns True if the geometry contains the other, else False
covered_by
(other)Returns True if the geometry is covered by the other, else False
covers
(other)Returns True if the geometry covers the other, else False
crosses
(other)Returns True if the geometries cross, else False
difference
(other)Returns the difference of the geometries
disjoint
(other)Returns True if geometries are disjoint, else False
distance
(other)Unitless distance to other geometry (float)
equals
(other)Returns True if geometries are equal, else False.
equals_exact
(other, tolerance)True if geometries are equal to within a specified tolerance.
hausdorff_distance
(other)Unitless hausdorff distance to other geometry (float)
interpolate
(distance[, normalized])Return a point at the specified distance along a linear geometry
intersection
(other)Returns the intersection of the geometries
intersects
(other)Returns True if geometries intersect, else False
line_interpolate_point
(distance[, normalized])Return a point at the specified distance along a linear geometry
line_locate_point
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
Converts geometry to normal form (or canonical form).
overlaps
(other)Returns True if geometries overlap, else False
Returns a point guaranteed to be within the object, cheaply.
project
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
relate
(other)Returns the DE-9IM intersection matrix for the two geometries (string)
relate_pattern
(other, pattern)Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
Returns a point guaranteed to be within the object, cheaply.
reverse
()Returns a copy of this geometry with the order of coordinates reversed.
segmentize
(tolerance)Adds vertices to line segments based on tolerance.
simplify
(tolerance[, preserve_topology])Returns a simplified geometry produced by the Douglas-Peucker algorithm
svg
([scale_factor, fill_color, opacity])Returns a group of SVG circle elements for the MultiPoint geometry.
symmetric_difference
(other)Returns the symmetric difference of the geometries (Shapely geometry)
touches
(other)Returns True if geometries touch, else False
union
(other)Returns the union of the geometries (Shapely geometry)
within
(other)Returns True if geometry is within the other, else False
geometryType
- __eq__(value, /)#
Return self==value.
- __ge__(value, /)#
Return self>=value.
- property __geo_interface__#
Dictionary representation of the geometry
- __gt__(value, /)#
Return self>value.
- __hash__(/)#
Return hash(self).
- __le__(value, /)#
Return self<=value.
- __lt__(value, /)#
Return self<value.
- __ne__(value, /)#
Return self!=value.
- static __new__(self, points=None)#
- __or__(other)#
Return self|value.
- __reduce__()#
Helper for pickle.
- __repr__()#
Return repr(self).
- __str__()#
Return str(self).
- almost_equals(other, decimal=6)#
True if geometries are equal at all coordinates to a specified decimal place.
Deprecated since version 1.8.0: The ‘almost_equals()’ method is deprecated and will be removed in Shapely 2.0 because the name is confusing. The ‘equals_exact()’ method should be used instead.
Refers to approximate coordinate equality, which requires coordinates to be approximately equal and in the same order for all components of a geometry.
Because of this it is possible for “equals()” to be True for two geometries and “almost_equals()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property area#
Unitless area of the geometry (float)
- property boundary#
Returns a lower dimension geometry that bounds the object
The boundary of a polygon is a line, the boundary of a line is a collection of points. The boundary of a point is an empty (null) collection.
- property bounds#
Returns minimum bounding region (minx, miny, maxx, maxy)
- buffer(distance, resolution=16, quadsegs=None, cap_style=1, join_style=1, mitre_limit=5.0, single_sided=False)#
Get a geometry that represents all points within a distance of this geometry.
A positive distance produces a dilation, a negative distance an erosion. A very small or zero distance may sometimes be used to “tidy” a polygon.
- Parameters
- distancefloat
The distance to buffer around the object.
- resolutionint, optional
The resolution of the buffer around each vertex of the object.
- quadsegsint, optional
Sets the number of line segments used to approximate an angle fillet. Note: the use of a quadsegs parameter is deprecated and will be gone from the next major release.
- cap_styleint, optional
The styles of caps are: CAP_STYLE.round (1), CAP_STYLE.flat (2), and CAP_STYLE.square (3).
- join_styleint, optional
The styles of joins between offset segments are: JOIN_STYLE.round (1), JOIN_STYLE.mitre (2), and JOIN_STYLE.bevel (3).
- mitre_limitfloat, optional
The mitre limit ratio is used for very sharp corners. The mitre ratio is the ratio of the distance from the corner to the end of the mitred offset corner. When two line segments meet at a sharp angle, a miter join will extend the original geometry. To prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. Corners with a ratio which exceed the limit will be beveled.
- single_sidebool, optional
The side used is determined by the sign of the buffer distance:
a positive distance indicates the left-hand side a negative distance indicates the right-hand side
The single-sided buffer of point geometries is the same as the regular buffer. The End Cap Style for single-sided buffers is always ignored, and forced to the equivalent of CAP_FLAT.
- Returns
- Geometry
Notes
The return value is a strictly two-dimensional geometry. All Z coordinates of the original geometry will be ignored.
Examples
>>> from shapely.wkt import loads >>> g = loads('POINT (0.0 0.0)')
16-gon approx of a unit radius circle:
>>> g.buffer(1.0).area 3.1365484905459...
128-gon approximation:
>>> g.buffer(1.0, 128).area 3.141513801144...
triangle approximation:
>>> g.buffer(1.0, 3).area 3.0 >>> list(g.buffer(1.0, cap_style=CAP_STYLE.square).exterior.coords) [(1.0, 1.0), (1.0, -1.0), (-1.0, -1.0), (-1.0, 1.0), (1.0, 1.0)] >>> g.buffer(1.0, cap_style=CAP_STYLE.square).area 4.0
- property centroid#
Returns the geometric center of the object
- contains(other)#
Returns True if the geometry contains the other, else False
- property convex_hull#
Imagine an elastic band stretched around the geometry: that’s a convex hull, more or less
The convex hull of a three member multipoint, for example, is a triangular polygon.
- property coords#
Access to geometry’s coordinates (CoordinateSequence)
- covered_by(other)#
Returns True if the geometry is covered by the other, else False
- covers(other)#
Returns True if the geometry covers the other, else False
- crosses(other)#
Returns True if the geometries cross, else False
- difference(other)#
Returns the difference of the geometries
- disjoint(other)#
Returns True if geometries are disjoint, else False
- distance(other)#
Unitless distance to other geometry (float)
- property envelope#
A figure that envelopes the geometry
- equals(other)#
Returns True if geometries are equal, else False.
This method considers point-set equality (or topological equality), and is equivalent to (self.within(other) & self.contains(other)).
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals( ... LineString([(0, 0), (1, 1), (2, 2)]) ... ) True
- equals_exact(other, tolerance)#
True if geometries are equal to within a specified tolerance.
- Parameters
- otherBaseGeometry
The other geometry object in this comparison.
- tolerancefloat
Absolute tolerance in the same units as coordinates.
- This method considers coordinate equality, which requires
- coordinates to be equal and in the same order for all components
- of a geometry.
- Because of this it is possible for “equals()” to be True for two
- geometries and “equals_exact()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property geom_type#
Name of the geometry’s type, such as ‘Point’
- property has_z#
True if the geometry’s coordinate sequence(s) have z values (are 3-dimensional)
- hausdorff_distance(other)#
Unitless hausdorff distance to other geometry (float)
- interpolate(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of line_interpolate_point.
- intersection(other)#
Returns the intersection of the geometries
- intersects(other)#
Returns True if geometries intersect, else False
- property is_closed#
True if the geometry is closed, else False
Applicable only to 1-D geometries.
- property is_empty#
True if the set of points in this geometry is empty, else False
- property is_ring#
True if the geometry is a closed ring, else False
- property is_simple#
True if the geometry is simple, meaning that any self-intersections are only at boundary points, else False
- property is_valid#
True if the geometry is valid (definition depends on sub-class), else False
- property length#
Unitless length of the geometry (float)
- line_interpolate_point(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of interpolate.
- line_locate_point(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of project.
- property minimum_clearance#
Unitless distance by which a node could be moved to produce an invalid geometry (float)
- property minimum_rotated_rectangle#
Returns the general minimum bounding rectangle of the geometry. Can possibly be rotated. If the convex hull of the object is a degenerate (line or point) this same degenerate is returned.
- normalize()#
Converts geometry to normal form (or canonical form).
This method orders the coordinates, rings of a polygon and parts of multi geometries consistently. Typically useful for testing purposes (for example in combination with equals_exact).
Examples
>>> from shapely import MultiLineString >>> line = MultiLineString([[(0, 0), (1, 1)], [(3, 3), (2, 2)]]) >>> line.normalize() <MULTILINESTRING ((2 2, 3 3), (0 0, 1 1))>
- overlaps(other)#
Returns True if geometries overlap, else False
- point_on_surface()#
Returns a point guaranteed to be within the object, cheaply.
Alias of representative_point.
- project(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of line_locate_point.
- relate(other)#
Returns the DE-9IM intersection matrix for the two geometries (string)
- relate_pattern(other, pattern)#
Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
- representative_point()#
Returns a point guaranteed to be within the object, cheaply.
Alias of point_on_surface.
- reverse()#
Returns a copy of this geometry with the order of coordinates reversed.
If the geometry is a polygon with interior rings, the interior rings are also reversed.
Points are unchanged.
See also
is_ccw
Checks if a geometry is clockwise.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (1, 2)]).reverse() <LINESTRING (1 2, 0 0)> >>> Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]).reverse() <POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))>
- segmentize(tolerance)#
Adds vertices to line segments based on tolerance.
Additional vertices will be added to every line segment in an input geometry so that segments are no greater than tolerance. New vertices will evenly subdivide each segment.
Only linear components of input geometries are densified; other geometries are returned unmodified.
- Parameters
- tolerancefloat or array_like
Additional vertices will be added so that all line segments are no greater than this value. Must be greater than 0.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (0, 10)]).segmentize(tolerance=5) <LINESTRING (0 0, 0 5, 0 10)> >>> Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]).segmentize(tolerance=5) <POLYGON ((0 0, 5 0, 10 0, 10 5, 10 10, 5 10, 0 10, 0 5, 0 0))>
- simplify(tolerance, preserve_topology=True)#
Returns a simplified geometry produced by the Douglas-Peucker algorithm
Coordinates of the simplified geometry will be no more than the tolerance distance from the original. Unless the topology preserving option is used, the algorithm may produce self-intersecting or otherwise invalid geometries.
- svg(scale_factor=1.0, fill_color=None, opacity=None)#
Returns a group of SVG circle elements for the MultiPoint geometry.
- Parameters
- scale_factorfloat
Multiplication factor for the SVG circle diameters. Default is 1.
- fill_colorstr, optional
Hex string for fill color. Default is to use “#66cc99” if geometry is valid, and “#ff3333” if invalid.
- opacityfloat
Float number between 0 and 1 for color opacity. Default value is 0.6
- symmetric_difference(other)#
Returns the symmetric difference of the geometries (Shapely geometry)
- touches(other)#
Returns True if geometries touch, else False
- union(other)#
Returns the union of the geometries (Shapely geometry)
- within(other)#
Returns True if geometry is within the other, else False
- property wkb#
WKB representation of the geometry
- property wkb_hex#
WKB hex representation of the geometry
- property wkt#
WKT representation of the geometry
- property xy#
Separate arrays of X and Y coordinate values
- class MultiPolygon(polygons=None)#
Bases:
shapely.geometry.base.BaseMultipartGeometry
A collection of one or more Polygons.
If component polygons overlap the collection is invalid and some operations on it may fail.
- Parameters
- polygonssequence
A sequence of Polygons, or a sequence of (shell, holes) tuples where shell is the sequence representation of a linear ring (see LinearRing) and holes is a sequence of such linear rings.
Examples
Construct a MultiPolygon from a sequence of coordinate tuples
>>> from shapely import Polygon >>> ob = MultiPolygon([ ... ( ... ((0.0, 0.0), (0.0, 1.0), (1.0, 1.0), (1.0, 0.0)), ... [((0.1,0.1), (0.1,0.2), (0.2,0.2), (0.2,0.1))] ... ) ... ]) >>> len(ob.geoms) 1 >>> type(ob.geoms[0]) == Polygon True
- Attributes
- geomssequence
A sequence of Polygon instances
Methods
almost_equals
(other[, decimal])True if geometries are equal at all coordinates to a specified decimal place.
buffer
(distance[, resolution, quadsegs, ...])Get a geometry that represents all points within a distance of this geometry.
contains
(other)Returns True if the geometry contains the other, else False
covered_by
(other)Returns True if the geometry is covered by the other, else False
covers
(other)Returns True if the geometry covers the other, else False
crosses
(other)Returns True if the geometries cross, else False
difference
(other)Returns the difference of the geometries
disjoint
(other)Returns True if geometries are disjoint, else False
distance
(other)Unitless distance to other geometry (float)
equals
(other)Returns True if geometries are equal, else False.
equals_exact
(other, tolerance)True if geometries are equal to within a specified tolerance.
hausdorff_distance
(other)Unitless hausdorff distance to other geometry (float)
interpolate
(distance[, normalized])Return a point at the specified distance along a linear geometry
intersection
(other)Returns the intersection of the geometries
intersects
(other)Returns True if geometries intersect, else False
line_interpolate_point
(distance[, normalized])Return a point at the specified distance along a linear geometry
line_locate_point
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
Converts geometry to normal form (or canonical form).
overlaps
(other)Returns True if geometries overlap, else False
Returns a point guaranteed to be within the object, cheaply.
project
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
relate
(other)Returns the DE-9IM intersection matrix for the two geometries (string)
relate_pattern
(other, pattern)Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
Returns a point guaranteed to be within the object, cheaply.
reverse
()Returns a copy of this geometry with the order of coordinates reversed.
segmentize
(tolerance)Adds vertices to line segments based on tolerance.
simplify
(tolerance[, preserve_topology])Returns a simplified geometry produced by the Douglas-Peucker algorithm
svg
([scale_factor, fill_color, opacity])Returns group of SVG path elements for the MultiPolygon geometry.
symmetric_difference
(other)Returns the symmetric difference of the geometries (Shapely geometry)
touches
(other)Returns True if geometries touch, else False
union
(other)Returns the union of the geometries (Shapely geometry)
within
(other)Returns True if geometry is within the other, else False
geometryType
- __eq__(value, /)#
Return self==value.
- __ge__(value, /)#
Return self>=value.
- property __geo_interface__#
Dictionary representation of the geometry
- __gt__(value, /)#
Return self>value.
- __hash__(/)#
Return hash(self).
- __le__(value, /)#
Return self<=value.
- __lt__(value, /)#
Return self<value.
- __ne__(value, /)#
Return self!=value.
- static __new__(self, polygons=None)#
- __or__(other)#
Return self|value.
- __reduce__()#
Helper for pickle.
- __repr__()#
Return repr(self).
- __str__()#
Return str(self).
- almost_equals(other, decimal=6)#
True if geometries are equal at all coordinates to a specified decimal place.
Deprecated since version 1.8.0: The ‘almost_equals()’ method is deprecated and will be removed in Shapely 2.0 because the name is confusing. The ‘equals_exact()’ method should be used instead.
Refers to approximate coordinate equality, which requires coordinates to be approximately equal and in the same order for all components of a geometry.
Because of this it is possible for “equals()” to be True for two geometries and “almost_equals()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property area#
Unitless area of the geometry (float)
- property boundary#
Returns a lower dimension geometry that bounds the object
The boundary of a polygon is a line, the boundary of a line is a collection of points. The boundary of a point is an empty (null) collection.
- property bounds#
Returns minimum bounding region (minx, miny, maxx, maxy)
- buffer(distance, resolution=16, quadsegs=None, cap_style=1, join_style=1, mitre_limit=5.0, single_sided=False)#
Get a geometry that represents all points within a distance of this geometry.
A positive distance produces a dilation, a negative distance an erosion. A very small or zero distance may sometimes be used to “tidy” a polygon.
- Parameters
- distancefloat
The distance to buffer around the object.
- resolutionint, optional
The resolution of the buffer around each vertex of the object.
- quadsegsint, optional
Sets the number of line segments used to approximate an angle fillet. Note: the use of a quadsegs parameter is deprecated and will be gone from the next major release.
- cap_styleint, optional
The styles of caps are: CAP_STYLE.round (1), CAP_STYLE.flat (2), and CAP_STYLE.square (3).
- join_styleint, optional
The styles of joins between offset segments are: JOIN_STYLE.round (1), JOIN_STYLE.mitre (2), and JOIN_STYLE.bevel (3).
- mitre_limitfloat, optional
The mitre limit ratio is used for very sharp corners. The mitre ratio is the ratio of the distance from the corner to the end of the mitred offset corner. When two line segments meet at a sharp angle, a miter join will extend the original geometry. To prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. Corners with a ratio which exceed the limit will be beveled.
- single_sidebool, optional
The side used is determined by the sign of the buffer distance:
a positive distance indicates the left-hand side a negative distance indicates the right-hand side
The single-sided buffer of point geometries is the same as the regular buffer. The End Cap Style for single-sided buffers is always ignored, and forced to the equivalent of CAP_FLAT.
- Returns
- Geometry
Notes
The return value is a strictly two-dimensional geometry. All Z coordinates of the original geometry will be ignored.
Examples
>>> from shapely.wkt import loads >>> g = loads('POINT (0.0 0.0)')
16-gon approx of a unit radius circle:
>>> g.buffer(1.0).area 3.1365484905459...
128-gon approximation:
>>> g.buffer(1.0, 128).area 3.141513801144...
triangle approximation:
>>> g.buffer(1.0, 3).area 3.0 >>> list(g.buffer(1.0, cap_style=CAP_STYLE.square).exterior.coords) [(1.0, 1.0), (1.0, -1.0), (-1.0, -1.0), (-1.0, 1.0), (1.0, 1.0)] >>> g.buffer(1.0, cap_style=CAP_STYLE.square).area 4.0
- property centroid#
Returns the geometric center of the object
- contains(other)#
Returns True if the geometry contains the other, else False
- property convex_hull#
Imagine an elastic band stretched around the geometry: that’s a convex hull, more or less
The convex hull of a three member multipoint, for example, is a triangular polygon.
- property coords#
Access to geometry’s coordinates (CoordinateSequence)
- covered_by(other)#
Returns True if the geometry is covered by the other, else False
- covers(other)#
Returns True if the geometry covers the other, else False
- crosses(other)#
Returns True if the geometries cross, else False
- difference(other)#
Returns the difference of the geometries
- disjoint(other)#
Returns True if geometries are disjoint, else False
- distance(other)#
Unitless distance to other geometry (float)
- property envelope#
A figure that envelopes the geometry
- equals(other)#
Returns True if geometries are equal, else False.
This method considers point-set equality (or topological equality), and is equivalent to (self.within(other) & self.contains(other)).
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals( ... LineString([(0, 0), (1, 1), (2, 2)]) ... ) True
- equals_exact(other, tolerance)#
True if geometries are equal to within a specified tolerance.
- Parameters
- otherBaseGeometry
The other geometry object in this comparison.
- tolerancefloat
Absolute tolerance in the same units as coordinates.
- This method considers coordinate equality, which requires
- coordinates to be equal and in the same order for all components
- of a geometry.
- Because of this it is possible for “equals()” to be True for two
- geometries and “equals_exact()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property geom_type#
Name of the geometry’s type, such as ‘Point’
- property has_z#
True if the geometry’s coordinate sequence(s) have z values (are 3-dimensional)
- hausdorff_distance(other)#
Unitless hausdorff distance to other geometry (float)
- interpolate(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of line_interpolate_point.
- intersection(other)#
Returns the intersection of the geometries
- intersects(other)#
Returns True if geometries intersect, else False
- property is_closed#
True if the geometry is closed, else False
Applicable only to 1-D geometries.
- property is_empty#
True if the set of points in this geometry is empty, else False
- property is_ring#
True if the geometry is a closed ring, else False
- property is_simple#
True if the geometry is simple, meaning that any self-intersections are only at boundary points, else False
- property is_valid#
True if the geometry is valid (definition depends on sub-class), else False
- property length#
Unitless length of the geometry (float)
- line_interpolate_point(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of interpolate.
- line_locate_point(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of project.
- property minimum_clearance#
Unitless distance by which a node could be moved to produce an invalid geometry (float)
- property minimum_rotated_rectangle#
Returns the general minimum bounding rectangle of the geometry. Can possibly be rotated. If the convex hull of the object is a degenerate (line or point) this same degenerate is returned.
- normalize()#
Converts geometry to normal form (or canonical form).
This method orders the coordinates, rings of a polygon and parts of multi geometries consistently. Typically useful for testing purposes (for example in combination with equals_exact).
Examples
>>> from shapely import MultiLineString >>> line = MultiLineString([[(0, 0), (1, 1)], [(3, 3), (2, 2)]]) >>> line.normalize() <MULTILINESTRING ((2 2, 3 3), (0 0, 1 1))>
- overlaps(other)#
Returns True if geometries overlap, else False
- point_on_surface()#
Returns a point guaranteed to be within the object, cheaply.
Alias of representative_point.
- project(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of line_locate_point.
- relate(other)#
Returns the DE-9IM intersection matrix for the two geometries (string)
- relate_pattern(other, pattern)#
Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
- representative_point()#
Returns a point guaranteed to be within the object, cheaply.
Alias of point_on_surface.
- reverse()#
Returns a copy of this geometry with the order of coordinates reversed.
If the geometry is a polygon with interior rings, the interior rings are also reversed.
Points are unchanged.
See also
is_ccw
Checks if a geometry is clockwise.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (1, 2)]).reverse() <LINESTRING (1 2, 0 0)> >>> Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]).reverse() <POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))>
- segmentize(tolerance)#
Adds vertices to line segments based on tolerance.
Additional vertices will be added to every line segment in an input geometry so that segments are no greater than tolerance. New vertices will evenly subdivide each segment.
Only linear components of input geometries are densified; other geometries are returned unmodified.
- Parameters
- tolerancefloat or array_like
Additional vertices will be added so that all line segments are no greater than this value. Must be greater than 0.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (0, 10)]).segmentize(tolerance=5) <LINESTRING (0 0, 0 5, 0 10)> >>> Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]).segmentize(tolerance=5) <POLYGON ((0 0, 5 0, 10 0, 10 5, 10 10, 5 10, 0 10, 0 5, 0 0))>
- simplify(tolerance, preserve_topology=True)#
Returns a simplified geometry produced by the Douglas-Peucker algorithm
Coordinates of the simplified geometry will be no more than the tolerance distance from the original. Unless the topology preserving option is used, the algorithm may produce self-intersecting or otherwise invalid geometries.
- svg(scale_factor=1.0, fill_color=None, opacity=None)#
Returns group of SVG path elements for the MultiPolygon geometry.
- Parameters
- scale_factorfloat
Multiplication factor for the SVG stroke-width. Default is 1.
- fill_colorstr, optional
Hex string for fill color. Default is to use “#66cc99” if geometry is valid, and “#ff3333” if invalid.
- opacityfloat
Float number between 0 and 1 for color opacity. Default value is 0.6
- symmetric_difference(other)#
Returns the symmetric difference of the geometries (Shapely geometry)
- touches(other)#
Returns True if geometries touch, else False
- union(other)#
Returns the union of the geometries (Shapely geometry)
- within(other)#
Returns True if geometry is within the other, else False
- property wkb#
WKB representation of the geometry
- property wkb_hex#
WKB hex representation of the geometry
- property wkt#
WKT representation of the geometry
- property xy#
Separate arrays of X and Y coordinate values
- class Point(*args)#
Bases:
shapely.geometry.base.BaseGeometry
A geometry type that represents a single coordinate with x,y and possibly z values.
A point is a zero-dimensional feature and has zero length and zero area.
- Parameters
- argsfloat, or sequence of floats
The coordinates can either be passed as a single parameter, or as individual float values using multiple parameters:
1 parameter: a sequence or array-like of with 2 or 3 values.
2 or 3 parameters (float): x, y, and possibly z.
Examples
Constructing the Point using separate parameters for x and y:
>>> p = Point(1.0, -1.0)
Constructing the Point using a list of x, y coordinates:
>>> p = Point([1.0, -1.0]) >>> print(p) POINT (1 -1) >>> p.y -1.0 >>> p.x 1.0
- Attributes
- x, y, zfloat
Coordinate values
Methods
almost_equals
(other[, decimal])True if geometries are equal at all coordinates to a specified decimal place.
buffer
(distance[, resolution, quadsegs, ...])Get a geometry that represents all points within a distance of this geometry.
contains
(other)Returns True if the geometry contains the other, else False
covered_by
(other)Returns True if the geometry is covered by the other, else False
covers
(other)Returns True if the geometry covers the other, else False
crosses
(other)Returns True if the geometries cross, else False
difference
(other)Returns the difference of the geometries
disjoint
(other)Returns True if geometries are disjoint, else False
distance
(other)Unitless distance to other geometry (float)
equals
(other)Returns True if geometries are equal, else False.
equals_exact
(other, tolerance)True if geometries are equal to within a specified tolerance.
hausdorff_distance
(other)Unitless hausdorff distance to other geometry (float)
interpolate
(distance[, normalized])Return a point at the specified distance along a linear geometry
intersection
(other)Returns the intersection of the geometries
intersects
(other)Returns True if geometries intersect, else False
line_interpolate_point
(distance[, normalized])Return a point at the specified distance along a linear geometry
line_locate_point
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
Converts geometry to normal form (or canonical form).
overlaps
(other)Returns True if geometries overlap, else False
Returns a point guaranteed to be within the object, cheaply.
project
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
relate
(other)Returns the DE-9IM intersection matrix for the two geometries (string)
relate_pattern
(other, pattern)Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
Returns a point guaranteed to be within the object, cheaply.
reverse
()Returns a copy of this geometry with the order of coordinates reversed.
segmentize
(tolerance)Adds vertices to line segments based on tolerance.
simplify
(tolerance[, preserve_topology])Returns a simplified geometry produced by the Douglas-Peucker algorithm
svg
([scale_factor, fill_color, opacity])Returns SVG circle element for the Point geometry.
symmetric_difference
(other)Returns the symmetric difference of the geometries (Shapely geometry)
touches
(other)Returns True if geometries touch, else False
union
(other)Returns the union of the geometries (Shapely geometry)
within
(other)Returns True if geometry is within the other, else False
geometryType
- __eq__(value, /)#
Return self==value.
- __ge__(value, /)#
Return self>=value.
- property __geo_interface__#
Dictionary representation of the geometry
- __gt__(value, /)#
Return self>value.
- __hash__(/)#
Return hash(self).
- __le__(value, /)#
Return self<=value.
- __lt__(value, /)#
Return self<value.
- __ne__(value, /)#
Return self!=value.
- static __new__(self, *args)#
- __or__(other)#
Return self|value.
- __reduce__()#
Helper for pickle.
- __repr__()#
Return repr(self).
- __str__()#
Return str(self).
- almost_equals(other, decimal=6)#
True if geometries are equal at all coordinates to a specified decimal place.
Deprecated since version 1.8.0: The ‘almost_equals()’ method is deprecated and will be removed in Shapely 2.0 because the name is confusing. The ‘equals_exact()’ method should be used instead.
Refers to approximate coordinate equality, which requires coordinates to be approximately equal and in the same order for all components of a geometry.
Because of this it is possible for “equals()” to be True for two geometries and “almost_equals()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property area#
Unitless area of the geometry (float)
- property boundary#
Returns a lower dimension geometry that bounds the object
The boundary of a polygon is a line, the boundary of a line is a collection of points. The boundary of a point is an empty (null) collection.
- property bounds#
Returns minimum bounding region (minx, miny, maxx, maxy)
- buffer(distance, resolution=16, quadsegs=None, cap_style=1, join_style=1, mitre_limit=5.0, single_sided=False)#
Get a geometry that represents all points within a distance of this geometry.
A positive distance produces a dilation, a negative distance an erosion. A very small or zero distance may sometimes be used to “tidy” a polygon.
- Parameters
- distancefloat
The distance to buffer around the object.
- resolutionint, optional
The resolution of the buffer around each vertex of the object.
- quadsegsint, optional
Sets the number of line segments used to approximate an angle fillet. Note: the use of a quadsegs parameter is deprecated and will be gone from the next major release.
- cap_styleint, optional
The styles of caps are: CAP_STYLE.round (1), CAP_STYLE.flat (2), and CAP_STYLE.square (3).
- join_styleint, optional
The styles of joins between offset segments are: JOIN_STYLE.round (1), JOIN_STYLE.mitre (2), and JOIN_STYLE.bevel (3).
- mitre_limitfloat, optional
The mitre limit ratio is used for very sharp corners. The mitre ratio is the ratio of the distance from the corner to the end of the mitred offset corner. When two line segments meet at a sharp angle, a miter join will extend the original geometry. To prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. Corners with a ratio which exceed the limit will be beveled.
- single_sidebool, optional
The side used is determined by the sign of the buffer distance:
a positive distance indicates the left-hand side a negative distance indicates the right-hand side
The single-sided buffer of point geometries is the same as the regular buffer. The End Cap Style for single-sided buffers is always ignored, and forced to the equivalent of CAP_FLAT.
- Returns
- Geometry
Notes
The return value is a strictly two-dimensional geometry. All Z coordinates of the original geometry will be ignored.
Examples
>>> from shapely.wkt import loads >>> g = loads('POINT (0.0 0.0)')
16-gon approx of a unit radius circle:
>>> g.buffer(1.0).area 3.1365484905459...
128-gon approximation:
>>> g.buffer(1.0, 128).area 3.141513801144...
triangle approximation:
>>> g.buffer(1.0, 3).area 3.0 >>> list(g.buffer(1.0, cap_style=CAP_STYLE.square).exterior.coords) [(1.0, 1.0), (1.0, -1.0), (-1.0, -1.0), (-1.0, 1.0), (1.0, 1.0)] >>> g.buffer(1.0, cap_style=CAP_STYLE.square).area 4.0
- property centroid#
Returns the geometric center of the object
- contains(other)#
Returns True if the geometry contains the other, else False
- property convex_hull#
Imagine an elastic band stretched around the geometry: that’s a convex hull, more or less
The convex hull of a three member multipoint, for example, is a triangular polygon.
- property coords#
Access to geometry’s coordinates (CoordinateSequence)
- covered_by(other)#
Returns True if the geometry is covered by the other, else False
- covers(other)#
Returns True if the geometry covers the other, else False
- crosses(other)#
Returns True if the geometries cross, else False
- difference(other)#
Returns the difference of the geometries
- disjoint(other)#
Returns True if geometries are disjoint, else False
- distance(other)#
Unitless distance to other geometry (float)
- property envelope#
A figure that envelopes the geometry
- equals(other)#
Returns True if geometries are equal, else False.
This method considers point-set equality (or topological equality), and is equivalent to (self.within(other) & self.contains(other)).
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals( ... LineString([(0, 0), (1, 1), (2, 2)]) ... ) True
- equals_exact(other, tolerance)#
True if geometries are equal to within a specified tolerance.
- Parameters
- otherBaseGeometry
The other geometry object in this comparison.
- tolerancefloat
Absolute tolerance in the same units as coordinates.
- This method considers coordinate equality, which requires
- coordinates to be equal and in the same order for all components
- of a geometry.
- Because of this it is possible for “equals()” to be True for two
- geometries and “equals_exact()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property geom_type#
Name of the geometry’s type, such as ‘Point’
- property has_z#
True if the geometry’s coordinate sequence(s) have z values (are 3-dimensional)
- hausdorff_distance(other)#
Unitless hausdorff distance to other geometry (float)
- interpolate(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of line_interpolate_point.
- intersection(other)#
Returns the intersection of the geometries
- intersects(other)#
Returns True if geometries intersect, else False
- property is_closed#
True if the geometry is closed, else False
Applicable only to 1-D geometries.
- property is_empty#
True if the set of points in this geometry is empty, else False
- property is_ring#
True if the geometry is a closed ring, else False
- property is_simple#
True if the geometry is simple, meaning that any self-intersections are only at boundary points, else False
- property is_valid#
True if the geometry is valid (definition depends on sub-class), else False
- property length#
Unitless length of the geometry (float)
- line_interpolate_point(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of interpolate.
- line_locate_point(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of project.
- property minimum_clearance#
Unitless distance by which a node could be moved to produce an invalid geometry (float)
- property minimum_rotated_rectangle#
Returns the general minimum bounding rectangle of the geometry. Can possibly be rotated. If the convex hull of the object is a degenerate (line or point) this same degenerate is returned.
- normalize()#
Converts geometry to normal form (or canonical form).
This method orders the coordinates, rings of a polygon and parts of multi geometries consistently. Typically useful for testing purposes (for example in combination with equals_exact).
Examples
>>> from shapely import MultiLineString >>> line = MultiLineString([[(0, 0), (1, 1)], [(3, 3), (2, 2)]]) >>> line.normalize() <MULTILINESTRING ((2 2, 3 3), (0 0, 1 1))>
- overlaps(other)#
Returns True if geometries overlap, else False
- point_on_surface()#
Returns a point guaranteed to be within the object, cheaply.
Alias of representative_point.
- project(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of line_locate_point.
- relate(other)#
Returns the DE-9IM intersection matrix for the two geometries (string)
- relate_pattern(other, pattern)#
Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
- representative_point()#
Returns a point guaranteed to be within the object, cheaply.
Alias of point_on_surface.
- reverse()#
Returns a copy of this geometry with the order of coordinates reversed.
If the geometry is a polygon with interior rings, the interior rings are also reversed.
Points are unchanged.
See also
is_ccw
Checks if a geometry is clockwise.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (1, 2)]).reverse() <LINESTRING (1 2, 0 0)> >>> Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]).reverse() <POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))>
- segmentize(tolerance)#
Adds vertices to line segments based on tolerance.
Additional vertices will be added to every line segment in an input geometry so that segments are no greater than tolerance. New vertices will evenly subdivide each segment.
Only linear components of input geometries are densified; other geometries are returned unmodified.
- Parameters
- tolerancefloat or array_like
Additional vertices will be added so that all line segments are no greater than this value. Must be greater than 0.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (0, 10)]).segmentize(tolerance=5) <LINESTRING (0 0, 0 5, 0 10)> >>> Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]).segmentize(tolerance=5) <POLYGON ((0 0, 5 0, 10 0, 10 5, 10 10, 5 10, 0 10, 0 5, 0 0))>
- simplify(tolerance, preserve_topology=True)#
Returns a simplified geometry produced by the Douglas-Peucker algorithm
Coordinates of the simplified geometry will be no more than the tolerance distance from the original. Unless the topology preserving option is used, the algorithm may produce self-intersecting or otherwise invalid geometries.
- svg(scale_factor=1.0, fill_color=None, opacity=None)#
Returns SVG circle element for the Point geometry.
- Parameters
- scale_factorfloat
Multiplication factor for the SVG circle diameter. Default is 1.
- fill_colorstr, optional
Hex string for fill color. Default is to use “#66cc99” if geometry is valid, and “#ff3333” if invalid.
- opacityfloat
Float number between 0 and 1 for color opacity. Default value is 0.6
- symmetric_difference(other)#
Returns the symmetric difference of the geometries (Shapely geometry)
- touches(other)#
Returns True if geometries touch, else False
- union(other)#
Returns the union of the geometries (Shapely geometry)
- within(other)#
Returns True if geometry is within the other, else False
- property wkb#
WKB representation of the geometry
- property wkb_hex#
WKB hex representation of the geometry
- property wkt#
WKT representation of the geometry
- property x#
Return x coordinate.
- property xy#
Separate arrays of X and Y coordinate values
- Example:
>>> x, y = Point(0, 0).xy >>> list(x) [0.0] >>> list(y) [0.0]
- property y#
Return y coordinate.
- property z#
Return z coordinate.
- class Polygon(shell=None, holes=None)#
Bases:
shapely.geometry.base.BaseGeometry
A geometry type representing an area that is enclosed by a linear ring.
A polygon is a two-dimensional feature and has a non-zero area. It may have one or more negative-space “holes” which are also bounded by linear rings. If any rings cross each other, the feature is invalid and operations on it may fail.
- Parameters
- shellsequence
A sequence of (x, y [,z]) numeric coordinate pairs or triples, or an array-like with shape (N, 2) or (N, 3). Also can be a sequence of Point objects.
- holessequence
A sequence of objects which satisfy the same requirements as the shell parameters above
Examples
Create a square polygon with no holes
>>> coords = ((0., 0.), (0., 1.), (1., 1.), (1., 0.), (0., 0.)) >>> polygon = Polygon(coords) >>> polygon.area 1.0
- Attributes
- exteriorLinearRing
The ring which bounds the positive space of the polygon.
- interiorssequence
A sequence of rings which bound all existing holes.
Methods
almost_equals
(other[, decimal])True if geometries are equal at all coordinates to a specified decimal place.
buffer
(distance[, resolution, quadsegs, ...])Get a geometry that represents all points within a distance of this geometry.
contains
(other)Returns True if the geometry contains the other, else False
covered_by
(other)Returns True if the geometry is covered by the other, else False
covers
(other)Returns True if the geometry covers the other, else False
crosses
(other)Returns True if the geometries cross, else False
difference
(other)Returns the difference of the geometries
disjoint
(other)Returns True if geometries are disjoint, else False
distance
(other)Unitless distance to other geometry (float)
equals
(other)Returns True if geometries are equal, else False.
equals_exact
(other, tolerance)True if geometries are equal to within a specified tolerance.
from_bounds
(xmin, ymin, xmax, ymax)Construct a Polygon() from spatial bounds.
hausdorff_distance
(other)Unitless hausdorff distance to other geometry (float)
interpolate
(distance[, normalized])Return a point at the specified distance along a linear geometry
intersection
(other)Returns the intersection of the geometries
intersects
(other)Returns True if geometries intersect, else False
line_interpolate_point
(distance[, normalized])Return a point at the specified distance along a linear geometry
line_locate_point
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
Converts geometry to normal form (or canonical form).
overlaps
(other)Returns True if geometries overlap, else False
Returns a point guaranteed to be within the object, cheaply.
project
(other[, normalized])Returns the distance along this geometry to a point nearest the specified point
relate
(other)Returns the DE-9IM intersection matrix for the two geometries (string)
relate_pattern
(other, pattern)Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
Returns a point guaranteed to be within the object, cheaply.
reverse
()Returns a copy of this geometry with the order of coordinates reversed.
segmentize
(tolerance)Adds vertices to line segments based on tolerance.
simplify
(tolerance[, preserve_topology])Returns a simplified geometry produced by the Douglas-Peucker algorithm
svg
([scale_factor, fill_color, opacity])Returns SVG path element for the Polygon geometry.
symmetric_difference
(other)Returns the symmetric difference of the geometries (Shapely geometry)
touches
(other)Returns True if geometries touch, else False
union
(other)Returns the union of the geometries (Shapely geometry)
within
(other)Returns True if geometry is within the other, else False
geometryType
- __eq__(value, /)#
Return self==value.
- __ge__(value, /)#
Return self>=value.
- property __geo_interface__#
Dictionary representation of the geometry
- __gt__(value, /)#
Return self>value.
- __hash__(/)#
Return hash(self).
- __le__(value, /)#
Return self<=value.
- __lt__(value, /)#
Return self<value.
- __ne__(value, /)#
Return self!=value.
- static __new__(self, shell=None, holes=None)#
- __or__(other)#
Return self|value.
- __reduce__()#
Helper for pickle.
- __repr__()#
Return repr(self).
- __str__()#
Return str(self).
- almost_equals(other, decimal=6)#
True if geometries are equal at all coordinates to a specified decimal place.
Deprecated since version 1.8.0: The ‘almost_equals()’ method is deprecated and will be removed in Shapely 2.0 because the name is confusing. The ‘equals_exact()’ method should be used instead.
Refers to approximate coordinate equality, which requires coordinates to be approximately equal and in the same order for all components of a geometry.
Because of this it is possible for “equals()” to be True for two geometries and “almost_equals()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- property area#
Unitless area of the geometry (float)
- property boundary#
Returns a lower dimension geometry that bounds the object
The boundary of a polygon is a line, the boundary of a line is a collection of points. The boundary of a point is an empty (null) collection.
- property bounds#
Returns minimum bounding region (minx, miny, maxx, maxy)
- buffer(distance, resolution=16, quadsegs=None, cap_style=1, join_style=1, mitre_limit=5.0, single_sided=False)#
Get a geometry that represents all points within a distance of this geometry.
A positive distance produces a dilation, a negative distance an erosion. A very small or zero distance may sometimes be used to “tidy” a polygon.
- Parameters
- distancefloat
The distance to buffer around the object.
- resolutionint, optional
The resolution of the buffer around each vertex of the object.
- quadsegsint, optional
Sets the number of line segments used to approximate an angle fillet. Note: the use of a quadsegs parameter is deprecated and will be gone from the next major release.
- cap_styleint, optional
The styles of caps are: CAP_STYLE.round (1), CAP_STYLE.flat (2), and CAP_STYLE.square (3).
- join_styleint, optional
The styles of joins between offset segments are: JOIN_STYLE.round (1), JOIN_STYLE.mitre (2), and JOIN_STYLE.bevel (3).
- mitre_limitfloat, optional
The mitre limit ratio is used for very sharp corners. The mitre ratio is the ratio of the distance from the corner to the end of the mitred offset corner. When two line segments meet at a sharp angle, a miter join will extend the original geometry. To prevent unreasonable geometry, the mitre limit allows controlling the maximum length of the join corner. Corners with a ratio which exceed the limit will be beveled.
- single_sidebool, optional
The side used is determined by the sign of the buffer distance:
a positive distance indicates the left-hand side a negative distance indicates the right-hand side
The single-sided buffer of point geometries is the same as the regular buffer. The End Cap Style for single-sided buffers is always ignored, and forced to the equivalent of CAP_FLAT.
- Returns
- Geometry
Notes
The return value is a strictly two-dimensional geometry. All Z coordinates of the original geometry will be ignored.
Examples
>>> from shapely.wkt import loads >>> g = loads('POINT (0.0 0.0)')
16-gon approx of a unit radius circle:
>>> g.buffer(1.0).area 3.1365484905459...
128-gon approximation:
>>> g.buffer(1.0, 128).area 3.141513801144...
triangle approximation:
>>> g.buffer(1.0, 3).area 3.0 >>> list(g.buffer(1.0, cap_style=CAP_STYLE.square).exterior.coords) [(1.0, 1.0), (1.0, -1.0), (-1.0, -1.0), (-1.0, 1.0), (1.0, 1.0)] >>> g.buffer(1.0, cap_style=CAP_STYLE.square).area 4.0
- property centroid#
Returns the geometric center of the object
- contains(other)#
Returns True if the geometry contains the other, else False
- property convex_hull#
Imagine an elastic band stretched around the geometry: that’s a convex hull, more or less
The convex hull of a three member multipoint, for example, is a triangular polygon.
- property coords#
Access to geometry’s coordinates (CoordinateSequence)
- covered_by(other)#
Returns True if the geometry is covered by the other, else False
- covers(other)#
Returns True if the geometry covers the other, else False
- crosses(other)#
Returns True if the geometries cross, else False
- difference(other)#
Returns the difference of the geometries
- disjoint(other)#
Returns True if geometries are disjoint, else False
- distance(other)#
Unitless distance to other geometry (float)
- property envelope#
A figure that envelopes the geometry
- equals(other)#
Returns True if geometries are equal, else False.
This method considers point-set equality (or topological equality), and is equivalent to (self.within(other) & self.contains(other)).
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals( ... LineString([(0, 0), (1, 1), (2, 2)]) ... ) True
- equals_exact(other, tolerance)#
True if geometries are equal to within a specified tolerance.
- Parameters
- otherBaseGeometry
The other geometry object in this comparison.
- tolerancefloat
Absolute tolerance in the same units as coordinates.
- This method considers coordinate equality, which requires
- coordinates to be equal and in the same order for all components
- of a geometry.
- Because of this it is possible for “equals()” to be True for two
- geometries and “equals_exact()” to be False.
- Returns
- bool
Examples
>>> LineString( ... [(0, 0), (2, 2)] ... ).equals_exact( ... LineString([(0, 0), (1, 1), (2, 2)]), ... 1e-6 ... ) False
- classmethod from_bounds(xmin, ymin, xmax, ymax)#
Construct a Polygon() from spatial bounds.
- property geom_type#
Name of the geometry’s type, such as ‘Point’
- property has_z#
True if the geometry’s coordinate sequence(s) have z values (are 3-dimensional)
- hausdorff_distance(other)#
Unitless hausdorff distance to other geometry (float)
- interpolate(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of line_interpolate_point.
- intersection(other)#
Returns the intersection of the geometries
- intersects(other)#
Returns True if geometries intersect, else False
- property is_closed#
True if the geometry is closed, else False
Applicable only to 1-D geometries.
- property is_empty#
True if the set of points in this geometry is empty, else False
- property is_ring#
True if the geometry is a closed ring, else False
- property is_simple#
True if the geometry is simple, meaning that any self-intersections are only at boundary points, else False
- property is_valid#
True if the geometry is valid (definition depends on sub-class), else False
- property length#
Unitless length of the geometry (float)
- line_interpolate_point(distance, normalized=False)#
Return a point at the specified distance along a linear geometry
Negative length values are taken as measured in the reverse direction from the end of the geometry. Out-of-range index values are handled by clamping them to the valid range of values. If the normalized arg is True, the distance will be interpreted as a fraction of the geometry’s length.
Alias of interpolate.
- line_locate_point(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of project.
- property minimum_clearance#
Unitless distance by which a node could be moved to produce an invalid geometry (float)
- property minimum_rotated_rectangle#
Returns the general minimum bounding rectangle of the geometry. Can possibly be rotated. If the convex hull of the object is a degenerate (line or point) this same degenerate is returned.
- normalize()#
Converts geometry to normal form (or canonical form).
This method orders the coordinates, rings of a polygon and parts of multi geometries consistently. Typically useful for testing purposes (for example in combination with equals_exact).
Examples
>>> from shapely import MultiLineString >>> line = MultiLineString([[(0, 0), (1, 1)], [(3, 3), (2, 2)]]) >>> line.normalize() <MULTILINESTRING ((2 2, 3 3), (0 0, 1 1))>
- overlaps(other)#
Returns True if geometries overlap, else False
- point_on_surface()#
Returns a point guaranteed to be within the object, cheaply.
Alias of representative_point.
- project(other, normalized=False)#
Returns the distance along this geometry to a point nearest the specified point
If the normalized arg is True, return the distance normalized to the length of the linear geometry.
Alias of line_locate_point.
- relate(other)#
Returns the DE-9IM intersection matrix for the two geometries (string)
- relate_pattern(other, pattern)#
Returns True if the DE-9IM string code for the relationship between the geometries satisfies the pattern, else False
- representative_point()#
Returns a point guaranteed to be within the object, cheaply.
Alias of point_on_surface.
- reverse()#
Returns a copy of this geometry with the order of coordinates reversed.
If the geometry is a polygon with interior rings, the interior rings are also reversed.
Points are unchanged.
See also
is_ccw
Checks if a geometry is clockwise.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (1, 2)]).reverse() <LINESTRING (1 2, 0 0)> >>> Polygon([(0, 0), (1, 0), (1, 1), (0, 1), (0, 0)]).reverse() <POLYGON ((0 0, 0 1, 1 1, 1 0, 0 0))>
- segmentize(tolerance)#
Adds vertices to line segments based on tolerance.
Additional vertices will be added to every line segment in an input geometry so that segments are no greater than tolerance. New vertices will evenly subdivide each segment.
Only linear components of input geometries are densified; other geometries are returned unmodified.
- Parameters
- tolerancefloat or array_like
Additional vertices will be added so that all line segments are no greater than this value. Must be greater than 0.
Examples
>>> from shapely import LineString, Polygon >>> LineString([(0, 0), (0, 10)]).segmentize(tolerance=5) <LINESTRING (0 0, 0 5, 0 10)> >>> Polygon([(0, 0), (10, 0), (10, 10), (0, 10), (0, 0)]).segmentize(tolerance=5) <POLYGON ((0 0, 5 0, 10 0, 10 5, 10 10, 5 10, 0 10, 0 5, 0 0))>
- simplify(tolerance, preserve_topology=True)#
Returns a simplified geometry produced by the Douglas-Peucker algorithm
Coordinates of the simplified geometry will be no more than the tolerance distance from the original. Unless the topology preserving option is used, the algorithm may produce self-intersecting or otherwise invalid geometries.
- svg(scale_factor=1.0, fill_color=None, opacity=None)#
Returns SVG path element for the Polygon geometry.
- Parameters
- scale_factorfloat
Multiplication factor for the SVG stroke-width. Default is 1.
- fill_colorstr, optional
Hex string for fill color. Default is to use “#66cc99” if geometry is valid, and “#ff3333” if invalid.
- opacityfloat
Float number between 0 and 1 for color opacity. Default value is 0.6
- symmetric_difference(other)#
Returns the symmetric difference of the geometries (Shapely geometry)
- touches(other)#
Returns True if geometries touch, else False
- union(other)#
Returns the union of the geometries (Shapely geometry)
- within(other)#
Returns True if geometry is within the other, else False
- property wkb#
WKB representation of the geometry
- property wkb_hex#
WKB hex representation of the geometry
- property wkt#
WKT representation of the geometry
- property xy#
Separate arrays of X and Y coordinate values
- box(minx, miny, maxx, maxy, ccw=True)#
Returns a rectangular polygon with configurable normal vector
- mapping(ob)#
Returns a GeoJSON-like mapping from a Geometry or any object which implements __geo_interface__
- Parameters
- ob :
An object which implements __geo_interface__.
- Returns
- dict
Examples
>>> pt = Point(0, 0) >>> mapping(pt) {'type': 'Point', 'coordinates': (0.0, 0.0)}
- shape(context)#
Returns a new, independent geometry with coordinates copied from the context. Changes to the original context will not be reflected in the geometry object.
- Parameters
- context :
a GeoJSON-like dict, which provides a “type” member describing the type of the geometry and “coordinates” member providing a list of coordinates, or an object which implements __geo_interface__.
- Returns
- Geometry object
Examples
Create a Point from GeoJSON, and then create a copy using __geo_interface__.
>>> context = {'type': 'Point', 'coordinates': [0, 1]} >>> geom = shape(context) >>> geom.type == 'Point' True >>> geom.wkt 'POINT (0 1)' >>> geom2 = shape(geom) >>> geom == geom2 True