refactor: Improve H3 layer code reuse (#1006)

### Change list

- Python `H3HexagonLayer` subclasses from `PolygonLayer`, so we don't
have to redefine all the polygon properties
- JS `H3HexagonModel` subclasses from core `BasePolygonModel`, so we
don't hve to redefine props
- Split JS models into separate files.
- Remove H3 index validation because the validation failed for kontur
data from
https://data.humdata.org/dataset/kontur-population-dataset-22km
- Improve H3 layer docs

Closes #1002

Author: kylebarron

lonboard/layer/_h3.py

@@ -8,8 +8,8 @@
 
 from lonboard._geoarrow.ops import Bbox, WeightedCentroid
 from lonboard._utils import auto_downcast as _auto_downcast
-from lonboard.layer._base import BaseArrowLayer
-from lonboard.traits import ArrowTableTrait, ColorAccessor, FloatAccessor, H3Accessor
+from lonboard.layer._polygon import PolygonLayer
+from lonboard.traits import ArrowTableTrait, H3Accessor
 
 if TYPE_CHECKING:
     import sys
@@ -82,37 +82,38 @@ def default_h3_viewport(ca: ChunkedArray) -> tuple[Bbox, WeightedCentroid] | Non
     )
 
 
-class H3HexagonLayer(BaseArrowLayer):
-    """The `H3HexagonLayer` renders H3 hexagons.
+class H3HexagonLayer(PolygonLayer):
+    """The `H3HexagonLayer` renders hexagons from the [H3](https://h3geo.org/) geospatial indexing system.
 
     **Example:**
 
-    From GeoPandas:
+    From Pandas:
 
     ```py
-    import geopandas as gpd
+    import pandas as pd
     from lonboard import Map, H3HexagonLayer
 
-    # A GeoDataFrame with Polygon or MultiPolygon geometries
-    gdf = gpd.GeoDataFrame()
-    layer = H3HexagonLayer.from_geopandas(
-        gdf,
-        get_fill_color=[255, 0, 0],
+    # 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)
     ```
 
-    From an Arrow-compatible source like [pyogrio][pyogrio] or [geoarrow-rust](https://geoarrow.github.io/geoarrow-rs/python/latest):
+    Or, you can pass in an Arrow table directly
 
     ```py
-    from geoarrow.rust.io import read_flatgeobuf
     from lonboard import Map, H3HexagonLayer
 
-    # Example: A FlatGeobuf file with Polygon or MultiPolygon geometries
-    table = read_flatgeobuf("path/to/file.fgb")
+    # Example: An Arrow table with H3 identifiers as a column
     layer = H3HexagonLayer(
         table,
-        get_fill_color=[255, 0, 0],
+        get_hexagon=table["h3_index"],
     )
     m = Map(layer)
     ```
@@ -162,11 +163,11 @@ def from_pandas(
         """Create a new H3HexagonLayer from a pandas DataFrame.
 
         Args:
-            df: _description_
+            df: a Pandas DataFrame with properties to associate with H3 hexagons.
 
         Keyword Args:
-            get_hexagon: _description_
-            auto_downcast: _description_. Defaults to True.
+            get_hexagon: H3 cell identifier of each H3 hexagon.
+            auto_downcast: Whether to save memory on input by casting to smaller types. Defaults to True.
             kwargs: Extra args passed down as H3HexagonLayer attributes.
 
         Raises:
@@ -194,173 +195,46 @@ def from_pandas(
     _layer_type = t.Unicode("h3-hexagon").tag(sync=True)
 
     table = ArrowTableTrait(geometry_required=False)
+    """An Arrow table with properties to associate with the H3 hexagons.
 
-    get_hexagon = H3Accessor()
-    """
-    todo
-    """
-
-    high_precision = t.Bool(None, allow_none=True).tag(sync=True)
-
-    stroked = t.Bool(None, allow_none=True).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`
-    """
-
-    filled = t.Bool(None, allow_none=True).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`
+    If you have a Pandas `DataFrame`, use
+    [`from_pandas`][lonboard.H3HexagonLayer.from_pandas] instead.
     """
 
-    extruded = t.Bool(None, allow_none=True).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`
-    """
-
-    wireframe = t.Bool(None, allow_none=True).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.
-    """
-
-    elevation_scale = t.Float(None, allow_none=True, min=0).tag(sync=True)
-    """Elevation multiplier.
+    get_hexagon = H3Accessor()
+    """The cell identifier of each H3 hexagon.
 
-    The final elevation is calculated by `elevationScale * getElevation(d)`.
-    `elevationScale` is a handy property to scale all elevation without updating the
-    data.
+    Accepts either an array of strings or uint64 integers representing H3 cell IDs.
 
-    - Type: `float`, optional
-    - Default: `1`
+    - Type: [H3Accessor][lonboard.traits.H3Accessor]
     """
 
-    line_width_units = t.Unicode(None, allow_none=True).tag(sync=True)
-    """
-    The units of the outline width, one of `'meters'`, `'common'`, and `'pixels'`. See
-    [unit
-    system](https://deck.gl/docs/developer-guide/coordinate-systems#supported-units).
-
-    - Type: `str`, optional
-    - Default: `'meters'`
-    """
+    high_precision = t.Bool(None, allow_none=True).tag(sync=True)
+    """Whether to render H3 hexagons in high-precision mode.
 
-    line_width_scale = t.Float(None, allow_none=True, min=0).tag(sync=True)
-    """
-    The outline width multiplier that multiplied to all outlines of `Polygon` and
-    `MultiPolygon` features if the `stroked` attribute is true.
+    Each hexagon in the H3 indexing system is [slightly different in shape](https://h3geo.org/docs/core-library/coordsystems). 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.
 
-    - Type: `float`, optional
-    - Default: `1`
-    """
+    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:
 
-    line_width_min_pixels = t.Float(None, allow_none=True, min=0).tag(sync=True)
-    """
-    The minimum outline width in pixels. This can be used to prevent the outline from
-    getting too small when zoomed out.
+    * 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.
 
-    - Type: `float`, optional
-    - Default: `0`
-    """
+    Possible values:
 
-    line_width_max_pixels = t.Float(None, allow_none=True, min=0).tag(sync=True)
-    """
-    The maximum outline width in pixels. This can be used to prevent the outline from
-    getting too big when zoomed in.
+    * `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: `float`, optional
+    - Type: `bool | None`, optional
     - Default: `None`
     """
 
-    line_joint_rounded = t.Bool(None, allow_none=True).tag(sync=True)
-    """Type of joint. If `true`, draw round joints. Otherwise draw miter joints.
-
-    - Type: `bool`, optional
-    - Default: `False`
-    """
+    coverage = t.Float(None, allow_none=True, min=0, max=1).tag(sync=True)
+    """Hexagon radius multiplier, between 0 - 1.
 
-    line_miter_limit = t.Float(None, allow_none=True, min=0).tag(sync=True)
-    """The maximum extent of a joint in ratio to the stroke width.
-
-    Only works if `line_joint_rounded` is false.
+    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: `4`
-    """
-
-    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][lonboard.traits.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_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][lonboard.traits.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 = FloatAccessor(None, allow_none=True)
-    """
-    The width of the outline of each polygon, in units specified by `line_width_units`
-    (default `'meters'`).
-
-    - Type: [FloatAccessor][lonboard.traits.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`.
-    """
-
-    get_elevation = FloatAccessor(None, allow_none=True)
-    """
-    The elevation to extrude each polygon with, in meters.
-
-    Only applies if `extruded=True`.
-
-    - Type: [FloatAccessor][lonboard.traits.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`.
+    - Default: `1`
     """

lonboard/traits/_h3.py

@@ -7,7 +7,7 @@
 import numpy as np
 from arro3.core import Array, ChunkedArray, DataType
 
-from lonboard._h3 import str_to_h3, validate_h3_indices
+from lonboard._h3 import str_to_h3
 from lonboard._serialization import ACCESSOR_SERIALIZATION
 from lonboard.traits._base import FixedErrorTraitType
 
@@ -125,13 +125,8 @@ def validate(self, obj: BaseArrowLayer, value: Any) -> ChunkedArray:
                 info="H3 Arrow array must be uint64 type.",
             )
 
-        try:
-            validate_h3_indices(value.to_numpy())
-        except ValueError as e:
-            self.error(
-                obj,
-                value,
-                info=f"H3 index validation error: {e}",
-            )
+        # Ideally we would validate the H3 indices here, but I hit spurious validation
+        # errors with the kontur 22km dataset
+        # https://data.humdata.org/dataset/kontur-population-dataset-22km
 
         return value.rechunk(max_chunksize=obj._rows_per_chunk)

package-lock.json

@@ -8,7 +8,7 @@
     "@deck.gl/mapbox": "^9.2.2",
     "@deck.gl/mesh-layers": "^9.2.2",
     "@deck.gl/react": "^9.2.2",
-    "@geoarrow/deck.gl-layers": "^0.4.0-beta.4",
+    "@geoarrow/deck.gl-layers": "^0.4.0-beta.5",
     "@geoarrow/geoarrow-js": "^0.3.2",
     "@nextui-org/react": "^2.4.8",
     "@xstate/react": "^6.0.0",

package.json

@@ -1,11 +1,6 @@
 export { BaseModel } from "./base.js";
-export { BaseLayerModel } from "./base-layer.js";
-export {
-  PathModel,
-  ScatterplotModel,
-  SolidPolygonModel,
-  initializeLayer,
-} from "./layer.js";
+export { BaseLayerModel } from "./layer/base.js";
+export { initializeLayer } from "./layer/index.js";
 export {
   BaseExtensionModel,
   BrushingExtension,