H3HexagonLayer

Screenshot from H3 Population example

lonboard.H3HexagonLayer

Bases: PolygonLayer

The H3HexagonLayer renders hexagons from the H3 geospatial indexing system.

Example:

From Pandas:

import pandas as pd
from lonboard import Map, H3HexagonLayer

# A DataFrame with H3 cell identifiers
df = pd.DataFrame({
    "h3_index": ["8928308280fffff", "8928308280bffff", ...],
    "other_attributes": [...],
})
layer = H3HexagonLayer.from_pandas(
    df,
    get_hexagon=df["h3_index"],
)
m = Map(layer)

Or, you can pass in an Arrow table directly

from lonboard import Map, H3HexagonLayer

# Example: An Arrow table with H3 identifiers as a column
layer = H3HexagonLayer(
    table,
    get_hexagon=table["h3_index"],
)
m = Map(layer)

auto_highlight class-attribute instance-attribute

auto_highlight = tag(sync=True)

When true, the current object pointed to by the mouse pointer (when hovered over) is highlighted with highlightColor.

Requires pickable to be True.

• Type: bool
• Default: False

before_id class-attribute instance-attribute

before_id = tag(sync=True)

The identifier of a layer in the Maplibre basemap layer stack.

This deck.gl layer will be rendered just before the layer with the given identifier. You can find such an identifier by inspecting the basemap style JSON.

For example, in the Carto Positron style, if you look at the raw JSON data, each layer has an "id" property. The first layer in the basemap stack has "id": "background". So if you pass before_id="background", you won't see your deck.gl layer because it will be rendered below all layers in the Maplibre basemap.

A common choice for Carto-based styles is to use before_id="watername_ocean" so that your deck.gl layer is rendered above the core basemap elements but below all text labels.

Info

This only has an effect when the map's basemap is a MaplibreBasemap, and the map is rendering in "interleaved" mode.

coverage class-attribute instance-attribute

coverage = tag(sync=True)

Hexagon radius multiplier, between 0 - 1.

When coverage = 1, hexagon is rendered with actual size, by specifying a different value (between 0 and 1) hexagon can be scaled down.

• Type: float, optional
• Default: 1

elevation_scale class-attribute instance-attribute

elevation_scale = tag(sync=True)

Elevation multiplier.

The final elevation is calculated by elevationScale * getElevation(d). elevationScale is a handy property to scale all elevation without updating the data.

• Type: float, optional
• Default: 1

extensions class-attribute instance-attribute

extensions = tag(sync=True, **(widget_serialization))

A list of layer extension objects to add additional features to a layer.

extruded class-attribute instance-attribute

extruded = tag(sync=True)

Whether to extrude the polygons.

Based on the elevations provided by the getElevation accessor.

If set to false, all polygons will be flat, this generates less geometry and is faster than simply returning 0 from getElevation.

• Type: bool, optional
• Default: False

filled class-attribute instance-attribute

filled = tag(sync=True)

Whether to draw a filled polygon (solid fill).

Note that only the area between the outer polygon and any holes will be filled.

• Type: bool, optional
• Default: True

get_elevation class-attribute instance-attribute

get_elevation = FloatAccessor(None, allow_none=True)

The elevation to extrude each polygon with, in meters.

Only applies if extruded=True.

• Type: FloatAccessor, optional
  • If a number is provided, it is used as the width for all polygons.
  • If an array is provided, each value in the array will be used as the width for the polygon at the same row index.
• Default: 1000.

get_fill_color class-attribute instance-attribute

get_fill_color = ColorAccessor(None, allow_none=True)

The fill color of each polygon in the format of [r, g, b, [a]]. Each channel is a number between 0-255 and a is 255 if not supplied.

• Type: ColorAccessor, optional
  • If a single list or tuple is provided, it is used as the fill color for all polygons.
  • If a numpy or pyarrow array is provided, each value in the array will be used as the fill color for the polygon at the same row index.
• Default: [0, 0, 0, 255].

get_hexagon class-attribute instance-attribute

get_hexagon = H3Accessor()

The cell identifier of each H3 hexagon.

Accepts either an array of strings or uint64 integers representing H3 cell IDs.

• Type: H3Accessor

get_line_color class-attribute instance-attribute

get_line_color = ColorAccessor(None, allow_none=True)

The outline color of each polygon in the format of [r, g, b, [a]]. Each channel is a number between 0-255 and a is 255 if not supplied.

Only applies if stroked=True.

• Type: ColorAccessor, optional
  • If a single list or tuple is provided, it is used as the outline color for all polygons.
  • If a numpy or pyarrow array is provided, each value in the array will be used as the outline color for the polygon at the same row index.
