Vgrid DGGS key features¶

You can try out Vgrid DGGS by using the cloud-computing platforms below without having to install anything on your computer. 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.

Install vgrid¶

Uncomment the following line to install vgrid.

In [1]:

# %pip install vgrid --upgrade

# %pip install vgrid --upgrade

DGGS Conversion¶

latlon2dggs¶

In [2]:

from vgrid.conversion.latlon2dggs import latlon2h3

lat = 10.775276
lon = 106.706797
res = 10
h3_id = latlon2h3(lat, lon, res)
h3_id

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

Out[2]:

'8a65b56628e7fff'

DGGS to Shapely Polygon¶

In [3]:

from vgrid.conversion.dggs2geo.h32geo import h32geo
h3_geo = h32geo([h3_id])
h3_geo

from vgrid.conversion.dggs2geo.h32geo import h32geo h3_geo = h32geo([h3_id]) h3_geo

Out[3]:

DGGS to GeoJSON¶

In [4]:

from vgrid.conversion.dggs2geo.h32geo import h32geojson

h3_geojson = h32geojson(h3_id)
h3_geojson

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

Out[4]:

{'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': '8a65b56628e7fff',
    'center_lat': 10.7754157,
    'center_lon': 106.7065382,
    'avg_edge_len': 81.374,
    'cell_area': 17202.984,
    'cell_perimeter': 488.243}}]}

Vector to DGGS¶

In [5]:

from vgrid.conversion.vector2dggs.vector2rhealpix import vector2rhealpix

# Read GeoJSON from URL
file_path = (
    "https://raw.githubusercontent.com/opengeoshub/vopendata/main/shape/polygon.geojson"
)
vector_to_rhealpix = vector2rhealpix(file_path, resolution=10, compact=False, output_format="gpd")
vector_to_rhealpix.plot(edgecolor="white")

from vgrid.conversion.vector2dggs.vector2rhealpix import vector2rhealpix # Read GeoJSON from URL file_path = ( "https://raw.githubusercontent.com/opengeoshub/vopendata/main/shape/polygon.geojson" ) vector_to_rhealpix = vector2rhealpix(file_path, resolution=10, compact=False, output_format="gpd") vector_to_rhealpix.plot(edgecolor="white")

Processing features: 100%|██████████| 4/4 [00:01<00:00,  3.56it/s]

Out[5]:

<Axes: >

DGGS Compact¶

In [6]:

from vgrid.conversion.dggscompact import rhealpixcompact
rhealpix_compacted = rhealpixcompact(vector_to_rhealpix, rhealpix_id="rhealpix", output_format="gpd")
rhealpix_compacted.plot(edgecolor="white")

from vgrid.conversion.dggscompact import rhealpixcompact rhealpix_compacted = rhealpixcompact(vector_to_rhealpix, rhealpix_id="rhealpix", output_format="gpd") rhealpix_compacted.plot(edgecolor="white")

Out[6]:

<Axes: >

DGGS Expand¶

In [7]:

from vgrid.conversion.dggscompact import rhealpixexpand
rhealpix_expanded = rhealpixexpand(vector_to_rhealpix, resolution=11, 
                                rhealpix_id="rhealpix", output_format="gpd")
rhealpix_expanded.plot(edgecolor="white")

from vgrid.conversion.dggscompact import rhealpixexpand rhealpix_expanded = rhealpixexpand(vector_to_rhealpix, resolution=11, rhealpix_id="rhealpix", output_format="gpd") rhealpix_expanded.plot(edgecolor="white")

Out[7]:

<Axes: >

DGGS Binning¶

In [8]:

from vgrid.binning.s2bin import s2bin
file_path = (
    "https://raw.githubusercontent.com/opengeoshub/vopendata/main/csv/dist1_pois.csv"
)
stats = "count"
s2_bin = s2bin(file_path, resolution=16, stats=stats, output_format="gpd")
s2_bin.plot(
    column=stats,        # numeric column to base the colors on
    cmap='Spectral_r',        # color scheme (matplotlib colormap)
    legend=True,  
    linewidth=0.2          # boundary width (optional)
)

