Vgrid

<!-- PROJECT LOGO --> <p align="center"> <strong >Vgrid </strong> <br> <b><i> A unified framework for working with DGGS</i><b> </p> <p align="center"> <img src="https://raw.githubusercontent.com/opengeoshub/vgridtools/main/images/readme/dggs.png"> </p> <!-- TABLE OF CONTENTS --> <details open="open"> <summary>Vgrid User Guide</summary> <ol> <li> <a href="#vgrid-introduction">Vgrid Introduction</a> </li> <li> <a href="#vgrid-installation">Vgrid Installation</a> </li> <li> <a href="#dggs-conversion">DGGS Conversion</a> <ul> <li><a href="#lat-lon-to-dggs">Lat lon to DGGS</a></li> <li><a href="#dggs-to-geojson">DGGS to GeoJSON</a></li> <li><a href="#vector-to-dggs">Vector to DGGS</a></li> <li><a href="#dggs-compact">DGGS Compact</a></li> <li><a href="#dggs-expand">DGGS Expand</a></li> <li><a href="#raster-to-dggs">Raster to DGGS</a></li> </ul> <li><a href="#dggs-binning">DGGS Binning</a></li> <li><a href="#dggs-generator">DGGS Generator</a></li> <li><a href="#dggs-stats">DGGS Stats</a></li> <li><a href="#dggs-inspect">DGGS Inspect</a></li> <li><a href="#polyhedra-generator">Polyhedra Generator</a></li> </li> </ol> </details>

Vgrid Introduction

Vgrid DGGS is 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.

The following Vgrid user guide is intended for use in a Command Line Interface (CLI) environment. Full Vgrid DGGS documentation is available at vgrid document.

To work with Vgrid DGGS directly in GeoPandas and Pandas, please use vgridpandas. 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.

Vgrid Installation

• Using pip:

  pip install vgrid --upgrade
  

DGGS Conversion

Lat lon to DGGS

Convert lat, long in WGS84 CRS to DGGS cellID (H3, S2, A5, rHEALPix, OpenEaggr ISEA4T and ISEA3H, EASE-DGGS, QTM, OLC/ OpenLocationCode/ Google Plus Code, Geohash, GEOREF, MGRS, Tilecode, Quadkey, Maidenhead, GARS).

> latlon2h3 10.775276 106.706797 13 # latlon2h3 <lat> <lon> <resolution> [0..15] 
> latlon2s2 10.775276 106.706797 21 # latlon2s2 <lat> <lon> <resolution> [0..30]
> latlon2a5 10.775276 106.706797 18 # latlon2a5 <lat> <lon> <resolution> [0..29]
> latlon2rhealpix 10.775276 106.706797 14 # latlon2rhealpix <lat> <lon> <resolution> [1..15]
> latlon2isea4t 10.775276 106.706797 21 # latlon2isea4t <lat> <lon> <resolution> [0..39]
> latlon2isea3h 10.775276 106.706797 27 # latlon2isea3h <lat> <lon> <resolution> [0..40]
> latlon2ease 10.775276 106.706797 6 # latlon2ease <lat> <lon> <resolution> [0..6]
> latlon2dggrid 10.775276 106.706797 FULLER4D 10 # Linux only: latlon2dggrid <lat> <lon> <dggs_type> <resolution> 
> latlon2qtm 10.775276 106.706797 11  # latlon2qtm <lat> <lon> <resolution> [1..24]
> latlon2olc 10.775276 106.706797 11 # latlon2olc <lat> <lon> <resolution> [2,4,6,8,10,11..15]
> latlon2geohash 10.775276 106.706797 9 # latlon2geohash <lat> <lon> <resolution>[1..10]
> latlon2georef 10.775276 106.706797 4 # latlon2georef <lat> <lon> <resolution> [0..10]
> latlon2mgrs 10.775276 106.706797 4 # latlon2mgrs <lat> <lon> <resolution> [0..5]
> latlon2tilecode 10.775276 106.706797 23 # latlon2tilecode <lat> <lon> <resolution> [0..29]
> latlon2quadkey 10.775276 106.706797 23 # latlon2quadkey <lat> <lon> <resolution> [0..29]
> latlon2maidenhead 10.775276 106.706797 4 # latlon2maidenhead <lat> <lon> <resolution> [1..4]
> latlon2gars 10.775276 106.706797 1 # latlon2gars <lat> <lon> <resolution> [1..4] (30,15,5,1 minutes)

<div align="center"> <img src="https://raw.githubusercontent.com/thangqd/vgridtools/main/images/readme/latlon2dggs.png"> </div>

DGGS to GeoJSON

Convert DGGS cell IDs to GeoJSON.

> h32geojson 8d65b56628e46bf 
> s22geojson 31752f45cc94 
> a52geojson 8e65b56628e0d07
> rhealpix2geojson R31260335553825
> isea4t2geojson 13102313331320133331133 
> isea3h2geojson 1327916769,-55086 
> ease2geojson L6.165767.02.02.22.45.63.05
> dggrid2geojson 8478420 FULLER4D 10 # Linux only:  dggrid2geojson <DGGRID code in SEQNUM format> <DGGS Type> <resolution>
# <DGGS Type> chosen from [SUPERFUND,PLANETRISK,ISEA3H,ISEA4H,ISEA4T,ISEA4D,ISEA43H,ISEA7H,IGEO7,FULLER3H,FULLER4H,FULLER4T,FULLER4D,FULLER43H,FULLER7H]
> qtm2geojson 42012323131
> olc2geojson 7P28QPG4+4P7
> geohash2geojson w3gvk1td8
> mgrs2geojson 34TGK56063228
> gzd # Create Grid Zone Designators - used by MGRS
> tilecode2geojson z23x6680749y3941729
> quadkey2geojson 13223011131020212310000
> maidenhead2geojson OK30is46 
> gars2geojson 574JK1918

{"type": "FeatureCollection", "features": [{"type": "Feature", "geometry": {"type": "Polygon", "coordinates": [[[106.70789209957029, 10.77601109480422], [106.70745212203926, 10.777918172217145], [106.7055792173179, 10.778494886227104], [106.70414629547702, 10.777164500398262], [106.70458630070586, 10.775257408234628], [106.70645920007833, 10.774680716650128], [106.70789209957029, 10.77601109480422]]]}, "properties": {"h3": "8965b56628fffff", "resolution": 9, "center_lat": 10.7765878, "center_lon": 106.7060192, "avg_edge_len": 215.295, "cell_area": 120421.396}}]}

Vector to DGGS

Convert Vector layers (Point/ Multipoint, Linestring/ Multilinestring, polygon/ Multipolygon) in GeoJSON to DGGS.

> geojson2h3 -r 11 -geojson polygon.geojson # geojson2h3 -r <resolution>[0..15] -geojson <GeoJSON file> -compact [optional]
> geojson2s2 -r 18 -geojson polygon.geojson -compact # geojson2s2 -r <resolution>[0..30] -geojson <GeoJSON file> -compact [optional]
> geojson2a5 -r 18 -geojson polygon.geojson -compact # geojson2a5 -r <resolution>[0..29] -geojson <GeoJSON file> -compact [optional]
> geojson2rhealpix -r 11 -geojson polygon.geojson # geojson2rhealpix -r <resolution>[1..15] -geojson <GeoJSON file> -compact [optional]
> geojson2isea4t -r 17 -geojson p