[](https://sonarcloud.io/dashboard?id=EL-BID_BabelGrid)
[](https://pepy.tech/project/babelgrid)
**BabelGrid is a common python API to work with different established geospatial indexing systems.**
Currently, it supports [H3](https://h3geo.org/), [S2](https://s2geometry.io/) and [Bing](https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system) geospatial indexing systems.
BabelGrid does not have the intention to replace any of the existing APIs, but
to create a common framework that geo-folks can use to easily switch between grids. Also,
it generates methods around the tiles that ease the data analysis pipeline with seamlessly integration
with well knonw libraries such as Shapely and GeoPandas.
## Start Using It
Install with
```bash
pip install babelgrid
```
- Get a h3 tile with an area of 1km2 in São Paulo, Brasil.
```python
>>> from babelgrid import Babel
>>> tile = Babel('h3').geo_to_tile(lat=-23, lon=-43, area_km=1)
>>> tile
Tile: grid_type "h3", resolution 8, tile_id 88a8a2b66dfffff
```
- Access the geojson, wkt and shapely descriptions of the tile:
```python
>>> tile.geometry.geojson
{'type': 'Polygon',
'coordinates': (((-42.99741709893686, -23.004282833594505),
(-42.9932470321478, -23.00127887552568),
(-42.994161748920796, -22.996608473771282),
(-42.99924646130203, -22.994942061847414),
(-43.00341650043048, -22.997946087213307),
(-43.002501854850166, -23.002616457194414),
(-42.99741709893686, -23.004282833594505)),)}
>>> tile.geometry.wkt
'POLYGON ((-42.9974170989368574 -23.0042828335945053, -42.9932470321477993 -23.0012788755256814, -42.9941617489207957 -22.9966084737712819, -42.9992464613020289 -22.9949420618474143, -43.0034165004304825 -22.9979460872133075, -43.0025018548501663 -23.0026164571944136, -42.9974170989368574 -23.0042828335945053))'
>>> tile.geometry.shapely
```
![][shapely]
- Fill a geometry with s2 tiles of resolution 10
```python
>>> tiles = Babel('s2').polyfill(geometry, resolution=10)
>>> tiles
[Tile: grid_type "s2", resolution 10, tile_id 94d28d,... ,Tile: grid_type "s2", resolution 10, tile_id 94d28f]
```
- Load a geopandas dataframe with the selected tiles
```python
>>> import geopandas as gpd
>>> gpd.GeoDataFrame([t.to_dict() for t in tiles], geometry='shapely')
```
## Quick Documentation
### Babel
You have to initialize the Babel object with any of the available grids.
```python
>>> Babel.available_grids()
['s2', 'h3', 'bing']
>>> grid = Babel('s2') # example
```
### geo_to_tile
It receives a coordinate pair (lat, lon) and either the native grid resolution or an area in km2.
If it receives an area, it automatically finds what is the resolution for that tile system and latitute
that best approximates the given area.
```python
>>> Babel('s2').geo_to_tile(2, 3, resolution=10)
Tile: grid_type "s2", resolution 10, tile_id 100fb1
>>> Babel('bing').geo_to_tile(2, 3, area_km=0.1)
Tile: grid_type "bing", resolution 17, tile_id 12222230201200322
>>> Babel('bing').geo_to_tile(2, 3, area_km=0.1).area_km
0.0934819087
```
### id_to_tile
It receives a tile id and converts it to a Tile Object.
```python
>>> Babel('s2').id_to_tile('100fb1')
Tile: grid_type "s2", resolution 10, tile_id 100fb1
```
### Polyfill
One of the most common uses to geospatial indexing systems is to fill up a geometry. This function receives
a geometry that can be a polygon or multipolygons and returns a list of Tile Objects.
```python
>>> tiles = Babel('s2').polyfill(geometry, resolution=10)
>>> tiles
[Tile: grid_type "s2", resolution 10, tile_id 94d28d,... ,Tile: grid_type "s2", resolution 10, tile_id 94d28f]
```
You can also pass a 'desired' grid area using the parameter `grid_km`.
```python
>>> tiles = Babel('bing').polyfill(geometry, area_km=10)
>>> tiles
[Tile: grid_type "bing", resolution 14, tile_id 21031113121331, ..., Tile: grid_type "bing", resolution 14, tile_id 21031113121333]
```
The image below shows `polyfill` being applied for the same geometry for different grid types and sizes.
![][polyfill]
### The Tile Object
The Tile Object is a central piece of the package. This is the object that is returned by most of the methods implemented. It is good because it
has some handy features that speed-up the analysis process.
- Easy access to wkt, geojson and shapely geometries
```python
>>> tile.geometry.wkt
>>> tile.geometry.geojson
>>> tile.geometry.shapely
```
- Child and parent transformation
```python
>>> tile.to_parent()
>>> tile.to_children()
```
- Area in km2 already calculated
```python
>>> tile.area_km
```
- To dictonary export of all properties
```python
>>> tile.to_dict()
```
## Grid Systems
| | H3 | S2 | BING/QuadTree |
|------------------------|----------------------------------------|------------------------------------------------------|---------------------------------------------------------------------------------------------------|
| Tile Shape | Hexagonal | Square | Square |
| Resolution Range | 0 - 15 | 0 - 30 | 1 - 23 (infinite) |
| API Reference | [h3-py](https://github.com/uber/h3-py) | [s2sphere](https://github.com/sidewalklabs/s2sphere) | [pygeotile](https://github.com/geometalab/pyGeoTile) |
| Original Documentation | [H3](https://h3geo.org/) | [S2 Geometry](https://s2geometry.io/) | [Bing Maps Tile System](https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system) |
:star: Kudos to all developer of H3, S2 and Bing/QuadTree systems.
### Resolution Reference Table and Plot
Lookup table with grid resolutions at equator by area in km2.
Note that the area is written in scientific notation (10^x) and x
is the index of the table.
| Area (10^x km2) | H3 | S2 | BING/QuadTree |
|-----------:|:------|:------|:----------------|
| 9 | - | - | 1 |
| 8 | - | 0 | 2 |
| 7 | - | 1,2 | 3,4 |
| 6 | 0,1 | 3,4 | 5,6 |
| 5 | 2 | 5 | 7 |
| 4 | 3 | 6,7 | 8,9 |
| 3 | 4 | 8 | 10,11 |
| 2 | 5 | 9,10 | 12 |
| 1 | 6,7 | 11,12 | 13,14 |
| 0 | 8 | 13 | 15,16 |
| -1 | 9 | 14,15 | 17 |
| -2 | 10 | 16,17 | 18,19 |
| -3 | 11 | 18 | 20,21 |
| -4 | 12,13 | 19,20 | 22 |
| -5 | 14 | 21,22 | 23 |
| -6 | 15 | 23 | - |
| -7 | - | 24,25 | - |
| -8 | - | 26,27 | - |
| -9 | - | 28 | - |
| -10 | - | 29,30 | - |
![][area-res]
### Tile Area Distortion by Latitude
Depending on how the tile system is built, the area of the tile varies given the latitude.
For inter-region comparissons, this behaviour can affect the analysis.
The figure below shows the tile area distortion by geospatial indexing systems. The distortion is defined as
<a href="https://www.codecogs.com/eqnedit.php?latex=D&space;=&space;A_l&space;/&space;A_e" target="_blank"><img src="https://latex.codecogs.com/gif.latex?D&space;=&space;A_l&space;/&space;A_e" title="D = A_l / A_e" /></a>
where <a href="https://www.codecogs.com/eqnedit.php?latex=\inline&space;A" target="_blank"><img src="https://latex.codecogs.com/gif.latex?\inline&space;A" title="A" /></a> is the tile area and <a href="https://www.codecogs.com/eqnedit.php?latex=\inline&space;l" target="_blank"><img src="https://latex.codecogs.com/gif.latex?\inline&space;l" title="l" /></a> the area given a latitude and <a href="https://www.codecogs.com/eqnedit.php?latex=\inline&space;e" target="_blank"><img src="https://latex.codecogs.com/gif.latex?\inline&space;e" title="e" /></a> the equator area. The figure
shows the mean distortion given all resolutions and the error bar is the standard deviation.
![][area-distortion]
[shapely]: https://github.com/EL-BID/BabelGrid/blob/master/imgs/Screen%20Shot%202020-07-20%20at%2019.47.58.png
[polyfill]: https://github.com/EL-BID/BabelGrid/blob/master/imgs/polyfill.png
[area-res]: https://github.com/EL-BID/BabelGrid/blob/master/imgs/gridtype-area-res.png?raw=true
[area-distortion]: https://github.com/EL-BID/BabelGrid/blob/master/imgs/gridtype-distortion.png
## Contributing
Any contribution is very welcomed. You can contribute in several ways:
- Suggest new geospatial indexing systems
- Raise issues with bugs and problems
- Propose new features or behaviours
- Contribute with code maintenence
## Developing
Start envorinment with
`make create-env`
Update envorinment with
`make update-env`
Publish to PyPi
```bash
poetry version [patch, minor, major]
make publish
```
## Authors
- Joao Carabetta (joaom at iadb.org)
## License
This work is licensed under AM-331-A3 - see the [LICENSE.md](LICENSE.md) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/EL-BID/BabelGrid",
"name": "babelgrid",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Joao Carabetta",
"author_email": "joao.carabetta@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/66/1a/67ef5fe9434623009cfa08743d42d8f831e1b3499aeb6b46c2d8fa758ed9/babelgrid-0.1.7.tar.gz",
"platform": null,
"description": "[](https://sonarcloud.io/dashboard?id=EL-BID_BabelGrid)\n[](https://pepy.tech/project/babelgrid)\n\n\n\n**BabelGrid is a common python API to work with different established geospatial indexing systems.**\n\n\nCurrently, it supports [H3](https://h3geo.org/), [S2](https://s2geometry.io/) and [Bing](https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system) geospatial indexing systems. \nBabelGrid does not have the intention to replace any of the existing APIs, but\nto create a common framework that geo-folks can use to easily switch between grids. Also, \nit generates methods around the tiles that ease the data analysis pipeline with seamlessly integration\nwith well knonw libraries such as Shapely and GeoPandas.\n\n\n\n## Start Using It\n\nInstall with\n```bash\npip install babelgrid\n```\n\n- Get a h3 tile with an area of 1km2 in S\u00e3o Paulo, Brasil.\n```python\n>>> from babelgrid import Babel\n\n>>> tile = Babel('h3').geo_to_tile(lat=-23, lon=-43, area_km=1)\n>>> tile\nTile: grid_type \"h3\", resolution 8, tile_id 88a8a2b66dfffff\n```\n\n- Access the geojson, wkt and shapely descriptions of the tile:\n```python\n>>> tile.geometry.geojson\n{'type': 'Polygon',\n 'coordinates': (((-42.99741709893686, -23.004282833594505),\n (-42.9932470321478, -23.00127887552568),\n (-42.994161748920796, -22.996608473771282),\n (-42.99924646130203, -22.994942061847414),\n (-43.00341650043048, -22.997946087213307),\n (-43.002501854850166, -23.002616457194414),\n (-42.99741709893686, -23.004282833594505)),)}\n>>> tile.geometry.wkt\n'POLYGON ((-42.9974170989368574 -23.0042828335945053, -42.9932470321477993 -23.0012788755256814, -42.9941617489207957 -22.9966084737712819, -42.9992464613020289 -22.9949420618474143, -43.0034165004304825 -22.9979460872133075, -43.0025018548501663 -23.0026164571944136, -42.9974170989368574 -23.0042828335945053))'\n>>> tile.geometry.shapely\n```\n![][shapely]\n\n- Fill a geometry with s2 tiles of resolution 10\n```python\n>>> tiles = Babel('s2').polyfill(geometry, resolution=10)\n>>> tiles\n[Tile: grid_type \"s2\", resolution 10, tile_id 94d28d,... ,Tile: grid_type \"s2\", resolution 10, tile_id 94d28f]\n```\n- Load a geopandas dataframe with the selected tiles\n```python\n>>> import geopandas as gpd\n>>> gpd.GeoDataFrame([t.to_dict() for t in tiles], geometry='shapely')\n```\n\n\n## Quick Documentation\n\n### Babel\n\nYou have to initialize the Babel object with any of the available grids. \n\n```python\n>>> Babel.available_grids()\n['s2', 'h3', 'bing']\n\n>>> grid = Babel('s2') # example\n```\n\n\n### geo_to_tile\n\nIt receives a coordinate pair (lat, lon) and either the native grid resolution or an area in km2.\nIf it receives an area, it automatically finds what is the resolution for that tile system and latitute \nthat best approximates the given area.\n\n```python\n>>> Babel('s2').geo_to_tile(2, 3, resolution=10)\nTile: grid_type \"s2\", resolution 10, tile_id 100fb1\n\n>>> Babel('bing').geo_to_tile(2, 3, area_km=0.1)\nTile: grid_type \"bing\", resolution 17, tile_id 12222230201200322\n\n>>> Babel('bing').geo_to_tile(2, 3, area_km=0.1).area_km\n0.0934819087\n```\n\n### id_to_tile\n\nIt receives a tile id and converts it to a Tile Object.\n\n```python\n>>> Babel('s2').id_to_tile('100fb1')\nTile: grid_type \"s2\", resolution 10, tile_id 100fb1\n```\n\n### Polyfill\nOne of the most common uses to geospatial indexing systems is to fill up a geometry. This function receives\na geometry that can be a polygon or multipolygons and returns a list of Tile Objects.\n\n```python\n>>> tiles = Babel('s2').polyfill(geometry, resolution=10)\n>>> tiles\n[Tile: grid_type \"s2\", resolution 10, tile_id 94d28d,... ,Tile: grid_type \"s2\", resolution 10, tile_id 94d28f]\n```\n\nYou can also pass a 'desired' grid area using the parameter `grid_km`.\n\n```python\n>>> tiles = Babel('bing').polyfill(geometry, area_km=10)\n>>> tiles\n[Tile: grid_type \"bing\", resolution 14, tile_id 21031113121331, ..., Tile: grid_type \"bing\", resolution 14, tile_id 21031113121333]\n```\n\nThe image below shows `polyfill` being applied for the same geometry for different grid types and sizes.\n\n![][polyfill]\n\n### The Tile Object\n\nThe Tile Object is a central piece of the package. This is the object that is returned by most of the methods implemented. It is good because it \nhas some handy features that speed-up the analysis process.\n\n- Easy access to wkt, geojson and shapely geometries\n\n```python\n>>> tile.geometry.wkt\n>>> tile.geometry.geojson\n>>> tile.geometry.shapely\n```\n\n- Child and parent transformation\n\n```python\n>>> tile.to_parent()\n>>> tile.to_children()\n```\n\n- Area in km2 already calculated\n\n```python\n>>> tile.area_km\n```\n\n- To dictonary export of all properties\n\n```python\n>>> tile.to_dict()\n```\n\n## Grid Systems\n\n\n\n| | H3 | S2 | BING/QuadTree |\n|------------------------|----------------------------------------|------------------------------------------------------|---------------------------------------------------------------------------------------------------|\n| Tile Shape | Hexagonal | Square | Square |\n| Resolution Range | 0 - 15 | 0 - 30 | 1 - 23 (infinite) |\n| API Reference | [h3-py](https://github.com/uber/h3-py) | [s2sphere](https://github.com/sidewalklabs/s2sphere) | [pygeotile](https://github.com/geometalab/pyGeoTile) |\n| Original Documentation | [H3](https://h3geo.org/) | [S2 Geometry](https://s2geometry.io/) | [Bing Maps Tile System](https://docs.microsoft.com/en-us/bingmaps/articles/bing-maps-tile-system) |\n\n:star: Kudos to all developer of H3, S2 and Bing/QuadTree systems.\n\n### Resolution Reference Table and Plot\n\n\nLookup table with grid resolutions at equator by area in km2. \nNote that the area is written in scientific notation (10^x) and x \nis the index of the table.\n\n| Area (10^x km2) | H3 | S2 | BING/QuadTree |\n|-----------:|:------|:------|:----------------|\n| 9 | - | - | 1 |\n| 8 | - | 0 | 2 |\n| 7 | - | 1,2 | 3,4 |\n| 6 | 0,1 | 3,4 | 5,6 |\n| 5 | 2 | 5 | 7 |\n| 4 | 3 | 6,7 | 8,9 |\n| 3 | 4 | 8 | 10,11 |\n| 2 | 5 | 9,10 | 12 |\n| 1 | 6,7 | 11,12 | 13,14 |\n| 0 | 8 | 13 | 15,16 |\n| -1 | 9 | 14,15 | 17 |\n| -2 | 10 | 16,17 | 18,19 |\n| -3 | 11 | 18 | 20,21 |\n| -4 | 12,13 | 19,20 | 22 |\n| -5 | 14 | 21,22 | 23 |\n| -6 | 15 | 23 | - |\n| -7 | - | 24,25 | - |\n| -8 | - | 26,27 | - |\n| -9 | - | 28 | - |\n| -10 | - | 29,30 | - |\n\n\n![][area-res]\n\n### Tile Area Distortion by Latitude\n\nDepending on how the tile system is built, the area of the tile varies given the latitude. \nFor inter-region comparissons, this behaviour can affect the analysis. \n\nThe figure below shows the tile area distortion by geospatial indexing systems. The distortion is defined as\n\n<a href=\"https://www.codecogs.com/eqnedit.php?latex=D&space;=&space;A_l&space;/&space;A_e\" target=\"_blank\"><img src=\"https://latex.codecogs.com/gif.latex?D&space;=&space;A_l&space;/&space;A_e\" title=\"D = A_l / A_e\" /></a>\n\nwhere <a href=\"https://www.codecogs.com/eqnedit.php?latex=\\inline&space;A\" target=\"_blank\"><img src=\"https://latex.codecogs.com/gif.latex?\\inline&space;A\" title=\"A\" /></a> is the tile area and <a href=\"https://www.codecogs.com/eqnedit.php?latex=\\inline&space;l\" target=\"_blank\"><img src=\"https://latex.codecogs.com/gif.latex?\\inline&space;l\" title=\"l\" /></a> the area given a latitude and <a href=\"https://www.codecogs.com/eqnedit.php?latex=\\inline&space;e\" target=\"_blank\"><img src=\"https://latex.codecogs.com/gif.latex?\\inline&space;e\" title=\"e\" /></a> the equator area. The figure\nshows the mean distortion given all resolutions and the error bar is the standard deviation.\n\n![][area-distortion]\n\n[shapely]: https://github.com/EL-BID/BabelGrid/blob/master/imgs/Screen%20Shot%202020-07-20%20at%2019.47.58.png\n[polyfill]: https://github.com/EL-BID/BabelGrid/blob/master/imgs/polyfill.png\n[area-res]: https://github.com/EL-BID/BabelGrid/blob/master/imgs/gridtype-area-res.png?raw=true\n[area-distortion]: https://github.com/EL-BID/BabelGrid/blob/master/imgs/gridtype-distortion.png\n\n## Contributing\n\nAny contribution is very welcomed. You can contribute in several ways:\n\n- Suggest new geospatial indexing systems\n- Raise issues with bugs and problems\n- Propose new features or behaviours\n- Contribute with code maintenence \n\n## Developing\n\nStart envorinment with\n\n`make create-env`\n\nUpdate envorinment with\n\n`make update-env`\n\nPublish to PyPi\n\n```bash\npoetry version [patch, minor, major]\nmake publish\n```\n\n## Authors\n\n- Joao Carabetta (joaom at iadb.org)\n\n## License\n\nThis work is licensed under AM-331-A3 - see the [LICENSE.md](LICENSE.md) file for details.\n\n",
"bugtrack_url": null,
"license": "AM-331-A3 Licencia de Software",
"summary": "A common python API to work with different established grid systems.",
"version": "0.1.7",
"project_urls": {
"Homepage": "https://github.com/EL-BID/BabelGrid",
"Repository": "https://github.com/EL-BID/BabelGrid"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "44ea9b4d7500a2a99ae384c2e79271f8f5abd5c2570598dbecf310d4a800c3d9",
"md5": "3740d058cf828bcb6f99c8cfe259e8c0",
"sha256": "19e35700b52debe988fc806fef686e41ba3eceabaff3b5183a2e7426b657e0f8"
},
"downloads": -1,
"filename": "babelgrid-0.1.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3740d058cf828bcb6f99c8cfe259e8c0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 15031,
"upload_time": "2023-11-25T02:10:10",
"upload_time_iso_8601": "2023-11-25T02:10:10.750654Z",
"url": "https://files.pythonhosted.org/packages/44/ea/9b4d7500a2a99ae384c2e79271f8f5abd5c2570598dbecf310d4a800c3d9/babelgrid-0.1.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "661a67ef5fe9434623009cfa08743d42d8f831e1b3499aeb6b46c2d8fa758ed9",
"md5": "52cc7219c4a1a23502720420b7286a6f",
"sha256": "713365273a96f65352c48ba0fc19f07e515042fd8b99baa85b9bef8157787b3d"
},
"downloads": -1,
"filename": "babelgrid-0.1.7.tar.gz",
"has_sig": false,
"md5_digest": "52cc7219c4a1a23502720420b7286a6f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 17135,
"upload_time": "2023-11-25T02:10:12",
"upload_time_iso_8601": "2023-11-25T02:10:12.883680Z",
"url": "https://files.pythonhosted.org/packages/66/1a/67ef5fe9434623009cfa08743d42d8f831e1b3499aeb6b46c2d8fa758ed9/babelgrid-0.1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-25 02:10:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "EL-BID",
"github_project": "BabelGrid",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "s2sphere",
"specs": [
[
"==",
"0.2.5"
]
]
},
{
"name": "shapely",
"specs": [
[
"==",
"1.7.0"
]
]
},
{
"name": "h3",
"specs": [
[
"==",
"3.6.6"
]
]
},
{
"name": "pygeotile",
"specs": [
[
"==",
"1.0.6"
]
]
}
],
"lcname": "babelgrid"
}
JSON
