Vgrid¶

Vgrid - A Python package for working with popular geodesic DGGS and graticule-based DGGS

Vgrid supports a wide range of popular geodesic DGGS, including H3, S2, A5, rHEALPix, Open-EAGGR ISEA4T, ISEA3H, DGGRID, DGGAL, EASE-DGGS, QTM, along with graticule-based DGGS such as OLC, Geohash, MGRS, GEOREF, TileCode, Quadkey, Maidenhead, and GARS.

Vgrid supports popular input and output GIS formats, including CSV, GeoJSON, Pandas/GeoPandas, Shapefile, GeoPackage, and GeoParquet.

Full Vgrid DGGS documentation is available at vgrid document.

To work with Vgrid DGGS directly in GeoPandas and Pandas, use the vgridpandas package. Full Vgridpandas DGGS documentation is available at vgridpandas document.

To work with Vgrid DGGS in QGIS, install the Vgrid Plugin.

To visualize DGGS in Maplibre GL JS, try the vgrid-maplibre library.

For an interactive demo, visit the Vgrid Homepage.

References:¶

h3-py by Uber.
s2sphere by Sidewalk Labs.
a5-py by Felix Palmer and Thang Quach.
rhealpixdggs-py by Manaaki Whenua – Landcare Research.
open-eaggr by Riskaware.
EASE-DGGS by GEMS-UMN.
pydggal by Jerome St-Louis from Ecere.
DGGRID by Kevin Sahr.
dggrid4py by Alex Kmoch.
QTM by Thang Quach, with reference to QTM by Paulo Raposo.
Lat Lon Tools QGIS Plugin by Calvin Hamilton.
gars-field by Corteva Agriscience.
Tilecode & Quadkey by Thang Quach, utilizing mercantile by Mapbox.
antimeridian by gadomski.
The DGGS Inspect feature in Vgrid is inspired by Area and shape distortions in open-source discrete global grid systems by Alex Kmoch et al. (2022) (resources).
The Vgrid Document is inspired by leafmap developed by Qiusheng Wu from Open Geospatial Solutions.

Area distortion over normalized areas of popular geodesic DGGS¶

IPQ compactness distribution over popular geodesic DGGS¶

Isoperimetric Inequality (IPQ) Compactness (suggested by Osserman, 1987):

\[C_{IPQ} = \frac{4 \pi A}{p^2}\]

The range of the IPQ compactness metric is [0,1].

A circle represents the maximum compactness with a value of 1.

As shapes become more irregular or elongated, their compactness decreases toward 0.

Installation¶

pip¶

pip install vgrid --upgrade

Key Features¶

DGGS Conversion: Convert Latlon to DGGS, DGGS cells to Shapely Geometry/ GeoJSON, Vector to DGGS, Raster to DGGS.
DGGS Compact: Compact DGGS cells or expand them to a specific resolution.
DGGS Binning: Aggregate points into DGGS cells, supporting common statistics (count, min, max, etc.) and category-based groups.
DGGS Generator: Generate DGGS at a specfic bounding box and resolution.
DGGS Inspect: Calculate and visualize DGGS area distortions and IPQ (isoperimetric inequality) compactness at a specific resolution.
DGGS Stats: Show DGGS metrics for each resolution like number of cells, average edge length, average cell area, perimeter.

Usage examples¶

Latlon to DGGS¶

>>> from vgrid.conversion.latlon2dggs import latlon2h3
>>> lat = 10.775276
>>> lon = 106.706797
>>> res = 10
h3_id = latlon2h3(lat, lon, res)
h3_id

'8a65b56628e7fff'

DGGS to Shapely Polygon¶

import geopandas as gpd
from vgrid.conversion.dggs2geo.h32geo import h32geo
h3_geo = h32geo(h3_id)
h3_geo

POLYGON ((106.70713615426936 10.774978441229653, 106.70721514572995 10.775713374905791, 106.70661718075799 10.776150587194028, 106.70594022237229 10.77585286364977, 106.70586123315323 10.77511792678204, 106.70645920007833 10.774680716650128, 106.70713615426936 10.774978441229653))

DGGS to GeoJSON¶

>>> from vgrid.conversion.dggs2geo.h32geo import h32geojson
>>> h3_geojson = h32geojson(h3_id)
>>> h3_geojson

{'type': 'FeatureCollection', 'features': [{'type': 'Feature', 'geometry': {'type': 'Polygon', 'coordinates': (((106.70713615426936, 10.774978441229653), (106.70721514572995, 10.775713374905791), (106.70661718075799, 10.776150587194028), (106.70594022237229, 10.77585286364977), (106.70586123315323, 10.77511792678204), (106.70645920007833, 10.774680716650128), (106.70713615426936, 10.774978441229653)),)}, 'properties': {'h3': '8a65b56628e7fff', 'resolution': 10, 'center_lat': 10.7754157, 'center_lon': 106.7065382, 'avg_edge_len': 81.374, 'cell_area': 17202.984}}]}

Vector to DGGS¶

from vgrid.conversion.vector2dggs.vector2isea4t import vector2isea4t

file_path = ("https://raw.githubusercontent.com/opengeoshub/vopendata/main/shape/polygon.geojson")
vector_to_isea4t = vector2isea4t(file_path, resolution=16, compact=False, predicate = "centroid_within", output_format="gpd")

DGGS Compact¶

from vgrid.conversion.dggscompact.isea4tcompact import isea4tcompact

isea4t_compacted = isea4tcompact(vector_to_isea4t,output_format="gpd")

DGGS Expand¶

from vgrid.conversion.dggscompact.isea4tcompact import isea4texpand

isea4t_expanded = isea4texpand(isea4t_compacted, resolution=17, output_format="gpd")   

DGGS Binning¶

from vgrid.binning.h3bin import h3bin
file_path = ("https://raw.githubusercontent.com/opengeoshub/vopendata/main/csv/dist1_pois.csv")
stats="count"
h3_bin = h3bin(file_path, resolution=10, stats=stats, 
                # numeric_field="confidence",
                # category="category",
                output_format="gpd")

Raster to DGGS¶

from vgrid.conversion.raster2dggs.raster2h3 import raster2h3
from vgrid.utils.io import download_file

raster_url = ("https://raw.githubusercontent.com/opengeoshub/vopendata/main/raster/rgb.tif")
raster_file = download_file(raster_url)
raster_to_h3 =  raster2h3(raster_file,output_format="gpd")

DGGS Generator¶

from vgrid.generator.h3grid import h3grid

h3_grid = h3grid(resolution=0, output_format="gpd")

DGGS Inspect¶

from vgrid.stats.a5stats import a5inspect
resolution = 5
a5inspect(resolution)

Distribution of DGGS Area Distortions visualized from DGGS Inspect¶

Visualization of DGGS IPQ Compactness visualized from DGGS Inspect¶

DGGS Stats¶

from vgrid.stats.h3stats import h3stats
h3stats()

Further examples¶

For more examples, see the example notebooks.