Converting vector data

from matplotlib import pyplot
from pathlib import Path
import os

# increase the plot size
pyplot.rcParams['figure.dpi'] = 120

project_root = Path(os.environ["PROJECT_ROOT"])

import geopandas as gpd

world = gpd.read_file(project_root / "data/naturalearth_110m_admin_0_countries.fgb")
africa = world[world["CONTINENT"] == "Africa"]
africa.plot(column="NAME_EN")

<Axes: >

Converting a complete GeoDataFrame to cells

Includes building a new GeoDataFrame with the cell geometries using h3ronpy.pandas.vector.geodataframe_to_cells():

from h3ronpy.pandas.vector import geodataframe_to_cells, cells_dataframe_to_geodataframe
from h3ronpy import ContainmentMode

df = geodataframe_to_cells(africa, 3)
gdf = cells_dataframe_to_geodataframe(df)
gdf.plot(column="NAME_EN")

<Axes: >

Polygon fill modes

Polygon to H3 conversion is based on centroid containment. Depending on the shape of the geometry the resulting cells may look like below:

namibia = africa[africa["NAME_EN"] == "Namibia"]

def fill_namibia(**kw):
    cell_ax = cells_dataframe_to_geodataframe(geodataframe_to_cells(namibia, 3, **kw)).plot()
    return namibia.plot(ax=cell_ax, facecolor=(0,0,0,0), edgecolor='black')

fill_namibia()

<Axes: >

The containment_mode argument allow the control how polygons are filled. See h3ronpy.ContainmentMode for details.

fill_namibia(containment_mode=ContainmentMode.ContainsCentroid)

<Axes: >

fill_namibia(containment_mode=ContainmentMode.ContainsBoundary)

<Axes: >

fill_namibia(containment_mode=ContainmentMode.IntersectsBoundary)

<Axes: >

fill_namibia(containment_mode=ContainmentMode.Covers)

<Axes: >

Merging cells into larger polygons

from h3ronpy.pandas.vector import cells_to_polygons, geoseries_to_cells

gpd.GeoDataFrame({
    "geometry": cells_to_polygons(geoseries_to_cells(namibia.geometry, 3, flatten=True), link_cells=True)
}).plot()

<Axes: >

Single geometries

It is also possible to convert single shapely geometries or any other type providing the python __geo_interface__:

from h3ronpy.vector import geometry_to_cells

namibia_geom = namibia["geometry"].iloc[0]
print(namibia_geom)
geometry_to_cells(namibia_geom, 3)

MULTIPOLYGON (((19.895767856534434 -24.76779021576059, 19.894734327888614 -28.461104831660776, 19.002127312911085 -28.972443129188868, 18.464899122804752 -29.04546192801728, 17.83615197110953 -28.85637786226132, 17.387497185951503 -28.78351409272978, 17.218928663815404 -28.35594329194681, 16.824017368240902 -28.08216155366447, 16.344976840895242 -28.5767050106977, 15.601818068105816 -27.821247247022804, 15.21047244635946 -27.090955905874047, 14.989710727608553 -26.117371921495156, 14.743214145576331 -25.39292001719538, 14.408144158595833 -23.853014011329847, 14.385716586981149 -22.65665292734069, 14.257714064194175 -22.111208184499958, 13.86864220546866 -21.699036960539978, 13.35249799973744 -20.872834161057504, 12.826845330464494 -19.673165785401665, 12.608564080463621 -19.0453488094877, 11.794918654028066 -18.069129327061916, 11.734198846085121 -17.301889336824473, 12.215461460019355 -17.111668389558083, 12.814081251688407 -16.94134286872407, 13.462362094789967 -16.971211846588773, 14.05850141770901 -17.423380629142663, 14.209706658595024 -17.35310068122572, 18.263309360434164 -17.309950860262006, 18.956186964603603 -17.789094740472258, 21.377176141045567 -17.930636488519696, 23.215048455506064 -17.523116143465984, 24.033861525170778 -17.295843194246324, 24.682349074001507 -17.353410739819473, 25.07695031098226 -17.57882333747662, 25.08444339366457 -17.661815687737374, 24.520705193792537 -17.887124932529936, 24.217364536239213 -17.88934701911849, 23.579005568137717 -18.28126108162006, 23.1968583513393 -17.869038181227786, 21.655040317478978 -18.219146010005225, 20.910641310314535 -18.252218926672022, 20.88113406747587 -21.814327080983148, 19.89545779794068 -21.84915699634787, 19.895767856534434 -24.76779021576059)))

arro3.core.Array<UInt64>
[
  592633056519520255,
  592633125238996991,
  592633331397427199,
  592635255542775807,
  592998987733139455,
  593006271997673471,
  593006340717150207,
  593006409436626943,
  593006478156103679,
  593006546875580415,
]