• Default: [0, 0, 0, 255].

get_line_width class-attribute instance-attribute

get_line_width = FloatAccessor(None, allow_none=True)

The width of the outline of each polygon, in units specified by line_width_units (default 'meters').

• Type: FloatAccessor, optional
  • If a number is provided, it is used as the outline width for all polygons.
  • If an array is provided, each value in the array will be used as the outline width for the polygon at the same row index.
• Default: 1.

high_precision class-attribute instance-attribute

high_precision = tag(sync=True)

Whether to render H3 hexagons in high-precision mode.

Each hexagon in the H3 indexing system is slightly different in shape. To draw a large number of hexagons efficiently, the H3HexagonLayer may choose to use instanced drawing by assuming that all hexagons within the current viewport have the same shape as the one at the center of the current viewport. The discrepancy is usually too small to be visible.

There are several cases in which high-precision mode is required. In these cases, H3HexagonLayer may choose to switch to high-precision mode, where it trades performance for accuracy:

• The input set contains a pentagon. There are 12 pentagons world wide at each resolution, and these cells and their immediate neighbors have significant differences in shape.
• The input set is at a coarse resolution (res 0 through res 5). These cells have larger differences in shape, particularly when using a Mercator projection.
• The input set contains hexagons with different resolutions.

Possible values:

• None: The layer chooses the mode automatically. High-precision rendering is only used if an edge case is encountered in the data.
• True: Always use high-precision rendering.

• False: Always use instanced rendering, regardless of the characteristics of the data.

• Type: bool | None, optional

• Default: None

highlight_color class-attribute instance-attribute

highlight_color = VariableLengthTuple(
    Int(), default_value=None, minlen=3, maxlen=4
)

RGBA color to blend with the highlighted object (the hovered over object if auto_highlight=true). When the value is a 3 component (RGB) array, a default alpha of 255 is applied.

• Type: List or Tuple of integers
• Default: [0, 0, 128, 128]

line_joint_rounded class-attribute instance-attribute

line_joint_rounded = tag(sync=True)

Type of joint. If true, draw round joints. Otherwise draw miter joints.

• Type: bool, optional
• Default: False

line_miter_limit class-attribute instance-attribute

line_miter_limit = tag(sync=True)

The maximum extent of a joint in ratio to the stroke width.

Only works if line_joint_rounded is false.

• Type: float, optional
• Default: 4

line_width_max_pixels class-attribute instance-attribute

line_width_max_pixels = tag(sync=True)

The maximum outline width in pixels. This can be used to prevent the outline from getting too big when zoomed in.

• Type: float, optional
• Default: None

line_width_min_pixels class-attribute instance-attribute

line_width_min_pixels = tag(sync=True)

The minimum outline width in pixels. This can be used to prevent the outline from getting too small when zoomed out.

• Type: float, optional
• Default: 0

line_width_scale class-attribute instance-attribute

line_width_scale = tag(sync=True)

The outline width multiplier that multiplied to all outlines of Polygon and MultiPolygon features if the stroked attribute is true.

• Type: float, optional
• Default: 1

line_width_units class-attribute instance-attribute

line_width_units = tag(sync=True)

The units of the outline width, one of 'meters', 'common', and 'pixels'. See unit system.

• Type: str, optional
• Default: 'meters'

opacity class-attribute instance-attribute

opacity = tag(sync=True)

The opacity of the layer.

• Type: float. Must range between 0 and 1.
• Default: 1

pickable class-attribute instance-attribute

pickable = tag(sync=True)

Whether the layer responds to mouse pointer picking events.

This must be set to True for tooltips and other interactive elements to be available. This can also be used to only allow picking on specific layers within a map instance.

Note that picking has some performance overhead in rendering. To get the absolute best rendering performance with large data (at the cost of removing interactivity), set this to False.

• Type: bool
• Default: True

selected_index class-attribute instance-attribute

selected_index = tag(sync=True)

The positional index of the most-recently clicked on row of data.

You can use this to access the full row of data from a GeoDataFrame

gdf.iloc[layer.selected_index]

Setting a value here from Python will do nothing. This attribute only exists to be updated from JavaScript on a map click. Note that pickable must be True (the default) on this layer for the JavaScript onClick handler to work; if pickable is set to False, selected_index will never update.

Note that you can use observe to call a function whenever a new value is received from JavaScript. Refer here for an example.

stroked class-attribute instance-attribute

stroked = tag(sync=True)

Whether to draw an outline around the polygon (solid fill).

