Directed edges allow encoding the directed (that is, which cell is the origin and which is the destination can be determined) edge from one cell to a neighboring cell.
are_neighbor_cells¶Determine whether two H3 cells are neighbors.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).pl.UInt64, pl.Int64, or pl.Utf8).Returns
true if the cells share an edge, false otherwise.Examples
>>> df = pl.DataFrame({
+... "cell1": [599686042433355775],
+... "cell2": [599686030622195711],
+... })
+>>> df.with_columns(neighbors=plh3.are_neighbor_cells("cell1", "cell2"))
+shape: (1, 3)
+┌─────────────────────┬─────────────────────┬───────────┐
+│ cell1 │ cell2 │ neighbors │
+│ --- │ --- │ --- │
+│ u64 │ u64 │ bool │
+╞═════════════════════╪═════════════════════╪═══════════╡
+│ 599686042433355775 │ 599686030622195711 │ true │
+└─────────────────────┴─────────────────────┴───────────┘
+Errors
ComputeError: If invalid or null indices are provided.cells_to_directed_edge¶Create a directed H3 edge from two neighboring cells.
plh3.cells_to_directed_edge(
+ origin: IntoExprColumn,
+ destination: IntoExprColumn
+) -> pl.Expr
+Parameters
Returns
Examples
>>> df = pl.DataFrame({
+... "origin": [599686042433355775],
+... "destination": [599686030622195711],
+... })
+>>> df.with_columns(edge=plh3.cells_to_directed_edge("origin", "destination"))
+shape: (1, 3)
+┌─────────────────────┬─────────────────────┬─────────────────────┐
+│ origin │ destination │ edge │
+│ --- │ --- │ --- │
+│ u64 │ u64 │ u64 │
+╞═════════════════════╪═════════════════════╪═════════════════════╡
+│ 599686042433355775 │ 599686030622195711 │ 1608492358964346879 │
+└─────────────────────┴─────────────────────┴─────────────────────┘
+Errors
ComputeError: If the cells are not neighbors or invalid.is_valid_directed_edge¶Check if an H3 index is a valid directed edge.
Parameters
Returns
true if edge is a valid directed edge, false otherwise.Examples
>>> df = pl.DataFrame({"edge": ["115283473fffffff"]})
+>>> df.with_columns(valid=plh3.is_valid_directed_edge("edge"))
+shape: (1, 2)
+┌───────────────────────┬──────────┐
+│ edge │ valid │
+│ --- │ --- │
+│ str │ bool │
+╞═══════════════════════╪══════════╡
+│ 115283473fffffff │ true │
+└───────────────────────┴──────────┘
+Errors
ComputeError: If the input is invalid or null.get_directed_edge_origin¶Extract the origin cell from a directed H3 edge.
Parameters
Returns
pl.UInt64 or pl.Utf8).Examples
>>> df = pl.DataFrame({"edge": [1608492358964346879]})
+>>> df.with_columns(origin=plh3.get_directed_edge_origin("edge"))
+shape: (1, 2)
+┌─────────────────────┬─────────────────────┐
+│ edge │ origin │
+│ --- │ --- │
+│ u64 │ u64 │
+╞═════════════════════╪═════════════════════╡
+│ 1608492358964346879 │ 599686042433355775 │
+└─────────────────────┴─────────────────────┘
+Errors
ComputeError: If edge is invalid or null.get_directed_edge_destination¶Extract the destination cell from a directed H3 edge.
Parameters
Returns
pl.UInt64 or pl.Utf8).Examples
>>> df = pl.DataFrame({"edge": [1608492358964346879]})
+>>> df.with_columns(destination=plh3.get_directed_edge_destination("edge"))
+shape: (1, 2)
+┌─────────────────────┬─────────────────────┐
+│ edge │ destination │
+│ --- │ --- │
+│ u64 │ u64 │
+╞═════════════════════╪═════════════════════╡
+│ 1608492358964346879 │ 599686030622195711 │
+└─────────────────────┴─────────────────────┘
+Errors
ComputeError: If edge is invalid or null.directed_edge_to_cells¶Retrieve the origin-destination cell pair from a directed edge.
Parameters
Returns
[origin, destination] as [pl.UInt64, pl.UInt64] (or [pl.Utf8, pl.Utf8]).Examples
>>> df = pl.DataFrame({"edge": [1608492358964346879]})
+>>> df.with_columns(cells=plh3.directed_edge_to_cells("edge"))
+shape: (1, 2)
+┌─────────────────────┬─────────────────────┐
+│ edge │ cells │
+│ --- │ --- │
+│ u64 │ list[u64] │
+╞═════════════════════╪═════════════════════╡
+│ 1608492358964346879 │ [599686042433355775,… │
+└─────────────────────┴─────────────────────┘
+Errors
ComputeError: If edge is invalid or null.origin_to_directed_edges¶List all directed edges originating from a given cell.
Parameters
Returns
pl.UInt64 or pl.Utf8).Examples
>>> df = pl.DataFrame({"h3_cell": [599686042433355775]})
+>>> df.with_columns(edges=plh3.origin_to_directed_edges("h3_cell"))
+shape: (1, 2)
+┌─────────────────────┬─────────────────────────────────┐
+│ h3_cell │ edges │
+│ --- │ --- │
+│ u64 │ list[u64] │
+╞═════════════════════╪═════════════════════════════════╡
+│ 599686042433355775 │ [1608492358964346879,…] │
+└─────────────────────┴─────────────────────────────────┘
+Errors
ComputeError: If cell is invalid or null.directed_edge_to_boundary¶Retrieve the geographic boundary (list of lat/lng pairs) defining a directed edge.
Parameters
Returns
[lat, lng] pairs, each itself a two-element list.Examples
>>> df = pl.DataFrame({"edge": [1608492358964346879]})
+>>> df.with_columns(boundary=plh3.directed_edge_to_boundary("edge"))
+shape: (1, 2)
+┌─────────────────────┬───────────────────────────────┐
+│ edge │ boundary │
+│ --- │ --- │
+│ u64 │ list[list[f64]] │
+╞═════════════════════╪═══════════════════════════════╡
+│ 1608492358964346879 │ [[37.3457, -121.9763], … ] │
+└─────────────────────┴───────────────────────────────┘
+Errors
ComputeError: If edge is invalid, null, or its boundary cannot be computed.These functions are used for finding the H3 cell index containing coordinates, and for finding the center and boundary of H3 cells.
latlng_to_cell¶Convert latitude/longitude coordinates to H3 cell indices.
plh3.latlng_to_cell(
+ lat: IntoExprColumn,
+ lng: IntoExprColumn,
+ resolution: HexResolution,
+ return_dtype: type[pl.Utf8] | type[pl.UInt64] | type[pl.Int64] = pl.UInt64
+) -> pl.Expr
+Parameters
pl.Float64).pl.Float64).[0, 15]pl.UInt64 | pl.Int64 | pl.Utf8pl.UInt64).Returns
Examples
>>> df = pl.DataFrame({
+... "lat": [37.7752702151959],
+... "lng": [-122.418307270836]
+... })
+>>> df.with_columns(
+... h3_cell=plh3.latlng_to_cell("lat", "lng", resolution=9, return_dtype=pl.Utf8)
+... )
+shape: (1, 3)
+┌──────────────────┬────────────────────┬──────────────────┐
+│ lat │ lng │ h3_cell │
+│ --- │ --- │ --- │
+│ f64 │ f64 │ str │
+╞══════════════════╪════════════════════╪══════════════════╡
+│ 37.7752702151959 │ -122.418307270836 │ 8928308280fffff │
+└──────────────────┴────────────────────┴──────────────────┘
+
+>>> # Using integer output
+>>> df.with_columns(
+... h3_cell=plh3.latlng_to_cell("lat", "lng", resolution=1, return_dtype=pl.UInt64)
+... )
+shape: (1, 3)
+┌─────────┬──────────┬─────────────────────┐
+│ lat │ lng │ h3_cell │
+│ --- │ --- │ --- │
+│ f64 │ f64 │ u64 │
+╞═════════╪══════════╪═════════════════════╡
+│ 0.0 │ 0.0 │ 583031433791012863 │
+└─────────┴──────────┴─────────────────────┘
+Errors
ValueError: If the resolution is not in [0, 15].ComputeError: If input coordinates contain null values or are otherwise invalid.cell_to_lat¶Extract the latitude coordinate from H3 cell indices.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
Float64.Examples
>>> df = pl.DataFrame({
+... "h3_cell": ["85283473fffffff"]
+... })
+>>> df.with_columns(
+... lat=plh3.cell_to_lat("h3_cell"),
+... lng=plh3.cell_to_lng("h3_cell")
+... )
+shape: (1, 3)
+┌──────────────────┬─────────────────┬───────────────────┐
+│ h3_cell │ lat │ lng │
+│ --- │ --- │ --- │
+│ str │ f64 │ f64 │
+╞══════════════════╪═════════════════╪═══════════════════╡
+│ 85283473fffffff │ 37.345793375368 │ -121.976375972551 │
+└──────────────────┴─────────────────┴───────────────────┘
+
+>>> # Works with integer representation too
+>>> df = pl.DataFrame({"h3_cell": [599686042433355775]}, schema={"h3_cell": pl.UInt64})
+>>> df.with_columns(
+... lat=plh3.cell_to_lat("h3_cell"),
+... lng=plh3.cell_to_lng("h3_cell")
+... )
+shape: (1, 3)
+┌─────────────────────┬─────────────────┬───────────────────┐
+│ h3_cell │ lat │ lng │
+│ --- │ --- │ --- │
+│ u64 │ f64 │ f64 │
+╞═════════════════════╪═════════════════╪═══════════════════╡
+│ 599686042433355775 │ 37.345793375368 │ -121.976375972551 │
+└─────────────────────┴─────────────────┴───────────────────┘
+cell_to_lng¶Extract the longitude coordinate from H3 cell indices.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
Float64.Examples
>>> df = pl.DataFrame({
+... "h3_cell": ["85283473fffffff"]
+... })
+>>> df.with_columns(
+... lat=plh3.cell_to_lat("h3_cell"),
+... lng=plh3.cell_to_lng("h3_cell")
+... )
+shape: (1, 3)
+┌──────────────────┬─────────────────┬───────────────────┐
+│ h3_cell │ lat │ lng │
+│ --- │ --- │ --- │
+│ str │ f64 │ f64 │
+╞══════════════════╪═════════════════╪═══════════════════╡
+│ 85283473fffffff │ 37.345793375368 │ -121.976375972551 │
+└──────────────────┴─────────────────┴───────────────────┘
+
+>>> # Works with integer representation too
+>>> df = pl.DataFrame({"h3_cell": [599686042433355775]}, schema={"h3_cell": pl.UInt64})
+>>> df.with_columns(
+... lat=plh3.cell_to_lat("h3_cell"),
+... lng=plh3.cell_to_lng("h3_cell")
+... )
+shape: (1, 3)
+┌─────────────────────┬─────────────────┬───────────────────┐
+│ h3_cell │ lat │ lng │
+│ --- │ --- │ --- │
+│ u64 │ f64 │ f64 │
+╞═════════════════════╪═════════════════╪═══════════════════╡
+│ 599686042433355775 │ 37.345793375368 │ -121.976375972551 │
+└─────────────────────┴─────────────────┴───────────────────┘
+cell_to_latlng¶Convert H3 cells into a list of [latitude, longitude].
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
[lat, lng] for each H3 cell.Examples
>>> df = pl.DataFrame({"cell": ["85283473fffffff"]})
+>>> df.select(plh3.cell_to_latlng("cell"))
+shape: (1, 1)
+┌─────────────────────────┐
+│ cell_to_latlng │
+│ --- │
+│ list[f64] │
+╞═════════════════════════╡
+│ [37.3457934, -121.9763…]│
+└─────────────────────────┘
+
+>>> # Easily extract lat/lng as separate columns:
+>>> df.select([
+... plh3.cell_to_latlng("cell").arr.get(0).alias("lat"),
+... plh3.cell_to_latlng("cell").arr.get(1).alias("lng"),
+... ])
+shape: (1, 2)
+┌───────────┬───────────┐
+│ lat │ lng │
+│ --- │ --- │
+│ f64 │ f64 │
+╞═══════════╡═══════════╡
+│ 37.345793…│ -121.9763…│
+└───────────┴───────────┘
+Errors
ComputeError: If null or invalid H3 cell indices are encountered.cell_to_local_ij¶Convert an H3 cell index into its local IJ coordinates relative to a given origin.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
[i, j] of integer coordinates.Examples
>>> df = pl.DataFrame({
+... "origin": [599686042433355775],
+... "cell": [599686042433355776]
+... })
+>>> df.select(plh3.cell_to_local_ij("cell", "origin"))
+shape: (1, 1)
+┌────────────────┐
+│ cell_to_local_ij│
+│ --- │
+│ list[i64] │
+╞════════════════╡
+│ [0,1] │
+└────────────────┘
+Errors
ComputeError: If the inputs are invalid, null, or cannot be transformed.local_ij_to_cell¶Convert local IJ coordinates back into an H3 cell index using a given origin.
plh3.local_ij_to_cell(
+ origin: IntoExprColumn,
+ i: IntoExprColumn,
+ j: IntoExprColumn
+) -> pl.Expr
+Parameters
Returns
Examples
>>> df = pl.DataFrame({
+... "origin": [599686042433355775],
+... "i": [0],
+... "j": [1]
+... })
+>>> df.select(plh3.local_ij_to_cell("origin", "i", "j"))
+shape: (1, 1)
+┌─────────────────┐
+│ local_ij_to_cell│
+│ --- │
+│ u64 │
+╞═════════════════╡
+│ 599686042433355776 │
+└─────────────────┘
+Errors
ComputeError: If null or invalid inputs are encountered, or the transformation cannot be performed.cell_to_boundary¶Retrieve the polygon boundary coordinates of the given H3 cell.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
Float64 values representing [lat0, lng0, lat1, lng1, …].Examples
>>> df = pl.DataFrame({
+... "cell": ["8a1fb464492ffff"]
+... })
+>>> df.select(plh3.cell_to_boundary("cell"))
+shape: (1, 1)
+┌────────────────────────────────────┐
+│ cell_to_boundary │
+│ --- │
+│ list[f64] │
+╞════════════════════════════════════╡
+│ [[50.99, -76.05], [48.29, -81.91...│
+└────────────────────────────────────┘
+Errors
ComputeError: If null or invalid H3 cell indices are encountered.These functions provide metadata about an H3 index, such as its resolution or base cell, and provide utilities for converting into and out of the 64-bit representation of an H3 index.
get_resolution¶Retrieve the resolution of H3 indices (cells, edges, or vertices).
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
0–15) for each H3 index.Examples
>>> df = pl.DataFrame({
+... "h3_cell": [599686042433355775]
+... })
+>>> df.with_columns(
+... resolution=plh3.get_resolution("h3_cell")
+... )
+shape: (1, 2)
+┌─────────────────────┬────────────┐
+│ h3_cell │ resolution │
+│ --- │ --- │
+│ u64 │ i64 │
+╞═════════════════════╪════════════╡
+│ 599686042433355775 │ 2 │
+└─────────────────────┴────────────┘
+str_to_int¶Convert string H3 indices into their unsigned 64-bit integer representation.
Parameters
"85283473fffffff").Returns
pl.UInt64 indices, or null for invalid strings.Examples
>>> df = pl.DataFrame({
+... "h3_str": ["85283473fffffff", "invalid_index"]
+... })
+>>> df.with_columns(
+... h3_int=plh3.str_to_int("h3_str")
+... )
+shape: (2, 2)
+┌──────────────────┬─────────────────────┐
+│ h3_str │ h3_int │
+│ --- │ --- │
+│ str │ u64 │
+╞══════════════════╪═════════════════════╡
+│ 85283473fffffff │ 599686042433355775 │
+│ invalid_index │ null │
+└──────────────────┴─────────────────────┘
+int_to_str¶Convert integer H3 indices into their string representation.
Parameters
pl.UInt64, pl.Int64).Returns
null for invalid inputs.Examples
>>> df = pl.DataFrame({
+... "h3_int": [599686042433355775, -1]
+... })
+>>> df.with_columns(
+... h3_str=plh3.int_to_str("h3_int")
+... )
+shape: (2, 2)
+┌─────────────────────┬──────────────────┐
+│ h3_int │ h3_str │
+│ --- │ --- │
+│ u64 │ str │
+╞═════════════════════╪══════════════════╡
+│ 599686042433355775 │ 85283473fffffff │
+│ -1 │ null │
+└─────────────────────┴──────────────────┘
+is_valid_cell¶Check if H3 cell indices are valid.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
true if valid, false otherwise.Examples
>>> df = pl.DataFrame({
+... "h3_cell": ["85283473fffffff", "invalid_cell"]
+... })
+>>> df.with_columns(
+... valid=plh3.is_valid_cell("h3_cell")
+... )
+shape: (2, 2)
+┌─────────────────────┬───────┐
+│ h3_cell │ valid │
+│ --- │ --- │
+│ str │ bool │
+╞═════════════════════╪═══════╡
+│ 85283473fffffff │ true │
+│ invalid_cell │ false │
+└─────────────────────┴───────┘
+is_pentagon¶Determine if H3 cells are pentagons.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
Examples
>>> df = pl.DataFrame({
+... "h3_cell": [585961082523222015, 599686042433355775]
+... })
+>>> df.with_columns(
+... is_pent=plh3.is_pentagon("h3_cell")
+... )
+shape: (2, 2)
+┌─────────────────────┬─────────┐
+│ h3_cell │ is_pent │
+│ --- │ --- │
+│ u64 │ bool │
+╞═════════════════════╪═════════╡
+│ 585961082523222015 │ true │
+│ 599686042433355775 │ false │
+└─────────────────────┴─────────┘
+is_res_class_III¶Check if H3 cells belong to the Class III resolution set.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
Examples
>>> df = pl.DataFrame({
+... "h3_cell": [582692784209657855, 586265647244115967]
+... })
+>>> df.with_columns(
+... is_class_3=plh3.is_res_class_III("h3_cell")
+... )
+shape: (2, 2)
+┌─────────────────────┬────────────┐
+│ h3_cell │ is_class_3 │
+│ --- │ --- │
+│ u64 │ bool │
+╞═════════════════════╪════════════╡
+│ 582692784209657855 │ true │
+│ 586265647244115967 │ false │
+└─────────────────────┴────────────┘
+get_icosahedron_faces¶Retrieve the icosahedron faces intersected by an H3 cell.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
Examples
>>> df = pl.DataFrame({
+... "h3_cell": [599686042433355775]
+... })
+>>> df.with_columns(
+... faces=plh3.get_icosahedron_faces("h3_cell")
+... )
+shape: (1, 2)
+┌─────────────────────┬─────────┐
+│ h3_cell │ faces │
+│ --- │ --- │
+│ u64 │ list[i64]│
+╞═════════════════════╪═════════╡
+│ 599686042433355775 │ [7] │
+└─────────────────────┴─────────┘
+cell_to_parent¶Retrieve the parent cell of a given H3 cell at a specified resolution.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).[0, 15]Returns
Examples
>>> df = pl.DataFrame({"h3_cell": [599686042433355775]})
+>>> df.with_columns(
+... parent=plh3.cell_to_parent("h3_cell", 1)
+... )
+shape: (1, 2)
+┌─────────────────────┬─────────────────────┐
+│ h3_cell │ parent │
+│ --- │ --- │
+│ u64 │ u64 │
+╞═════════════════════╪═════════════════════╡
+│ 599686042433355775 │ 593686042413355775 │
+└─────────────────────┴─────────────────────┘
+cell_to_center_child¶Retrieve the center child cell of an H3 cell at a specified resolution.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).[0, 15]Returns
Examples
>>> df = pl.DataFrame({"h3_cell": [582692784209657855]})
+>>> df.with_columns(
+... center_child=plh3.cell_to_center_child("h3_cell", 2)
+... )
+shape: (1, 2)
+┌─────────────────────┬─────────────────┐
+│ h3_cell │ center_child │
+│ --- │ --- │
+│ u64 │ u64 │
+╞═════════════════════╪═════════════════╡
+│ 582692784209657855 │ ... │
+└─────────────────────┴─────────────────┘
+cell_to_children_size¶Get the number of children cells at a specified resolution.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).[0, 15]Returns
Examples
>>> df = pl.DataFrame({"h3_cell": [582692784209657855]})
+>>> df.with_columns(
+... num_children=plh3.cell_to_children_size("h3_cell", 2)
+... )
+shape: (1, 2)
+┌─────────────────────┬──────────────┐
+│ h3_cell │ num_children │
+│ --- │ --- │
+│ u64 │ u64 │
+╞═════════════════════╪══════════════╡
+│ 582692784209657855 │ 7 │
+└─────────────────────┴──────────────┘
+cell_to_children¶Retrieve all children cells of an H3 cell at a specified resolution.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).[0, 15]Returns
Examples
>>> df = pl.DataFrame({"h3_cell": [582692784209657855]})
+>>> df.with_columns(
+... children=plh3.cell_to_children("h3_cell", 2)
+... )
+shape: (1, 2)
+┌─────────────────────┬───────────────────────────────────┐
+│ h3_cell │ children │
+│ --- │ --- │
+│ u64 │ list[u64] │
+╞═════════════════════╪═══════════════════════════════════╡
+│ 582692784209657855 │ [587192535546331135, ...] │
+└─────────────────────┴───────────────────────────────────┘
+cell_to_child_pos¶Get the position index of a child cell within its parent cell hierarchy.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).[0, 15]Returns
Examples
>>> df = pl.DataFrame({"h3_cell": [582692784209657855]})
+>>> df.with_columns(
+... child_pos=plh3.cell_to_child_pos("h3_cell", 2)
+... )
+shape: (1, 2)
+┌─────────────────────┬───────────┐
+│ h3_cell │ child_pos │
+│ --- │ --- │
+│ u64 │ u64 │
+╞═════════════════════╪═══════════╡
+│ 582692784209657855 │ 0 │
+└─────────────────────┴───────────┘
+child_pos_to_cell¶Obtain the child cell at a given position index for a specified parent cell and resolution.
plh3.child_pos_to_cell(
+ parent: IntoExprColumn,
+ pos: IntoExprColumn,
+ resolution: HexResolution
+) -> pl.Expr
+Parameters
pl.UInt64, pl.Int64, or pl.Utf8).pl.UInt64 or pl.Int64).[0, 15]Returns
Examples
>>> df = pl.DataFrame({
+... "parent": [582692784209657855],
+... "pos": [0]
+... })
+>>> df.with_columns(
+... child=plh3.child_pos_to_cell("parent", "pos", 2)
+... )
+shape: (1, 2)
+┌─────────────────────┬──────────┐
+│ parent │ child │
+│ --- │ --- │
+│ u64 │ u64 │
+╞═════════════════════╪══════════╡
+│ 582692784209657855 │ ... │
+└─────────────────────┴──────────┘
+compact_cells¶Compact a set of H3 cells into a minimal covering set.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8), possibly in a list.Returns
Examples
>>> df = pl.DataFrame({
+... "h3_cells": [[599686042433355775, 599686042433355776]]
+... })
+>>> df.with_columns(
+... compact=plh3.compact_cells("h3_cells")
+... )
+shape: (1, 2)
+┌───────────────────────────────────┬────────────────────────────────┐
+│ h3_cells │ compact │
+│ --- │ --- │
+│ list[u64] │ list[u64] │
+╞═══════════════════════════════════╪════════════════════════════════╡
+│ [599686042433355775, 5996860424…] │ [599686042433355775] │
+└───────────────────────────────────┴────────────────────────────────┘
+uncompact_cells¶Uncompact a set of H3 cells to the specified resolution.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).[0, 15]Returns
Examples
>>> df = pl.DataFrame({
+... "compact_cells": [[582692784209657855]]
+... })
+>>> df.with_columns(
+... full_set=plh3.uncompact_cells("compact_cells", 2)
+... )
+shape: (1, 2)
+┌──────────────────────┬────────────────────────────────┐
+│ compact_cells │ full_set │
+│ --- │ --- │
+│ list[u64] │ list[u64] │
+╞══════════════════════╪════════════════════════════════╡
+│ [582692784209657855] │ [587192535546331135, ...] │
+└──────────────────────┴────────────────────────────────┘
+Notes
ComputeError may occur if inputs are invalid or the operation cannot be completed.ValueError is raised if the resolution is outside [0, 15].great_circle_distance¶Compute the Haversine distance between two latitude/longitude pairs.
plh3.great_circle_distance(
+ s_lat_deg: IntoExprColumn,
+ s_lng_deg: IntoExprColumn,
+ e_lat_deg: IntoExprColumn,
+ e_lng_deg: IntoExprColumn,
+ unit: Literal["km", "m"] = "km"
+) -> pl.Expr
+Description
Uses the Haversine formula to approximate the great circle distance on Earth’s surface. The error is usually much smaller than 0.5% for typical use cases.
Parameters
pl.Float64).pl.Float64).pl.Float64).pl.Float64).{"km", "m"}Returns
Examples
df = pl.DataFrame({
+ "start_lat": [37.775],
+ "start_lng": [-122.419],
+ "end_lat": [40.7128],
+ "end_lng": [-74.0060],
+})
+df.with_columns(
+ distance=plh3.great_circle_distance(
+ "start_lat", "start_lng", "end_lat", "end_lng", unit="km"
+ )
+)
+average_hexagon_area¶Return the average area of an H3 hexagon at a given resolution.
plh3.average_hexagon_area(
+ resolution: IntoExprColumn,
+ unit: Literal["km^2", "m^2"] = "km^2"
+) -> pl.Expr
+Parameters
0 to 15).{"km^2", "m^2"}"km^2").Returns
Examples
df = pl.DataFrame({"resolution": [5]})
+df.with_columns(
+ area=plh3.average_hexagon_area("resolution", "km^2")
+)
+cell_area¶Get the area of a specific H3 cell.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).{"km^2", "m^2"}Returns
Note: This function calls into a plugin that is elementwise. For invalid inputs, a ComputeError may be raised.
edge_length¶Determine the length of an H3 edge cell.
Warning: This function is not yet implemented and will raise NotImplementedError.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).{"km", "m"}Returns
average_hexagon_edge_length¶Get the average edge length of H3 hexagons at a specific resolution.
plh3.average_hexagon_edge_length(
+ resolution: IntoExprColumn,
+ unit: Literal["km", "m"] = "km"
+) -> pl.Expr
+Parameters
0 to 15).{"km", "m"}Returns
Examples
df = pl.DataFrame({"resolution": [1]})
+df.with_columns(
+ length=plh3.average_hexagon_edge_length("resolution", "km")
+)
+get_num_cells¶Get the total number of H3 cells at a given resolution.
Parameters
0 to 15).Returns
Examples
df = pl.DataFrame({"resolution": [5]})
+df.with_columns(
+ count=plh3.get_num_cells("resolution")
+)
+get_pentagons¶Get the number of pentagons at a given resolution.
Warning: This function is not yet implemented and will raise NotImplementedError.
Parameters
0 to 15).Returns
Note
ComputeError if given invalid input or null values.resolution will also raise a ValueError for out-of-range resolutions (< 0 or > 15).edge_length and get_pentagons functions are placeholders that raise NotImplementedError.Grid traversal allows finding cells in the vicinity of an origin cell, and determining how to traverse the grid from one cell to another.
grid_distance¶Compute the grid distance between two H3 cells.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).pl.UInt64, pl.Int64, or pl.Utf8).Returns
origin and destination, or null if it cannot be computed.Examples
>>> df = pl.DataFrame({
+... "start": [605035864166236159],
+... "end": [605034941150920703],
+... })
+>>> df.select(plh3.grid_distance("start", "end"))
+shape: (1, 1)
+┌───────────────┐
+│ grid_distance │
+│ --- │
+│ i64 │
+╞═══════════════╡
+│ 5 │
+└───────────────┘
+Errors
ComputeError: If inputs are invalid (e.g. different resolutions or pentagon issues).None: If no valid distance can be computed.grid_ring¶Produce a "hollow ring" of cells at exactly grid distance k from the origin cell.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
k. May contain null items if pentagonal distortion is encountered.Examples
>>> df = pl.DataFrame({"input": [622054503267303423]})
+>>> df.select(plh3.grid_ring("input", 1))
+shape: (1, 1)
+┌───────────────────────────────────┐
+│ grid_ring │
+│ --- │
+│ list[u64] │
+╞═══════════════════════════════════╡
+│ [622054502770606079, 622054502770…]│
+└───────────────────────────────────┘
+Returns
ValueError: If k < 0.ComputeError: If pentagonal distortion or invalid inputs prevent computation.grid_disk¶Produce a “filled-in disk” of cells within grid distance k of the origin cell.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
k.null items if pentagonal distortion is encountered.Examples
>>> df = pl.DataFrame({"input": [622054503267303423]})
+>>> df.select(plh3.grid_disk("input", 1))
+shape: (1, 1)
+┌───────────────────────────────────┐
+│ grid_disk │
+│ --- │
+│ list[u64] │
+╞═══════════════════════════════════╡
+│ [622054503267303423, 622054502770…]│
+└───────────────────────────────────┘
+Returns
ValueError: If k < 0.ComputeError: If pentagonal distortion or invalid inputs prevent computation.grid_path_cells¶Find a minimal contiguous path of cells from origin to destination.
Parameters
Returns
origin to destination, or null if no valid path is found.Examples
>>> df = pl.DataFrame({
+... "start": [605035864166236159],
+... "end": [605034941150920703],
+... })
+>>> df.select(plh3.grid_path_cells("start", "end"))
+shape: (1, 1)
+┌───────────────────────────────────┐
+│ grid_path_cells │
+│ --- │
+│ list[u64] │
+╞═══════════════════════════════════╡
+│ [605035864166236159, 605035861750…]│
+└───────────────────────────────────┘
+Returns
ComputeError: If no valid path can be computed (e.g., due to invalid inputs or pentagon issues).Vertex mode allows encoding the topological vertexes of H3 cells.
cell_to_vertex¶Retrieve the H3 vertex index for a specific vertex of a given cell.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).[0..5]; for pentagonal cells, [0..4].Returns
pl.UInt64 or pl.Int64), or null if invalid.Examples
>>> df = pl.DataFrame({"h3_cell": [599686042433355775]})
+>>> df.with_columns(vertex=plh3.cell_to_vertex("h3_cell", 0))
+shape: (1, 2)
+┌─────────────────────┬─────────────────────┐
+│ h3_cell │ vertex │
+│ --- │ --- │
+│ u64 │ u64 │
+╞═════════════════════╪═════════════════════╡
+│ 599686042433355775 │ 2473183459502194687 │
+└─────────────────────┴─────────────────────┘
+Errors
ComputeError: If vertex_num is out of range or the cell is invalid.cell_to_vertexes¶Retrieve all vertex indices for a given H3 cell.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
Examples
>>> df = pl.DataFrame({"h3_cell": [599686042433355775]})
+>>> df.with_columns(vertexes=plh3.cell_to_vertexes("h3_cell"))
+shape: (1, 2)
+┌─────────────────────┬────────────────────────────────────────────────┐
+│ h3_cell │ vertexes │
+│ --- │ --- │
+│ u64 │ list[u64] │
+╞═════════════════════╪════════════════════════════════════════════════╡
+│ 599686042433355775 │ [2473183459502194687, 2545241069646249983, … ] │
+└─────────────────────┴────────────────────────────────────────────────┘
+vertex_to_latlng¶Convert an H3 vertex index into its latitude and longitude coordinates.
Parameters
pl.UInt64, pl.Int64, or pl.Utf8).Returns
[latitude, longitude] (Float64, Float64) or null if invalid.Examples
>>> df = pl.DataFrame({"vertex": [2459626752788398079]})
+>>> df.with_columns(coords=plh3.vertex_to_latlng("vertex"))
+shape: (1, 2)
+┌──────────────────────┬─────────────────────────┐
+│ vertex │ coords │
+│ --- │ --- │
+│ u64 │ list[f64] │
+╞══════════════════════╪═════════════════════════╡
+│ 2459626752788398079 │ [39.38084284181812, 88.57496213785487] │
+└──────────────────────┴─────────────────────────┘
+is_valid_vertex¶Check whether an H3 index represents a valid H3 vertex.
Parameters
Returns
true if valid, false otherwise.Examples
>>> df = pl.DataFrame({"vertex": [2459626752788398079]})
+>>> df.with_columns(valid=plh3.is_valid_vertex("vertex"))
+shape: (1, 2)
+┌──────────────────────┬──────────┐
+│ vertex │ valid │
+│ --- │ --- │
+│ u64 │ bool │
+╞══════════════════════╪══════════╡
+│ 2459626752788398079 │ true │
+└──────────────────────┴──────────┘
+