Skip to content

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, 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.

logo

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.

image image image image PyPI version image image

Installation

pip

image 

1
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

1
2
3
4
5
6
7
8
>>> 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

1
2
3
4
5
6
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

1
2
3
4
5
>>> 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

1
2
3
4
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

1
2
3
from vgrid.conversion.dggscompact.isea4tcompact import isea4tcompact

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

DGGS Expand

1
2
3
from vgrid.conversion.dggscompact.isea4tcompact import isea4texpand

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

DGGS Binning

1
2
3
4
5
6
7
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

1
2
3
4
5
6
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

1
2
3
from vgrid.generator.h3grid import h3grid

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

DGGS Inspect

1
2
from vgrid.stats.a5stats import a5inspect
a5inspect()

Distribution of DGGS Area Distortions visualized from DGGS Inspect

Visualization of DGGS IPQ Compactness visualized from DGGS Inspect

DGGS Stats

1
2
from vgrid.stats.h3stats import h3stats
h3stats()

Further examples

For more examples, see the example notebooks.