from vgrid.binning.s2bin import s2bin file_path = ( "https://raw.githubusercontent.com/opengeoshub/vopendata/main/csv/dist1_pois.csv" ) stats = "count" s2_bin = s2bin(file_path, resolution=16, stats=stats, output_format="gpd") s2_bin.plot( column=stats, # numeric column to base the colors on cmap='Spectral_r', # color scheme (matplotlib colormap) legend=True, linewidth=0.2 # boundary width (optional) )

Generating S2 DGGS: 100%|██████████| 737/737 [00:01<00:00, 658.85 cells/s]

Out[8]:

<Axes: >

Raster to DGGS¶

In [9]:

# %pip install folium

# %pip install folium

In [10]:

from vgrid.conversion.raster2dggs.raster2tilecode import raster2tilecode
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_tilecode = raster2tilecode(raster_file, output_format="gpd")

# Visualize the output
import folium

m = folium.Map(tiles="CartoDB positron", max_zoom=28)

tilecode_layer = folium.GeoJson(
    raster_to_tilecode,
    style_function=lambda x: {
        "fillColor": f"rgb({x['properties']['band_1']}, {x['properties']['band_2']}, {x['properties']['band_3']})",
        "fillOpacity": 1,
        "color": "black",
        "weight": 1,
    },
    popup=folium.GeoJsonPopup(
        fields=["tilecode", "band_1", "band_2", "band_3"],
        aliases=["Tilecode ID", "Band 1", "Band 2", "Band 3"],
        style="""
            background-color: white;
            border: 2px solid black;
            border-radius: 3px;
            box-shadow: 3px;
        """,
    ),
).add_to(m)

m.fit_bounds(tilecode_layer.get_bounds())

# Display the map
m

from vgrid.conversion.raster2dggs.raster2tilecode import raster2tilecode 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_tilecode = raster2tilecode(raster_file, output_format="gpd") # Visualize the output import folium m = folium.Map(tiles="CartoDB positron", max_zoom=28) tilecode_layer = folium.GeoJson( raster_to_tilecode, style_function=lambda x: { "fillColor": f"rgb({x['properties']['band_1']}, {x['properties']['band_2']}, {x['properties']['band_3']})", "fillOpacity": 1, "color": "black", "weight": 1, }, popup=folium.GeoJsonPopup( fields=["tilecode", "band_1", "band_2", "band_3"], aliases=["Tilecode ID", "Band 1", "Band 2", "Band 3"], style=""" background-color: white; border: 2px solid black; border-radius: 3px; box-shadow: 3px; """, ), ).add_to(m) m.fit_bounds(tilecode_layer.get_bounds()) # Display the map m

WARNING [rasterio._env:368  open()] CPLE_AppDefined in PROJ: proj_create_from_database: Cannot find proj.db
WARNING [rasterio._env:368  open()] CPLE_AppDefined in PROJ: proj_create_from_database: Cannot find proj.db

rgb.tif already exists. Skip downloading. Set overwrite=True to overwrite.
Nearest tilecode resolution determined: 26

Resampling: 100%|██████████| 8925/8925 [00:00<00:00, 48197.48 cells/s]
Converting raster to Tilecode: 100%|██████████| 8806/8806 [00:01<00:00, 6961.13 cells/s] 

Out[10]:

Make this Notebook Trusted to load map: File -> Trust Notebook

DGGS Generator¶

In [11]:

from vgrid.generator.h3grid import h3grid

h3_grid = h3grid(resolution=0,output_format="gpd")
h3_grid.plot(edgecolor='white')

from vgrid.generator.h3grid import h3grid h3_grid = h3grid(resolution=0,output_format="gpd") h3_grid.plot(edgecolor='white')

Generating H3 DGGS: 100%|██████████| 122/122 [00:00<00:00, 368.15 cells/s]

Out[11]:

<Axes: >

DGGS Inspect¶

In [12]:

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

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

Generating A5 DGGS: 100%|██████████| 41472/41472 [01:05<00:00, 631.03 cells/s]

Out[12]:

	a5	resolution	center_lat	center_lon	avg_edge_len	cell_area	cell_perimeter	geometry	crossed	norm_area	ipq	zsc
0	c402000000000000	5	-88.778429	143.247090	146990.185	3.311882e+10	734950.924	POLYGON ((267 -90, 168.65049 -89.33266, 168.65...	True	0.997333	0.770492	0.877748
1	c406000000000000	5	-87.450371	171.582970	148114.039	3.318690e+10	740570.194	POLYGON ((159 -86.10242, 157.01838 -86.76115, ...	True	0.999383	0.760403	0.871983
2	c412000000000000	5	-86.388526	-169.620901	148227.201	3.317992e+10	741136.006	POLYGON ((-181.58039 -86.57893, -174.9477 -87....	True	0.999172	0.759083	0.871225
3	c44a000000000000	5	-84.470901	-177.258397	150415.196	3.323008e+10	752075.979	POLYGON ((-165 -85.42943, -168.30096 -84.80452...	True	1.000683	0.738274	0.859201
4	c446000000000000	5	-82.927396	-173.663764	149871.712	3.319273e+10	749358.559	POLYGON ((-181.52273 -81.83357, -180.65159 -82...	True	0.999558	0.742803	0.861832

Distribution of DGGS Area Distortions¶

In [13]:

from vgrid.stats.a5stats import a5_norm_area
a5_norm_area(a5_inspect)

from vgrid.stats.a5stats import a5_norm_area a5_norm_area(a5_inspect)

Distribution of DGGS IPQ Compactness¶

In [14]:

from vgrid.stats.a5stats import a5_compactness
a5_compactness(a5_inspect)

from vgrid.stats.a5stats import a5_compactness a5_compactness(a5_inspect)

DGGS Statistics¶

In [15]:

from vgrid.stats.h3stats import h3stats
h3stats('km')

from vgrid.stats.h3stats import h3stats h3stats('km')

Out[15]:

	resolution	number_of_cells	avg_edge_len_km	avg_area_km2	min_area_km2	max_area_km2	max_min_ratio
0	0	122	1107.712591	4.357449e+06	2.562182e+06	4.977807e+06	1.942800
1	1	842	418.676005	6.097884e+05	3.284346e+05	7.294869e+05	2.221102
2	2	5882	158.244656	8.680178e+04	4.493090e+04	1.045998e+05	2.328015
3	3	41162	59.810858	1.239343e+04	6.315472e+03	1.495077e+04	2.367325
4	4	288122	22.606379	1.770348e+03	8.965824e+02	2.135987e+03	2.382366
5	5	2016842	8.544408	2.529039e+02	1.277856e+02	3.051443e+02	2.387940
6	6	14117882	3.229483	3.612906e+01	1.823875e+01	4.359211e+01	2.390082
7	7	98825162	1.220630	5.161293e+00	2.604669e+00	6.227446e+00	2.390878
8	8	691776122	0.461355	7.373276e-01	3.720480e-01	8.896352e-01	2.391184
9	9	4842432842	0.174376	1.053325e-01	5.314719e-02	1.270907e-01	2.391297
10	10	33897029882	0.065908	1.504750e-02	7.592318e-03	1.815582e-02	2.391341
11	11	237279209162	0.024911	2.149643e-03	1.084609e-03	2.593689e-03	2.391357
12	12	1660954464122	0.009416	3.070919e-04	1.549438e-04	3.705269e-04	2.391363
13	13	11626681248842	0.003560	4.387027e-05	2.213481e-05	5.293242e-05	2.391366
14	14	81386768741882	0.001349	6.267181e-06	3.162114e-06	7.561774e-06	2.391367
15	15	569707381193162	0.000510	8.953116e-07	4.517305e-07	1.080253e-06	2.391367

Polyhedra Generator¶

Tetrahedron¶

In [16]:

from vgrid.generator.polyhedra import tetrahedron

tetrahedron_gdf = tetrahedron()
tetrahedron_gdf.plot(edgecolor="white")

from vgrid.generator.polyhedra import tetrahedron tetrahedron_gdf = tetrahedron() tetrahedron_gdf.plot(edgecolor="white")

Out[16]:

<Axes: >

Cube¶

In [17]:

from vgrid.generator.polyhedra import cube

cube_gdf = cube()
tetrahedron_gdf.plot(edgecolor="white")

from vgrid.generator.polyhedra import cube cube_gdf = cube() tetrahedron_gdf.plot(edgecolor="white")

Out[17]:

<Axes: >

Octahedron¶

In [18]:

from vgrid.generator.polyhedra import octahedron

octa_gdf = octahedron()
octa_gdf.plot(edgecolor="white")

from vgrid.generator.polyhedra import octahedron octa_gdf = octahedron() octa_gdf.plot(edgecolor="white")

Out[18]:

<Axes: >

Fuller Icosahedron¶

In [19]:

from vgrid.generator.polyhedra import fuller_icosahedron            

fuller_icosahedron_gdf = fuller_icosahedron() 
fuller_icosahedron_gdf.plot()

from vgrid.generator.polyhedra import fuller_icosahedron fuller_icosahedron_gdf = fuller_icosahedron() fuller_icosahedron_gdf.plot()

Out[19]:

<Axes: >

Rhombic Icosahedron¶

In [20]:

from vgrid.generator.polyhedra import rhombic_icosahedron               

rhombic_icosahedron_gdf = rhombic_icosahedron() 
rhombic_icosahedron_gdf.plot()

from vgrid.generator.polyhedra import rhombic_icosahedron rhombic_icosahedron_gdf = rhombic_icosahedron() rhombic_icosahedron_gdf.plot()

Out[20]:

<Axes: >

Hexagon¶

In [21]:

from vgrid.generator.polyhedra import hexagon        

hexagon_gdf = hexagon(level=1) 
hexagon_gdf.plot(edgecolor="white")

from vgrid.generator.polyhedra import hexagon hexagon_gdf = hexagon(level=1) hexagon_gdf.plot(edgecolor="white")

Out[21]:

<Axes: >