pygeoif

Module contents

Submodules

pygeoif.geometry module

Geometries in pure Python.

class pygeoif.geometry.GeometryCollection(geometries: Iterable[Point | LineString | LinearRing | Polygon | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection])

Bases: _MultiGeometry

A heterogenous collection of geometries.

Attributes:

geomssequence

A sequence of geometry instances

Please note: GEOMETRYCOLLECTION isn’t supported by the Shapefile format. And this sub- class isn’t generally supported by ordinary GIS sw (viewers and so on). So it’s very rarely used in the real GIS professional world.

Example:

Initialize Geometries and construct a GeometryCollection

>>> from pygeoif import geometry
>>> p = geometry.Point(1.0, -1.0)
>>> p2 = geometry.Point(1.0, -1.0)
>>> geoms = [p, p2]
>>> c = geometry.GeometryCollection(geoms)
>>> c.__geo_interface__
{'type': 'GeometryCollection',
'geometries': [{'type': 'Point', 'coordinates': (1.0, -1.0)},
{'type': 'Point', 'coordinates': (1.0, -1.0)}]}

class pygeoif.geometry.LineString(coordinates: Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]])

Bases: _Geometry

A one-dimensional figure comprising one or more line segments.

A LineString has non-zero length and zero area. It may approximate a curve and need not be straight. Unlike a LinearRing, a LineString is not closed.

Attributes

geomssequence

A sequence of Points

property geoms: Tuple[Point, ...]

Return the underlying geometries.

property coords: Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]

Return the geometry coordinates.

property is_empty: bool

Return if this geometry is empty.

A Linestring is considered empty when it has no points.

property has_z: bool | None

Return True if the geometry’s coordinate sequence(s) have z values.

classmethod from_coordinates(coordinates: Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]) → LineString

Construct a linestring from coordinates.

classmethod from_points(*args: Point) → LineString

Create a linestring from points.

class pygeoif.geometry.LinearRing(coordinates: Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]])

Bases: LineString

A closed one-dimensional geometry comprising one or more line segments.

A LinearRing that crosses itself or touches itself at a single point is invalid and operations on it may fail.

A Linear Ring is self closing

property centroid: Point | None

Return the centroid of the ring.

property is_ccw: bool

Return True if the ring is oriented counter clock-wise.

class pygeoif.geometry.MultiLineString(lines: Sequence[Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]], unique: bool = False)

Bases: _MultiGeometry

A collection of one or more line strings.

A MultiLineString has non-zero length and zero area.

Attributes

geomssequence

A sequence of LineStrings

property geoms: Iterator[LineString]

Iterate over the points.

classmethod from_linestrings(*args: LineString, unique: bool = False) → MultiLineString

Create a MultiLineString from LineStrings.

class pygeoif.geometry.MultiPoint(points: Sequence[Tuple[float, float] | Tuple[float, float, float]], unique: bool = False)

Bases: _MultiGeometry

A collection of one or more points.

Attributes

geomssequence

A sequence of Points

property geoms: Iterator[Point]

Iterate over the points.

classmethod from_points(*args: Point, unique: bool = False) → MultiPoint

Create a MultiPoint from Points.

class pygeoif.geometry.MultiPolygon(polygons: Sequence[Tuple[Sequence[Tuple[float, float]], Sequence[Sequence[Tuple[float, float]]]] | Tuple[Sequence[Tuple[float, float]]] | Tuple[Sequence[Tuple[float, float, float]], Sequence[Sequence[Tuple[float, float, float]]]] | Tuple[Sequence[Tuple[float, float, float]]]], unique: bool = False)

Bases: _MultiGeometry

A collection of one or more polygons.

If component polygons overlap the collection is invalid and some operations on it may fail.

Attributes

geomssequence

A sequence of Polygon instances

property geoms: Iterator[Polygon]

Iterate over the points.

classmethod from_polygons(*args: Polygon, unique: bool = False) → MultiPolygon

Create a MultiPolygon from Polygons.

class pygeoif.geometry.Point(x: float, y: float, z: float | None = None)

Bases: _Geometry

A zero dimensional geometry.

A point has zero length and zero area.

Attributes:

x, y, zfloat

Coordinate values

Example:

