| Name | shapely-cli JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | A command line tool for operating on GeoJSON objects with Shapely |
| upload_time | 2024-09-02 22:01:15 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | None |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Shapely CLI
A command line tool which wraps the [shapely] Python package (which in turn wraps [GEOS]), providing a convenient way to apply various operations to GeoJSON geometries from the command line.
> [!NOTE]
> This is a tool I wrote for personal use and is not affiliated with the Shapely project or endorsed by its maintainers.
## Examples
Say you have a GeoJSON file containing a single `FeatureCollection`, like [this one](./tests/great-lakes.geojson) which contains five features representing the five [Great Lakes](https://en.wikipedia.org/wiki/Great_Lakes) (each feature has some properties and a `Polygon` geometry).
Here are some things you could use `shapely-cli` to do.
Print the bounding boxes of each geometry:
```
$ shapely 'bounds(geom)' < great-lakes.geojson
[-92.11418, 46.42339, -84.35621, 49.02763]
[-88.04342, 41.62791, -84.77450, 46.11519]
[-79.77473, 43.19010, -75.77020, 44.50443]
[-83.46620, 41.39359, -78.86750, 43.10620]
[-84.78083, 43.01730, -79.66258, 46.35539]
```
Update each feature so that its geometry is guaranteed to be valid:
```
$ shapely 'geom = make_valid(geom)' < great-lakes.geojson
```
Add a bbox property to each feature:
```
$ shapely 'feature["bbox"] = bounds(geom)' < great-lakes.geojson
```
Produce a single MultiPolygon containing all of the input geometries:
```
$ shapely 'union_all(geoms)' < great-lakes.geojson
```
Find and print the feature with the largest area:
```
$ shapely 'max(features, key=lambda f: geodesic_area(f["geometry"]))' < great-lakes.geojson
```
Simplify each feature's geometry using [Ramer–Douglas–Peucker algorithm](https://en.wikipedia.org/wiki/Ramer–Douglas–Peucker_algorithm):
```
$ shapely 'geom = simplify(geom, tolerance=0.05)' < great-lakes.geojson
```
Reproject each feature from WGS 84 Lon/Lat to [Web Mercator coordinates](https://epsg.io/3857):
```
$ shapely 'geom = transform(geom, proj(4326, 3857))' < great-lakes.geojson
```
All of the above would also work if the input file were a newline-separated sequence of individual GeoJSON features, like [this](./tests/great-lakes.ndjson).
## Installation
Clone this repository, cd into it, and then run `pip install .`. Check that it worked by running `shapely --version` in your shell.
TODO: package for Homebrew or PyPI
## How it works
The tool takes one argument which is a Python expression, statement, or series of statements (you can use semicolons to smush multiple statements into one line). It then reads a GeoJSON object or a newline-delimited sequence of GeoJSON objects (it automatically detects the difference) and applies the Python snippet to each feature or geometry in the input.
The Python snippet has access to the following variables:
- `feature` is the GeoJSON feature currently being processed
- `geom` is the GeoJSON geometry currently being processed (either a bare geometry or the one associated with the current `feature`)
In addition, everything from Shapely is in scope (via `from shapely import *`), as well as a few additional [helper functions](./src/shapely_cli/helpers.py).
The Python snippet may end in an expression, in which case the result of that expression will be printed to STDOUT. Or, the Python snippet may be a statement (or series of statements) which modify `feature`, `geom`, or both. In this case each feature or geometry from STDIN is dumped back to STDOUT (with the modifications applied). If you wish to omit a feature from the output, use `feature = None` or `del feature`.
If the Python snippet refers to the variables `features` or `geoms` (in the plural), then instead of being run for each feature/geometry in the input, it will just be run once. `features` will be a list of all features in the input, and `geoms` will be a list of all geoms. This allows for aggregate operations like unioning all the geometries together, or finding the feature with the largest bounding box.
## Purpose
I work on geospatial software and do a lot of ad-hoc manipulation of geospatial data. I was finding myself frequently writing short Python scripts to transform GeoJSON data, like the following example:
```python
#!/usr/bin/env python3
"""
Add a bounding box to each feature in the input GeoJSON.
Usage: python add_bbox.py < input.geojson > output.geojson
"""
import sys
import json
import shapely
geojson = json.load(sys.stdin)
assert geojson.get("type") == "FeatureCollection"
for feature in geojson["features"]:
geom = shapely.geometry.mapping(feature["geometry"])
feature["bbox"] = shapely.bounds(geom)
json.dump(geojson, file=sys.stdout)
```
I wrote shapely-cli as an experiment to see if I could replace these single-purpose scripts with one-liners. So far I've found it to be moderately useful.
There are still missing features (for example, if the input is a FeatureCollection, it's not possible to access or modify the `properties` on that collection). And I'm honestly not sure yet if the approach I've taken (evaling Python snippets) is a good idea or not. Is it too magic? Or just the right amount?
If you decide to try out this tool, I'd love to hear your thoughts on it and how you're using it. Feel free to open an issue or email me.
[shapely]: https://shapely.readthedocs.io/en/stable/manual.html
[GEOS]: https://libgeos.org/
Raw data
{
"_id": null,
"home_page": null,
"name": "shapely-cli",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Jake Low <hello@jakelow.com>",
"download_url": "https://files.pythonhosted.org/packages/2d/d6/289384baf9b8165e51e18644331332d172f55b9fbd7ba7848289e41cf6c7/shapely_cli-0.1.1.tar.gz",
"platform": null,
"description": "# Shapely CLI\n\nA command line tool which wraps the [shapely] Python package (which in turn wraps [GEOS]), providing a convenient way to apply various operations to GeoJSON geometries from the command line.\n\n> [!NOTE]\n> This is a tool I wrote for personal use and is not affiliated with the Shapely project or endorsed by its maintainers.\n\n## Examples\n\nSay you have a GeoJSON file containing a single `FeatureCollection`, like [this one](./tests/great-lakes.geojson) which contains five features representing the five [Great Lakes](https://en.wikipedia.org/wiki/Great_Lakes) (each feature has some properties and a `Polygon` geometry).\n\nHere are some things you could use `shapely-cli` to do.\n\nPrint the bounding boxes of each geometry:\n```\n$ shapely 'bounds(geom)' < great-lakes.geojson\n[-92.11418, 46.42339, -84.35621, 49.02763]\n[-88.04342, 41.62791, -84.77450, 46.11519]\n[-79.77473, 43.19010, -75.77020, 44.50443]\n[-83.46620, 41.39359, -78.86750, 43.10620]\n[-84.78083, 43.01730, -79.66258, 46.35539]\n```\n\nUpdate each feature so that its geometry is guaranteed to be valid:\n```\n$ shapely 'geom = make_valid(geom)' < great-lakes.geojson\n```\n\nAdd a bbox property to each feature:\n```\n$ shapely 'feature[\"bbox\"] = bounds(geom)' < great-lakes.geojson\n```\n\nProduce a single MultiPolygon containing all of the input geometries:\n```\n$ shapely 'union_all(geoms)' < great-lakes.geojson\n```\n\nFind and print the feature with the largest area:\n```\n$ shapely 'max(features, key=lambda f: geodesic_area(f[\"geometry\"]))' < great-lakes.geojson\n```\n\nSimplify each feature's geometry using [Ramer\u2013Douglas\u2013Peucker algorithm](https://en.wikipedia.org/wiki/Ramer\u2013Douglas\u2013Peucker_algorithm):\n```\n$ shapely 'geom = simplify(geom, tolerance=0.05)' < great-lakes.geojson\n```\n\nReproject each feature from WGS 84 Lon/Lat to [Web Mercator coordinates](https://epsg.io/3857):\n```\n$ shapely 'geom = transform(geom, proj(4326, 3857))' < great-lakes.geojson\n```\n\nAll of the above would also work if the input file were a newline-separated sequence of individual GeoJSON features, like [this](./tests/great-lakes.ndjson).\n\n## Installation\n\nClone this repository, cd into it, and then run `pip install .`. Check that it worked by running `shapely --version` in your shell.\n\nTODO: package for Homebrew or PyPI\n\n## How it works\n\nThe tool takes one argument which is a Python expression, statement, or series of statements (you can use semicolons to smush multiple statements into one line). It then reads a GeoJSON object or a newline-delimited sequence of GeoJSON objects (it automatically detects the difference) and applies the Python snippet to each feature or geometry in the input.\n\nThe Python snippet has access to the following variables:\n- `feature` is the GeoJSON feature currently being processed\n- `geom` is the GeoJSON geometry currently being processed (either a bare geometry or the one associated with the current `feature`)\n\nIn addition, everything from Shapely is in scope (via `from shapely import *`), as well as a few additional [helper functions](./src/shapely_cli/helpers.py).\n\nThe Python snippet may end in an expression, in which case the result of that expression will be printed to STDOUT. Or, the Python snippet may be a statement (or series of statements) which modify `feature`, `geom`, or both. In this case each feature or geometry from STDIN is dumped back to STDOUT (with the modifications applied). If you wish to omit a feature from the output, use `feature = None` or `del feature`.\n\nIf the Python snippet refers to the variables `features` or `geoms` (in the plural), then instead of being run for each feature/geometry in the input, it will just be run once. `features` will be a list of all features in the input, and `geoms` will be a list of all geoms. This allows for aggregate operations like unioning all the geometries together, or finding the feature with the largest bounding box.\n\n## Purpose\n\nI work on geospatial software and do a lot of ad-hoc manipulation of geospatial data. I was finding myself frequently writing short Python scripts to transform GeoJSON data, like the following example:\n\n```python\n#!/usr/bin/env python3\n\"\"\"\nAdd a bounding box to each feature in the input GeoJSON.\nUsage: python add_bbox.py < input.geojson > output.geojson\n\"\"\"\nimport sys\nimport json\nimport shapely\n\ngeojson = json.load(sys.stdin)\nassert geojson.get(\"type\") == \"FeatureCollection\"\n\nfor feature in geojson[\"features\"]:\n geom = shapely.geometry.mapping(feature[\"geometry\"])\n feature[\"bbox\"] = shapely.bounds(geom)\n\njson.dump(geojson, file=sys.stdout)\n```\n\nI wrote shapely-cli as an experiment to see if I could replace these single-purpose scripts with one-liners. So far I've found it to be moderately useful.\n\nThere are still missing features (for example, if the input is a FeatureCollection, it's not possible to access or modify the `properties` on that collection). And I'm honestly not sure yet if the approach I've taken (evaling Python snippets) is a good idea or not. Is it too magic? Or just the right amount?\n\nIf you decide to try out this tool, I'd love to hear your thoughts on it and how you're using it. Feel free to open an issue or email me.\n\n[shapely]: https://shapely.readthedocs.io/en/stable/manual.html\n[GEOS]: https://libgeos.org/\n",
"bugtrack_url": null,
"license": null,
"summary": "A command line tool for operating on GeoJSON objects with Shapely",
"version": "0.1.1",
"project_urls": {
"Repository": "https://github.com/jake-low/shapely-cli"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bcf4522aab0490118c008e001398ee30a3d3142161539de36aaefe8b2f49bde8",
"md5": "73ab98948b77f39ee4dd3d04b2aea885",
"sha256": "8109792a74d051be700578bb36c677bccaf1f6f1644ce964a1df5f895a10d8a0"
},
"downloads": -1,
"filename": "shapely_cli-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "73ab98948b77f39ee4dd3d04b2aea885",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7105,
"upload_time": "2024-09-02T22:01:14",
"upload_time_iso_8601": "2024-09-02T22:01:14.329891Z",
"url": "https://files.pythonhosted.org/packages/bc/f4/522aab0490118c008e001398ee30a3d3142161539de36aaefe8b2f49bde8/shapely_cli-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2dd6289384baf9b8165e51e18644331332d172f55b9fbd7ba7848289e41cf6c7",
"md5": "c4746f380636f5c6d52d845e92868484",
"sha256": "4e19de9065d466fec354b25398b8be807df91633506325cd7f8f0919a024aba7"
},
"downloads": -1,
"filename": "shapely_cli-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "c4746f380636f5c6d52d845e92868484",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 6527,
"upload_time": "2024-09-02T22:01:15",
"upload_time_iso_8601": "2024-09-02T22:01:15.838492Z",
"url": "https://files.pythonhosted.org/packages/2d/d6/289384baf9b8165e51e18644331332d172f55b9fbd7ba7848289e41cf6c7/shapely_cli-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-02 22:01:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jake-low",
"github_project": "shapely-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "shapely-cli"
}
