A lightweight implementation of shapes drawn across a geo-temporal plane. Geostructures enables you to quickly draw shapes, convert to/from a variety of other geometric formats, and draw results.
Geostructures is available on PYPI
$ pip install geostructures
Geostructures does not require any of the below dependencies to function, however maintains optional features that use:
- geopandas
- H3
- MGRS
- scipy
- shapely
Geostructures provides a python interface for functionally defining various shapes drawn on a map. Unlike other libraries such as Shapely, these shapes retain their mathematical definitions rather than being simplified into N-sided polygons.
The shapes currently supported are:
- Boxes
- Circles
- Ellipses
- LineStrings
- Points
- Polygons
- Rings/Wedges
All shapes may optionally be temporally-bound using a specific datetime or a datetime interval.
Additionally, geostructures provides convenience objects for representing chronologically-ordered (Track
) and unordered (FeatureCollection
) collections of the above shapes.
For an interactive introduction, please review our collection of Jupyter notebooks.
from geostructures import *
box = GeoBox(
Coordinate(-0.154092, 51.539865), # Northwest corner
Coordinate(-0.140592, 51.505665), # Southeast corner
properties={"name": "box"}
)
circle = GeoCircle(
Coordinate(-0.131092, 51.509865), # centerpoint
radius=500,
properties={"name": "circle"}
)
ellipse = GeoEllipse(
Coordinate(-0.093092, 51.529865), # centerpoint
major_axis=1_000, # The distance between the centerpoint and the furthest point along the circumference
minor_axis=250, # The distance between the centerpoint and the closest point along the circumference
rotation=45, # The angle of rotation (between 0 and 360)
properties={"name": "ellipse"}
)
ring = GeoRing(
Coordinate(-0.116092, 51.519865), # centerpoint
inner_radius=800,
outer_radius=1000,
properties={"name": "ring"}
)
# Same as a ring, but with a min/max angle
wedge = GeoRing(
Coordinate(-0.101092, 51.514865), # centerpoint
inner_radius=300,
outer_radius=500,
angle_min=60, # The minimum angle of the wedge
angle_max=190, # The maximum angle of the wedge
properties={"name": "wedge"}
)
linestring = GeoLineString(
[
Coordinate(-0.123092, 51.515865), Coordinate(-0.118092, 51.514665), Coordinate(-0.116092, 51.514865),
Coordinate(-0.116092, 51.518865), Coordinate(-0.108092, 51.512865)
],
properties={"name": "linestring"}
)
point = GeoPoint(
Coordinate(-0.116092, 51.519865),
properties={"name": "point"}
)
polygon = GeoPolygon(
[
Coordinate(-0.116092, 51.509865), Coordinate(-0.111092, 51.509865),
Coordinate(-0.113092, 51.506865), Coordinate(-0.116092, 51.509865) # Note that the last coordinate is the same as the first
],
properties={"name": "polygon"}
)
from geostructures import *
from geostructures.collections import FeatureCollection
polygon = GeoPolygon(
[
Coordinate(-0.116092, 51.509865), Coordinate(-0.111092, 51.509865),
Coordinate(-0.113092, 51.506865), Coordinate(-0.116092, 51.509865)
]
)
# Convert to and from a variety of formats
polygon.to_geojson()
polygon.from_geojson( { a geojson object } )
polygon.to_wkt()
polygon.from_wkt( '<a wkt polygon string>' )
polygon.to_shapely()
polygon.from_shapely( a shapely polygon )
# Collections of shapes have additional supported formats
collection = FeatureCollection([polygon])
# Creates a geopandas DataFrame
collection.to_geopandas()
collection.from_geopandas( a geopandas DataFrame )
# Creates a GeoJSON FeatureCollection
collection.to_geojson()
collection.from_geojson( { a geojson object } )
# Write a FeatureCollection to an ESRI Shapefile
from zipfile import ZipFile
with ZipFile('shapefile_name.zip', 'w') as zfile:
collection.to_shapefile(zfile)
collection.from_shapefile('shapefile_name.zip')
from geostructures import *
from geostructures.collections import FeatureCollection
from geostructures.visualization.plotly import draw_collection
box = GeoBox(Coordinate(-0.154092, 51.539865), Coordinate(-0.140592, 51.505665))
circle = GeoCircle(Coordinate(-0.131092, 51.509865), radius=500)
collection = FeatureCollection([box, circle])
# Display the results
fig = draw_collection(collection)
fig
from datetime import datetime
from geostructures import *
from geostructures.collections import Track
from geostructures.time import TimeInterval
track = Track([
# Bound shapes to a specific point in time
GeoPoint(Coordinate(-0.154092, 51.539865), dt=datetime(2020, 5, 1, 12)),
GeoPoint(Coordinate(-0.155092, 51.540865), dt=datetime(2020, 5, 1, 13)),
# Or bound them to a span of time
GeoPoint(
Coordinate(-0.156092, 51.541865),
dt=TimeInterval(
datetime(2020, 5, 1, 14),
datetime(2020, 5, 1, 15)
)
),
])
# Slice by datetime
subset = track[datetime(2020, 5, 1, 12):datetime(2020, 5, 1, 13)]
# Get efficient metrics between shapes
track.centroid_distances # meters
track.speed_diffs # meters per second
track.time_start_diffs # timedeltas
Geostructures supports geohashing using both Uber's H3 and the original Niemeyer geohashing algorithm.
from geostructures import *
from geostructures.collections import FeatureCollection
from geostructures.geohash import H3Hasher, NiemeyerHasher
from geostructures.visualization.plotly import h3_choropleth
box = GeoBox(Coordinate(-0.154092, 51.539865), Coordinate(-0.140592, 51.505665))
circle = GeoCircle(Coordinate(-0.131092, 51.509865), radius=500)
collection = FeatureCollection([box, circle])
# Create a hasher
hasher = H3Hasher(resolution=10)
hashmap = hasher.hash_collection(collection)
# Display the results
h3_choropleth(hashmap)
# Alternatively, hash using the Niemeyer algorithm
hasher = NiemeyerHasher(length=8, base=16)
hashmap = hasher.hash_collection(collection)
This library assumes that all geospatial terms and structures conform to the WGS84 standard (CRS 4326).
The Geostructures team uses Github issues to track development goals. Please include as much detail as possible so we can effectively triage your request.
We welcome all contributors! Please review CONTRIBUTING.md for more information.
Carl Best (Sr. Data Scientist/Project Owner)
https://github.com/ccbest/
Eli Talbert (Sr. Data Scientist/PhD)
https://github.com/etalbert102
Jessica Moore (Sr. Data Scientist)
https://github.com/jessica-writes-code
Richard Marshall (Data Scientist/SME)
https://github.com/RichardMarshall13