Note that both the outer polygon as well the outlines of any holes will be drawn.

• Type: bool, optional
• Default: True

table class-attribute instance-attribute

table = ArrowTableTrait(geometry_required=False)

An Arrow table with properties to associate with the H3 hexagons.

If you have a Pandas DataFrame, use from_pandas instead.

visible class-attribute instance-attribute

visible = tag(sync=True)

Whether the layer is visible.

Under most circumstances, using the visible attribute to control the visibility of layers is recommended over removing/adding the layer from the Map.layers list.

In particular, toggling the visible attribute will persist the layer on the JavaScript side, while removing/adding the layer from the Map.layers list will re-download and re-render from scratch.

• Type: bool
• Default: True

wireframe class-attribute instance-attribute

wireframe = tag(sync=True)

Whether to generate a line wireframe of the polygon. The outline will have "horizontal" lines closing the top and bottom polygons and a vertical line (a "strut") for each vertex on the polygon.

• Type: bool, optional
• Default: False

Remarks:

• These lines are rendered with GL.LINE and will thus always be 1 pixel wide.
• Wireframe and solid extrusions are exclusive, you'll need to create two layers with the same data if you want a combined rendering effect.

__init__

__init__(
    table: ArrowStreamExportable,
    *,
    get_hexagon: H3AccessorInput,
    _rows_per_chunk: int | None = None,
    **kwargs: Unpack[H3HexagonLayerKwargs]
) -> None

Create a new H3HexagonLayer.

Parameters:

• table (ArrowStreamExportable) –

  An Arrow table with properties to associate with the H3 hexagons.

Other Parameters:

• get_hexagon (H3AccessorInput) –

  The cell identifier of each H3 hexagon.

• kwargs (Unpack[H3HexagonLayerKwargs]) –

  Extra args passed down as H3HexagonLayer attributes.

from_duckdb classmethod

from_duckdb(
    sql: str | DuckDBPyRelation,
    con: DuckDBPyConnection | None = None,
    *,
    crs: str | CRS | None = None,
    **kwargs: Unpack[PolygonLayerKwargs]
) -> Self

Construct a Layer from a duckdb-spatial query.

DuckDB Spatial does not currently expose coordinate reference system information, so the user must ensure that data has been reprojected to EPSG:4326 or pass in the existing CRS of the data in the crs keyword parameter.

Parameters:

• sql (str | DuckDBPyRelation) –

  The SQL input to visualize. This can either be a string containing a SQL query or the output of the duckdb sql function.

• con (DuckDBPyConnection | None, default: None ) –

  The current DuckDB connection. This is required when passing a str to the sql parameter.

Other Parameters:

• crs (str | CRS | None) –

  The CRS of the input data. This can either be a string passed to pyproj.CRS.from_user_input or a pyproj.CRS object. Defaults to None.

• kwargs (Unpack[BaseLayerKwargs]) –

  parameters passed on to __init__

Returns:

• Self –

  A Layer with the initialized data.

from_geopandas classmethod

from_geopandas(
    gdf: GeoDataFrame,
    *,
    auto_downcast: bool = True,
    **kwargs: Unpack[PolygonLayerKwargs]
) -> Self

Construct a Layer from a geopandas GeoDataFrame.

The GeoDataFrame will be reprojected to EPSG:4326 if it is not already in that coordinate system.

Parameters:

• gdf (GeoDataFrame) –

  The GeoDataFrame to set on the layer.

Other Parameters:

• auto_downcast (bool) –

  If True, automatically downcast to smaller-size data types if possible without loss of precision. This calls pandas.DataFrame.convert_dtypes and pandas.to_numeric under the hood.

• kwargs (Unpack[BaseLayerKwargs]) –

  parameters passed on to __init__

Returns:

• Self –

  A Layer with the initialized data.

from_pandas classmethod

from_pandas(
    df: DataFrame,
    *,
    get_hexagon: H3AccessorInput,
    auto_downcast: bool = True,
    **kwargs: Unpack[H3HexagonLayerKwargs]
) -> Self

Create a new H3HexagonLayer from a pandas DataFrame.

Parameters:

• df (DataFrame) –

  a Pandas DataFrame with properties to associate with H3 hexagons.

Other Parameters:

• get_hexagon (H3AccessorInput) –

  H3 cell identifier of each H3 hexagon.

• auto_downcast (bool) –

  Whether to save memory on input by casting to smaller types. Defaults to True.

• kwargs (Unpack[H3HexagonLayerKwargs]) –

  Extra args passed down as H3HexagonLayer attributes.