A basic implementation of the __geo_interface__
Project description
Introduction
PyGeoIf provides a GeoJSON-like protocol for geo-spatial (GIS) vector data.
Other Python programs and packages that you may have heard of already implement this protocol:
When you want to write your own geospatial library with support for this protocol you may use pygeoif as a starting point and build your functionality on top of it. It has no requirements outside the Python standard library and is therefore easy to integrate into your project. It is tested on CPython and PyPy, but it should work on alternative Python implementations (that implement the language specification >=3.8) as well.
You may think of pygeoif as a ‘shapely ultralight’ which lets you construct geometries and perform very basic operations like reading and writing geometries from/to WKT, constructing line strings out of points, polygons from linear rings, multi polygons from polygons, etc. It was inspired by shapely and implements the geometries in a way that when you are familiar with pygeoif, you will feel right at home with shapely or the other way round.
It was written to provide clean and python only geometries for fastkml
Example
>>> from pygeoif import geometry
>>> p = geometry.Point(1,1)
>>> p.__geo_interface__
{'type': 'Point', 'bbox': (1, 1, 1, 1), 'coordinates': (1, 1)}
>>> print(p)
POINT (1 1)
>>> p
Point(1, 1)
>>> l = geometry.LineString([(0.0, 0.0), (1.0, 1.0)])
>>> l.bounds
(0.0, 0.0, 1.0, 1.0)
>>> print(l)
LINESTRING (0.0 0.0, 1.0 1.0)
You find more examples in the tests directory which cover every aspect of pygeoif or in fastkml.
Classes
All classes implement the attribute:
__geo_interface__: as discussed above, an interface to GeoJSON.
All geometry classes implement the attributes:
geom_type: Returns a string specifying the Geometry Type of the object
bounds: Returns a (minx, miny, maxx, maxy) tuple that bounds the object.
wkt: Returns the ‘Well Known Text’ representation of the object
For two-dimensional geometries the following methods are implemented:
convex_hull: Returns a representation of the smallest convex Polygon containing all the points in the object unless the number of points in the object is less than three. For two points, the convex hull collapses to a LineString; for 1, a Point. For three dimensional objects only their projection in the xy plane is taken into consideration. Empty objects without coordinates return None for the convex_hull.
Point
A zero dimensional geometry
A point has zero length and zero area. A point cannot be empty.
Attributes
- x, y, zfloat
Coordinate values
Example
>>> from pygeoif import Point >>> p = Point(1.0, -1.0) >>> print(p) POINT (1.0 -1.0) >>> p.y -1.0 >>> p.x 1.0
LineString
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
LinearRing
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 LinearRing is self closing.
Polygon
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.
- maybe_valid: boolean
When a polygon has obvious problems such as self crossing lines or holes that are outside the exterior bounds this will return False. Even if this returns True the geometry may still be invalid, but if this returns False you do have a problem.
MultiPoint
A collection of one or more points.
Attributes
- geomssequence
A sequence of Points.
MultiLineString
A collection of one or more line strings.
A MultiLineString has non-zero length and zero area.
Attributes
- geomssequence
A sequence of LineStrings
MultiPolygon
A collection of one or more polygons.
Attributes
- geomssequence
A sequence of Polygon instances
GeometryCollection
A heterogenous collection of geometries (Points, LineStrings, LinearRings and Polygons).
Attributes
- geomssequence
A sequence of geometry instances
Please note: GEOMETRYCOLLECTION isn’t supported by the Shapefile or GeoJSON 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
>>> 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) >>> [geom for geom in geoms] [Point(1.0, -1.0), Point(1.0, -1.0)]
Feature
Aggregates a geometry instance with associated user-defined properties.
Attributes
- geometryobject
A geometry instance
- propertiesdict
A dictionary linking field keys with values associated with with geometry instance
Example
>>> from pygeoif import Point, Feature
>>> 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'
FeatureCollection
A heterogenous collection of Features
Attributes
- features: sequence
A sequence of feature instances
Example
>>> from pygeoif import Point, Feature, FeatureCollection
>>> p = Point(1.0, -1.0)
>>> props = {'Name': 'Sample Point', 'Other': 'Other Data'}
>>> a = Feature(p, props)
>>> p2 = Point(1.0, -1.0)
>>> props2 = {'Name': 'Sample Point2', 'Other': 'Other Data2'}
>>> b = Feature(p2, props2)
>>> features = [a, b]
>>> c = FeatureCollection(features)
>>> [feature for feature in c]
[Feature(Point(1.0, -1.0), {'Name': 'Sample Point', 'Other': 'Other Data'},...]
Functions
shape
Create a pygeoif feature from an object that provides the __geo_interface__ or any GeoJSON compatible dictionary.
>>> from shapely.geometry import Point >>> from pygeoif import geometry, shape >>> shape(Point(0,0)) Point(0.0, 0.0)
from_wkt
Create a geometry from its WKT representation
>>> from pygeoif import from_wkt
>>> p = from_wkt('POINT (0 1)')
>>> print(p)
POINT (0.0 1.0)
signed_area
Return the signed area enclosed by a ring using the linear time algorithm at http://www.cgafaq.info/wiki/Polygon_Area. A value >= 0 indicates a counter-clockwise oriented ring.
orient
Returns a copy of 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.
box
Return a rectangular polygon with configurable normal vector.
mapping
Return the __geo_interface__ dictionary.
Development
Installation
You can install PyGeoIf from pypi using pip:
pip install pygeoif
Testing
Install the requirements with pip install -r test-requirements.txt and run the unit and static tests with:
pytest pygeoif pytest --doctest-glob="README.rst" yesqa pygeoif/*.py black pygeoif flake8 pygeoif mypy pygeoif
pre-commit
Install the pre-commit hook with:
pip install pre-commit pre-commit install
and check the code with:
pre-commit run --all-files
Acknowledgments
The tests were improved with mutmut which discovered some nasty edge cases.
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file pygeoif-1.1.1.tar.gz.
File metadata
- Download URL: pygeoif-1.1.1.tar.gz
- Upload date:
- Size: 35.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.9.18
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 5b3cc057adde1a0bf50a3dcb5b160172261861a4f4bdde6ee6eb663773c4fe33 |
|
| MD5 | d3ab55e376d4521b361a51ad577a6dd0 |
|
| BLAKE2b-256 | 15fa7f7dc736b741c33f57c9132f02e7de33df595079eb442508c25b1693a5d2 |
File details
Details for the file pygeoif-1.1.1-py3-none-any.whl.
File metadata
- Download URL: pygeoif-1.1.1-py3-none-any.whl
- Upload date:
- Size: 23.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/4.0.2 CPython/3.9.18
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | c98dd9db1022c9002950d128a37b53bb17d972239f92871687e28958c4c088b0 |
|
| MD5 | 0c8a49009b98ce438c1f3f6bc0c31779 |
|
| BLAKE2b-256 | fc9606c30ee09609e0cb14379ed8fe843d6592625a4de398755a1acffa38bfb4 |
