polars-h3 0.6.1

H3 bindings for Polars

This is a Polars extension that adds support for the H3 discrete global grid system, so you can index points and geometries to hexagons directly in Polars. All credits goes to the h3o for doing the heavy lifting.

Highlights

• 🚀 Blazing Fast: Built entirely in Rust, offering vectorized, multi-core H3 operations within Polars. Ideal for high-performance data processing.

  • 25X faster than h3-py
  • 5X faster than H3 DuckDB (See notebook for more details)

• 🌍 H3 Feature Parity: Comprehensive support for H3 functions, covering almost everything the standard H3 library provides, excluding geometric functions.

• 📋 Fully Tested & Used in Production: Thoroughly tested against the standard H3 library.

• 🔍 Data Type Agnostic: Supports string and integer H3 indexes natively, eliminating format conversion hassles.

Get started

You can get started by installing it with pip (or uv):

pip install polars-h3

You can use the extension as a drop-in replacement for the standard H3 functions.

import polars_h3 as plh3
import polars as pl

df = (
    pl.DataFrame(
        {
            "lat": [37.7749],
            "long": [-122.4194],
        }
    )
    .with_columns(
        plh3.latlng_to_cell(
            "lat",
            "long",
            resolution=7,
            return_dtype=pl.Utf8,
        ).alias("h3_cell")
    )
)

print(df)

shape: (1, 3)
┌─────────┬───────────┬─────────────────┐
│ lat     ┆ long      ┆ h3_cell         │
│ ---     ┆ ---       ┆ ---             │
│ f64     ┆ f64       ┆ str             │
╞═════════╪═══════════╪═════════════════╡
│ 37.7749 ┆ -122.4194 ┆ 872830828ffffff │
└─────────┴───────────┴─────────────────┘

Check out the quickstart notebook for more examples.

🌟 You can also find the advanced notebooks here.

Implemented functions

This extension implements most of the H3 API. The full list of functions is below - you can find full docs here.

⚠️ Performance Note: When possible, prefer using pl.UInt64 for H3 indices instead of the pl.Utf8 representation. String representations require casting operations which impact performance. Working directly with the native 64-bit integer format provides better computational efficiency.

We are unable to support the functions that work with geometries.

Full list of functions

✅ = Supported 🚧 = Pending 🛑 = Not supported

Function	Description	Supported
latlng_to_cell	Convert latitude/longitude coordinate to cell ID	✅
cell_to_lat	Convert cell ID to latitude	✅
cell_to_lng	Convert cell ID to longitude	✅
cell_to_latlng	Convert cell ID to latitude/longitude	✅
get_resolution	Get resolution number of cell ID	✅
str_to_int	Convert pl.Utf8 cell ID to pl.UInt64	✅
int_to_str	Convert pl.UInt64 or pl.Int64 cell ID to pl.Utf8	✅
is_valid_cell	True if this is a valid cell ID	✅
is_res_class_iii	True if the cell's resolution is class III	✅
is_pentagon	True if the cell is a pentagon	✅
get_icosahedron_faces	List of icosahedron face IDs the cell is on	✅
cell_to_parent	Get coarser cell for a cell	✅
cell_to_children	Get finer cells for a cell	✅
cell_to_center_child	Provides the center child (finer) cell contained by cell at resolution childRes.	✅
cell_to_child_pos	Position of the child cell within the ordered list of all children of its parent at the specified resolution	✅
child_pos_to_cell	Child cell at a given position within the ordered list of children for a specified parent/resolution	✅
compact_cells	Compacts a collection of H3 cells (all same resolution) by replacing child cells with their parent if all children exist	✅
uncompact_cells	Uncompacts a set of H3 cells to the resolution res	✅
grid_ring	Produces the "hollow ring" of cells which are exactly grid distance k from the origin cell	✅
grid_disk	Produces the "filled-in disk" of cells at most grid distance k from the origin cell	✅
grid_path_cells	Find a grid path to connect two cells	✅
grid_distance	Find the grid distance between two cells	✅
cell_to_local_ij	Convert a cell ID to a local I,J coordinate space	✅
local_ij_to_cell	Convert a local I,J coordinate to a cell ID	✅
cell_to_boundary	Convert cell ID to its boundary lat/lng coordinates	✅
cell_to_vertex	Get the vertex ID for a cell ID and vertex number	✅
cell_to_vertexes	Get all vertex IDs for a cell ID (5 for pentagon, 6 for hex)	✅
vertex_to_latlng	Convert a vertex ID to latitude/longitude coordinates	✅
is_valid_vertex	True if passed a valid vertex ID	✅
is_valid_directed_edge	True if passed a valid directed edge ID	✅
origin_to_directed_edges	Get all directed edge IDs for a cell ID	✅
directed_edge_to_cells	Convert a directed edge ID to origin/destination cell IDs	✅
get_directed_edge_origin	Convert a directed edge ID to origin cell ID	✅
get_directed_edge_destination	Convert a directed edge ID to destination cell ID	✅
cells_to_directed_edge	Convert an origin/destination pair to directed edge ID	✅
are_neighbor_cells	True if the two cell IDs share an edge	✅
average_hexagon_area	Get average area of a hexagon cell at resolution	✅
cell_area	Get the area of a cell ID	✅
average_hexagon_edge_length	Average hexagon edge length at resolution	✅
edge_length	Get the length of a directed edge ID	✅
get_num_cells	Get the number of cells at a resolution	✅
get_pentagons	Get all pentagons at a resolution	✅
great_circle_distance	Compute the great circle distance between two points (haversine)	✅
cells_to_multi_polygon_wkt	Convert a set of cells to multipolygon WKT	🛑
polygon_wkt_to_cells	Convert polygon WKT to a set of cells	🛑
directed_edge_to_boundary_wkt	Convert directed edge ID to linestring WKT	🛑

Plotting

The library also comes with helper functions to plot hexes on a Folium map.

import polars_h3 as plh3
import polars as pl

hex_map = plh3.graphing.plot_hex_outlines(df, "h3_cell")
display(hex_map)

# or if you have a metric to plot

hex_map = plh3.graphing.plot_hex_fills(df, "h3_cell", "metric_col")
display(hex_map)

Development

It's recommended to use uv to manage the extension's python dependencies. If you modify rust code, you will need to run uv run maturin develop --uv to see changes.

You can run test suite with uv run pytest. You can also run the docs locally with uv run mkdocs serve.

Benchmarking

If you're looking to benchmark the performance of the extension, build the release version with maturin develop --release --uv and then run uv run -m benchmarks.engine (assuming you have the benchmark dependencies installed). Benchmarking with the development version will lead to misleading results.

# 1 – (build) compile the optimized Rust extension
uv run maturin develop --release --uv

# 2 – (run) execute the benchmark CLI
uv run h3-bench \
  --libraries plh3 duckdb h3_py \   # which back-ends to test (or “all”)
  --functions latlng_to_cell cell_to_parent \  # which functions to time (or “all”)
  --iterations 3 \                  # repetitions per test
  --fast-factor 4 \                 # divide default row-counts to speed things up
  --output results.json             # optional: dump raw results