https://github.com/martibosch/pyregeon
Reusable Python utilities to work with geospatial regions.
https://github.com/martibosch/pyregeon
geopandas geospatial osmnx python
Last synced: 6 months ago
JSON representation
Reusable Python utilities to work with geospatial regions.
- Host: GitHub
- URL: https://github.com/martibosch/pyregeon
- Owner: martibosch
- License: gpl-3.0
- Created: 2025-04-03T09:10:43.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-04-03T10:20:25.000Z (6 months ago)
- Last Synced: 2025-04-03T10:25:30.835Z (6 months ago)
- Topics: geopandas, geospatial, osmnx, python
- Language: Python
- Homepage: https://pyregeon.readthedocs.io/en/latest/?badge=latest
- Size: 24.4 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://pypi.python.org/pypi/pyregeon/)
[](https://pyregeon.readthedocs.io/en/latest/?badge=latest)
[](https://github.com/martibosch/pyregeon/blob/main/.github/workflows/tests.yml)
[](https://results.pre-commit.ci/latest/github/martibosch/pyregeon/main)
[](https://codecov.io/gh/martibosch/pyregeon)
[](https://github.com/martibosch/pyregeon/blob/main/LICENSE)
# pyregeon
Reusable Python utilities to work with geospatial regions.
> *pyregeon* stands for Python Region Geospatial utilities
## Usage
The main idea of pyregeon is to make it as easy as possible to associate any Python object to a geospatial region. The first approach is with the object-oriented `RegionMixin`. We can set the `region` [property attribute](https://docs.python.org/3/library/functions.html#property) to any object that inherits from `RegionMixin`, e.g.:
```python
from pyregeon import RegionMixin
class MyAnalysisCase(..., RegionMixin):
# optionally define a `crs` or `CRS` attribute
pass
analysis = MyAnalysisCase(...)
analysis.region = "Lausanne, Switzerland"
```
The `region` [property setter](https://docs.python.org/3/library/functions.html#property.setter) accepts the following values:
- A string with a place name (Nominatim query) to geocode (requires [osmnx](https://github.com/gboeing/osmnx)).
- A sequence with the west, south, east and north bounds.
- A geometric object, e.g., shapely geometry, or a sequence of geometric objects (polygon or multi-polygon). In such a case, the value is passed as the `data` argument of the GeoSeries constructor, and needs to be in the same CRS as the one provided through the `crs` argument.
- A geopandas geo-series or geo-data frame.
- A filename or URL, a file-like object opened in binary ('rb') mode, or a Path object that will be passed to `geopandas.read_file`.
Then, the processed `region` attribute can be accessed as a geo-data frame:
```python
analysis.region
```
geometry
bbox_west
bbox_south
bbox_east
bbox_north
place_id
osm_type
osm_id
lat
lon
class
type
place_rank
importance
addresstype
name
display_name
0
MULTIPOLYGON (((6.58387 46.55187, 6.58632 46.5...
6.583868
46.454873
6.720814
46.602577
83952532
relation
1685018
46.521827
6.632702
boundary
administrative
16
0.6941
city
Lausanne
Lausanne, District de Lausanne, Vaud, Switzerland
Note that *when setting `region` to a naive geometry*, i.e, without associated coordinate reference system (CRS), the setter will try to retrieve a CRS by looking whether the object has a `crs` or `CRS` attribute (in that order). In absence of these, a `ValueError` will be raised.
With the `region` attribute properly set, we can also generate regular grids using the `generate_regular_grid_gser` method:
```python
import contextily as cx
res = 0.05
ax = analysis.generate_regular_grid_gser(res).plot(alpha=0.5, edgecolor="black")
cx.add_basemap(ax, crs=analysis.region.crs, attribution=False)
```
Alternatively, it is possible to use [the standalone `pyregeon.generate_regular_grid_gser` function](https://pyregeon.readthedocs.io/en/latest/api.html#pyregeon.generate_regular_grid_gser) without any class by prepending a geo-series with the region as first positional argument (and optionally providing the `crs` keyword argument if the provided geo-series is naive).
See the [API documentation](https://pyregeon.readthedocs.io/en/latest/api.html) for more details or the [multiurbanpy](https://github.com/martibosch/multiurbanpy) library for an example use case of pyregeon.
## Installation
```bash
pip install pyregeon
```
## Acknowledgements
- This package was created with the [martibosch/cookiecutter-geopy-package](https://github.com/martibosch/cookiecutter-geopy-package) project template.