>>> p = Point(1.0, -1.0)
>>> print p
POINT (1.0 -1.0)
>>> p.y
-1.0
>>> p.x
1.0

property is_empty: bool

Return if this geometry is empty.

A Point is considered empty when it has no valid coordinates.

property x: float

Return x coordinate.

property y: float

Return y coordinate.

property z: float | None

Return z coordinate.

property coords: Tuple[Tuple[float, float] | Tuple[float, float, float]] | Tuple

Return the geometry coordinates.

property has_z: bool

Return True if the geometry’s coordinate sequence(s) have z values.

classmethod from_coordinates(coordinates: Sequence[Tuple[float, float] | Tuple[float, float, float]]) → Point

Construct a point from coordinates.

class pygeoif.geometry.Polygon(shell: Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]], holes: Sequence[Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]] | None = None)

Bases: _Geometry

A two-dimensional figure bounded by a linear ring.

A polygon 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 geometry is invalid and operations on it may fail.

Attributes

exteriorLinearRing

The ring which bounds the positive space of the polygon.

interiorssequence

A sequence of rings which bound all existing holes.

property exterior: LinearRing

Return the exterior Linear Ring of the polygon.

property interiors: Iterator[LinearRing]

Interiors (Holes) of the polygon.

property is_empty: bool

Return if this geometry is empty.

A polygon is empty when it does not have an exterior.

property coords: Tuple[Sequence[Tuple[float, float]], Sequence[Sequence[Tuple[float, float]]]] | Tuple[Sequence[Tuple[float, float]]] | Tuple[Sequence[Tuple[float, float, float]], Sequence[Sequence[Tuple[float, float, float]]]] | Tuple[Sequence[Tuple[float, float, float]]]

Return Coordinates of the Polygon.

Note that this is not implemented in Shapely.

property has_z: bool | None

Return True if the geometry’s coordinate sequence(s) have z values.

classmethod from_coordinates(coordinates: Tuple[Sequence[Tuple[float, float]], Sequence[Sequence[Tuple[float, float]]]] | Tuple[Sequence[Tuple[float, float]]] | Tuple[Sequence[Tuple[float, float, float]], Sequence[Sequence[Tuple[float, float, float]]]] | Tuple[Sequence[Tuple[float, float, float]]]) → Polygon

Construct a linestring from coordinates.

classmethod from_linear_rings(shell: LinearRing, *args: LinearRing) → Polygon

Construct a Polygon from linear rings.

pygeoif.feature module

Features.

class pygeoif.feature.Feature(geometry: Point | LineString | LinearRing | Polygon | MultiPoint | MultiLineString | MultiPolygon, properties: Dict[str, Any] | None = None, feature_id: str | int | None = None)

Bases: object

Aggregates a geometry instance with associated user-defined properties.

Attributes:

geometryobject

A geometry instance

propertiesdict

A dictionary linking field keys with values associated with geometry instance

Example:

>>> p = Point(1.0, -1.0)
>>> props = {'Name': 'Sample Point', 'Other': 'Other Data'}
>>> a = Feature(p, props)
>>> a.properties
{'Name': 'Sample Point', 'Other': 'Other Data'}
 >>> a.properties['Name']
'Sample Point'

property id: str | int | None

Return the id of the feature.

property geometry: Point | LineString | LinearRing | Polygon | MultiPoint | MultiLineString | MultiPolygon

Return the geometry of the feature.

property properties: Dict[str, Any]

Return a dictionary of properties.

class pygeoif.feature.FeatureCollection(features: Sequence[Feature])

Bases: object

A heterogenous collection of Features.

Attributes:

featuressequence

A sequence of feature instances

Example:

>>> from pygeoif import geometry
>>> p = geometry.Point(1.0, -1.0)
>>> props = {'Name': 'Sample Point', 'Other': 'Other Data'}
>>> a = geometry.Feature(p, props)
>>> p2 = geometry.Point(1.0, -1.0)
>>> props2 = {'Name': 'Sample Point2', 'Other': 'Other Data2'}
>>> b = geometry.Feature(p2, props2)
>>> features = [a, b]
>>> c = geometry.FeatureCollection(features)
>>> c.__geo_interface__
{'type': 'FeatureCollection',
 'features': [{'geometry': {'type': 'Point', 'coordinates': (1.0, -1.0)},
 'type': 'Feature',
 'properties': {'Other': 'Other Data', 'Name': 'Sample Point'}},
{'geometry': {'type': 'Point', 'coordinates': (1.0, -1.0)},
 'type': 'Feature',
 'properties': {'Other': 'Other Data2', 'Name': 'Sample Point2'}}]}

