Package: babelgrid
BabelGrid is a common python API to work with different established geospatial indexing systems.Currently, it supportsH3,S2andBinggeospatial 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 ItInstall withpipinstallbabelgridGet a h3 tile with an area of 1km2 in São Paulo, Brasil.>>>frombabelgridimportBabel>>>tile=Babel('h3').geo_to_tile(lat=-23,lon=-43,area_km=1)>>>tileTile:grid_type"h3",resolution8,tile_id88a8a2b66dfffffAccess the geojson, wkt and shapely descriptions of the tile:>>>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.shapelyFill a geometry with s2 tiles of resolution 10>>>tiles=Babel('s2').polyfill(geometry,resolution=10)>>>tiles[Tile:grid_type"s2",resolution10,tile_id94d28d,...,Tile:grid_type"s2",resolution10,tile_id94d28f]Load a geopandas dataframe with the selected tiles>>>importgeopandasasgpd>>>gpd.GeoDataFrame([t.to_dict()fortintiles],geometry='shapely')Quick DocumentationBabelYou have to initialize the Babel object with any of the available grids.>>>Babel.available_grids()['s2','h3','bing']>>>grid=Babel('s2')# examplegeo_to_tileIt 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.>>>Babel('s2').geo_to_tile(2,3,resolution=10)Tile:grid_type"s2",resolution10,tile_id100fb1>>>Babel('bing').geo_to_tile(2,3,area_km=0.1)Tile:grid_type"bing",resolution17,tile_id12222230201200322>>>Babel('bing').geo_to_tile(2,3,area_km=0.1).area_km0.0934819087id_to_tileIt receives a tile id and converts it to a Tile Object.>>>Babel('s2').id_to_tile('100fb1')Tile:grid_type"s2",resolution10,tile_id100fb1PolyfillOne 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.>>>tiles=Babel('s2').polyfill(geometry,resolution=10)>>>tiles[Tile:grid_type"s2",resolution10,tile_id94d28d,...,Tile:grid_type"s2",resolution10,tile_id94d28f]You can also pass a 'desired' grid area using the parametergrid_km.>>>tiles=Babel('bing').polyfill(geometry,area_km=10)>>>tiles[Tile:grid_type"bing",resolution14,tile_id21031113121331,...,Tile:grid_type"bing",resolution14,tile_id21031113121333]The image below showspolyfillbeing applied for the same geometry for different grid types and sizes.The Tile ObjectThe 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>>>tile.geometry.wkt>>>tile.geometry.geojson>>>tile.geometry.shapelyChild and parent transformation>>>tile.to_parent()>>>tile.to_children()Area in km2 already calculated>>>tile.area_kmTo dictonary export of all properties>>>tile.to_dict()Grid SystemsH3S2BING/QuadTreeTile ShapeHexagonalSquareSquareResolution Range0 - 150 - 301 - 23 (infinite)API Referenceh3-pys2spherepygeotileOriginal DocumentationH3S2 GeometryBing Maps Tile System:star: Kudos to all developer of H3, S2 and Bing/QuadTree systems.Resolution Reference Table and PlotLookup 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)H3S2BING/QuadTree9--18-027-1,23,460,13,45,65257436,78,934810,11259,101216,711,1213,14081315,16-1914,1517-21016,1718,19-3111820,21-412,1319,2022-51421,2223-61523--7-24,25--8-26,27--9-28--10-29,30-Tile Area Distortion by LatitudeDepending 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 aswhereis the tile area andthe area given a latitude andthe equator area. The figure
shows the mean distortion given all resolutions and the error bar is the standard deviation.ContributingAny contribution is very welcomed. You can contribute in several ways:Suggest new geospatial indexing systemsRaise issues with bugs and problemsPropose new features or behavioursContribute with code maintenenceDevelopingStart envorinment withmake create-envUpdate envorinment withmake update-envPublish to PyPipoetryversion[patch,minor,major]makepublishAuthorsJoao Carabetta (joaom at iadb.org)LicenseThis work is licensed under AM-331-A3 - see theLICENSE.mdfile for details.