property features: Generator[Feature, None, None]

Iterate over the features of the collection.

property bounds: Tuple[float, float, float, float]

Return the X-Y bounding box.

pygeoif.factories module

Geometry Factories.

pygeoif.factories.force_2d(context: GeoType | GeoCollectionType) → Point | LineString | LinearRing | Polygon | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection

Force the dimensionality of a geometry to 2D.

>>> force_2d(Point(0, 0, 1))
Point(0, 0)
>>> force_2d(Point(0, 0))
Point(0, 0)
>>> force_2d(LineString([(0, 0, 0), (0, 1, 1), (1, 1, 2)]))
LineString(((0, 0), (0, 1), (1, 1)))

pygeoif.factories.force_3d(context: GeoType | GeoCollectionType, z: float = 0) → Point | LineString | LinearRing | Polygon | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection

Force the dimensionality of a geometry to 3D.

>>> force_3d(Point(0, 0))
Point(0, 0, 0)
>>> force_3d(Point(0, 0), 1)
Point(0, 0, 1)
>>> force_3d(Point(0, 0, 0))
Point(0, 0, 0)
>>> force_3d(LineString([(0, 0), (0, 1), (1, 1)]))
LineString(((0, 0, 0), (0, 1, 0), (1, 1, 0)))

pygeoif.factories.box(minx: float, miny: float, maxx: float, maxy: float, ccw: bool = True) → Polygon

Return a rectangular polygon with configurable normal vector.

pygeoif.factories.from_wkt(geo_str: str) → Point | LineString | LinearRing | Polygon | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection | None

Create a geometry from its WKT representation.

pygeoif.factories.mapping(ob: GeoType | GeoCollectionType) → GeoCollectionInterface | GeoInterface

Return a GeoJSON-like mapping.

Parameters

ob :

An object which implements __geo_interface__.

Returns

dict Example ——- >>> pt = Point(0, 0) >>> mapping(pt) {‘type’: ‘Point’, ‘bbox’: (0, 0, 0, 0), ‘coordinates’: (0, 0)}

pygeoif.factories.orient(polygon: Polygon, ccw: bool = True) → Polygon

Return a polygon with exteriors and interiors in the right orientation.

if ccw is True than the exterior will be in counterclockwise orientation and the interiors will be in clockwise orientation, or the other way round when ccw is False.

pygeoif.factories.shape(context: GeoType | GeoCollectionType | GeoInterface | GeoCollectionInterface) → Point | LineString | LinearRing | Polygon | MultiPoint | MultiLineString | MultiPolygon | GeometryCollection

Return a new 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 Example ——- Create a Point from GeoJSON, and then create a copy using __geo_interface__. >>> context = {‘type’: ‘Point’, ‘coordinates’: [0, 1]} >>> geom = shape(context) >>> geom.geom_type == ‘Point’ True >>> geom.wkt ‘POINT (0 1)’ >>> geom2 = shape(geom) >>> geom == geom2 True

pygeoif.functions module

Functions for geometries.

pygeoif.functions.centroid(coords: Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]) → Tuple[Tuple[float, float], float]

Calculate the coordinates of the centroid and the area of a LineString.

pygeoif.functions.compare_coordinates(coords: float | Tuple[float, float] | Tuple[float, float, float] | Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]] | Sequence[Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]] | Sequence[Tuple[float, float] | Tuple[float, float, float] | Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]] | Sequence[Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]]], other: float | Tuple[float, float] | Tuple[float, float, float] | Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]] | Sequence[Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]] | Sequence[Tuple[float, float] | Tuple[float, float, float] | Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]] | Sequence[Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]]]) → bool

Compare two coordinate sequences.

pygeoif.functions.compare_geo_interface(first: GeoInterface | GeoCollectionInterface, second: GeoInterface | GeoCollectionInterface) → bool

Compare two geo interfaces.

pygeoif.functions.convex_hull(points: Iterable[Tuple[float, float]]) → Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]

Return the convex hull of a set of points using Andrew’s monotone chain algorithm.

Args:

points (Iterable[Point2D]): A collection of 2D points.

Returns:

LineType: The convex hull, represented as a list of points.

pygeoif.functions.dedupe(coords: Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]) → Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]

Remove duplicate Points from a LineString.

pygeoif.functions.move_coordinate(coordinate: Tuple[float, float] | Tuple[float, float, float], move_by: Tuple[float, float] | Tuple[float, float, float]) → Tuple[float, float] | Tuple[float, float, float]

Move the coordinate by the given vector.

This forcefully changes the dimensions of the coordinate to match the latter. >>> move_coordinate((0, 0), (-1, 1)) (-1, 1) >>> move_coordinate((0, 0, 0), (-1, 1)) (-1, 1) >>> move_coordinate((0, 0), (-1, 1, 0)) (-1, 1, 0)

pygeoif.functions.move_coordinates(coordinates: Tuple[float, float] | Tuple[float, float, float] | Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]] | Sequence[Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]], move_by: Tuple[float, float] | Tuple[float, float, float]) → Tuple[float, float] | Tuple[float, float, float] | Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]] | Sequence[Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]]

Move the coordinates recursively by the given vector.

This forcefully changes the dimension of each of the coordinate to match the dimensionality of the vector. >>> move_coordinates(((0, 0), (-1, 1)), (-1, 1)) ((-1, 1), (-2, 2)) >>> move_coordinates(((0, 0, 0), (-1, 1, 0)), (-1, 1)) ((-1, 1), (-2, 2)) >>> move_coordinates(((0, 0), (-1, 1)), (-1, 1, 0)) ((-1, 1, 0), (-2, 2, 0))

pygeoif.functions.signed_area(coords: Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]) → float

Return the signed area enclosed by a ring.

Linear time algorithm: http://www.cgafaq.info/wiki/Polygon_Area. A value >= 0 indicates a counter-clockwise oriented ring.

pygeoif.exceptions module

Exceptions for pygeoif.

exception pygeoif.exceptions.DimensionError

Bases: ValueError

Geometries must have 2 or 3 dimensions.

exception pygeoif.exceptions.InvalidGeometryError

Bases: ValueError

Geometry is not valid.

exception pygeoif.exceptions.WKTParserError

Bases: AttributeError

WKT not supported or cannot be parsed.

pygeoif.types module

Types for geometries.

class pygeoif.types.GeoCollectionInterface

Bases: TypedDict

Geometry Collection Interface.

type: Literal['GeometryCollection']

geometries: Sequence[GeoInterface | GeoCollectionInterface]

bbox: Tuple[float, float, float, float]

class pygeoif.types.GeoCollectionType(*args, **kwargs)

Bases: Protocol

Any compatible type that implements the __geo_interface__.

class pygeoif.types.GeoFeatureCollectionInterface

Bases: TypedDict

Bbox and id are optional keys for the GeoFeatureCollectionInterface.

type: Literal['FeatureCollection']

features: Sequence[GeoFeatureInterface]

bbox: Tuple[float, float, float, float]

id: str | int

class pygeoif.types.GeoFeatureInterface

Bases: TypedDict

The GeoFeatureInterface has optional keys.

type: Literal['Feature']

bbox: Tuple[float, float, float, float]

properties: Dict[str, Any]

id: str | int

geometry: GeoInterface

class pygeoif.types.GeoInterface

Bases: TypedDict

Required keys for the GeoInterface.

type: Literal['Point', 'LineString', 'LinearRing', 'Polygon', 'MultiPoint', 'MultiLineString', 'MultiPolygon']

coordinates: Tuple[float, float] | Tuple[float, float, float] | Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]] | Sequence[Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]] | Sequence[Tuple[float, float] | Tuple[float, float, float] | Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]] | Sequence[Sequence[Tuple[float, float]] | Sequence[Tuple[float, float, float]]]]

bbox: Tuple[float, float, float, float]

class pygeoif.types.GeoType(*args, **kwargs)

Bases: Protocol

Any compatible type that implements the __geo_interface__.

pygeoif.about module

About pygeoif.

The only purpose of this module is to provide a version number for the package.

pygeoif.hypothesis.strategies module