feat: Allow passing GeoArrow arrays and chunked arrays directly to layer constructors (#828)

### Change list

- Implement `total_bounds` and `weighted_centroid` for `geoarrow.box`
arrays
- Always add positional row index when the user passes in a raw array or
chunked array
- Convert a geoarrow box column to a geoarrow polygon column in the
table trait validation directly.
- Add new tests for passing `geoarrow.box` array and chunked array into
`PolygonLayer` constructor.


Closes #823

Author: kylebarron

lonboard/_geoarrow/ops/bbox.py

@@ -6,7 +6,7 @@
 from dataclasses import dataclass
 
 import numpy as np
-from arro3.core import Array, ChunkedArray, DataType, Field, list_flatten
+from arro3.core import Array, ChunkedArray, DataType, Field, list_flatten, struct_field
 
 from lonboard._constants import EXTENSION_NAME
 
@@ -44,6 +44,9 @@ def total_bounds(field: Field, column: ChunkedArray) -> Bbox:
     if extension_type_name == EXTENSION_NAME.MULTIPOLYGON:
         return _total_bounds_nest_3(column)
 
+    if extension_type_name == EXTENSION_NAME.BOX:
+        return _total_bounds_box(column)
+
     assert False
 
 
@@ -91,3 +94,30 @@ def _total_bounds_nest_3(column: ChunkedArray) -> Bbox:
         bbox.update(_coords_bbox(coords))
 
     return bbox
+
+
+def _total_bounds_box(column: ChunkedArray) -> Bbox:
+    """Compute the total bounds of a geoarrow.box column."""
+    bbox = Bbox()
+    for chunk in column.chunks:
+        is_2d = len(chunk.field.type.fields) == 4
+        is_3d = len(chunk.field.type.fields) == 6
+
+        if is_2d:
+            minx = np.min(struct_field(chunk, 0))
+            miny = np.min(struct_field(chunk, 1))
+            maxx = np.max(struct_field(chunk, 2))
+            maxy = np.max(struct_field(chunk, 3))
+        elif is_3d:
+            minx = np.min(struct_field(chunk, 0))
+            miny = np.min(struct_field(chunk, 1))
+            maxx = np.max(struct_field(chunk, 3))
+            maxy = np.max(struct_field(chunk, 4))
+        else:
+            raise ValueError(
+                f"Unexpected box type with {len(chunk.field.type.fields)} fields.\n"
+                "Only 2D and 3D boxes are supported.",
+            )
+        bbox.update(Bbox(minx=minx, miny=miny, maxx=maxx, maxy=maxy))
+
+    return bbox

lonboard/_geoarrow/ops/centroid.py

@@ -5,7 +5,7 @@
 from dataclasses import dataclass
 
 import numpy as np
-from arro3.core import Array, ChunkedArray, DataType, Field, list_flatten
+from arro3.core import Array, ChunkedArray, DataType, Field, list_flatten, struct_field
 
 from lonboard._constants import EXTENSION_NAME
 
@@ -109,6 +109,9 @@ def weighted_centroid(field: Field, column: ChunkedArray) -> WeightedCentroid:
     if extension_type_name == EXTENSION_NAME.MULTIPOLYGON:
         return _weighted_centroid_nest_3(column)
 
+    if extension_type_name == EXTENSION_NAME.BOX:
+        return _weighted_centroid_box(column)
+
     assert False
 
 
@@ -146,3 +149,34 @@ def _weighted_centroid_nest_3(column: ChunkedArray) -> WeightedCentroid:
         centroid.update_coords(coords)
 
     return centroid
+
+
+def _weighted_centroid_box(column: ChunkedArray) -> WeightedCentroid:
+    """Compute the weighted centroid of a box geometry."""
+    centroid = WeightedCentroid()
+    for chunk in column.chunks:
+        is_2d = len(chunk.field.type.fields) == 4
+        is_3d = len(chunk.field.type.fields) == 6
+
+        if is_2d:
+            minx = struct_field(chunk, 0)
+            miny = struct_field(chunk, 1)
+            maxx = struct_field(chunk, 2)
+            maxy = struct_field(chunk, 3)
+        elif is_3d:
+            minx = struct_field(chunk, 0)
+            miny = struct_field(chunk, 1)
+            maxx = struct_field(chunk, 3)
+            maxy = struct_field(chunk, 4)
+        else:
+            raise ValueError(
+                f"Unexpected box type with {len(chunk.field.type.fields)} fields.\n"
+                "Only 2D and 3D boxes are supported.",
+            )
+
+        meanx = float((np.mean(minx) + np.mean(maxx)) / 2)
+        meany = float((np.mean(miny) + np.mean(maxy)) / 2)
+
+        centroid.update(WeightedCentroid(x=meanx, y=meany, num_items=len(chunk)))
+
+    return centroid

lonboard/_geoarrow/ops/coord_layout.py

@@ -33,6 +33,11 @@ def make_geometry_interleaved(
     geom_field = table.schema.field(geom_col_idx)
     geom_column = table.column(geom_col_idx)
 
+    # The GeoArrow box extension type is only struct, not interleaved. It will be
+    # converted to an interleaved polygon separately, if needed.
+    if geom_field.metadata.get(b"ARROW:extension:name") == EXTENSION_NAME.BOX:
+        return table
+
     new_field, new_column = transpose_column(field=geom_field, column=geom_column)
     return table.set_column(geom_col_idx, new_field, new_column)
 

lonboard/_geoarrow/row_index.py

@@ -0,0 +1,18 @@
+import numpy as np
+from arro3.core import Array, ChunkedArray, Table
+
+
+def add_positional_row_index(
+    table: Table,
+) -> Table:
+    num_rows = table.num_rows
+    if num_rows <= np.iinfo(np.uint8).max:
+        arange_col = Array(np.arange(num_rows, dtype=np.uint8))
+    elif num_rows <= np.iinfo(np.uint16).max:
+        arange_col = Array(np.arange(num_rows, dtype=np.uint16))
+    elif num_rows <= np.iinfo(np.uint32).max:
+        arange_col = Array(np.arange(num_rows, dtype=np.uint32))
+    else:
+        arange_col = Array(np.arange(num_rows, dtype=np.uint64))
+
+    return table.append_column("row_index", ChunkedArray([arange_col]))

lonboard/_layer.py

@@ -20,18 +20,19 @@
 import ipywidgets
 import traitlets
 import traitlets as t
-from arro3.core import Table
+from arro3.core import ChunkedArray, Schema, Table
 
 from lonboard._base import BaseExtension, BaseWidget
 from lonboard._constants import EXTENSION_NAME, OGC_84
 from lonboard._geoarrow._duckdb import from_duckdb as _from_duckdb
-from lonboard._geoarrow.box_to_polygon import parse_box_encoded_table
+from lonboard._geoarrow.c_stream_import import import_arrow_c_stream
 from lonboard._geoarrow.geopandas_interop import geopandas_to_geoarrow
 from lonboard._geoarrow.ops import reproject_table
 from lonboard._geoarrow.ops.bbox import Bbox, total_bounds
 from lonboard._geoarrow.ops.centroid import WeightedCentroid, weighted_centroid
 from lonboard._geoarrow.ops.coord_layout import make_geometry_interleaved
 from lonboard._geoarrow.parse_wkb import parse_serialized_table
+from lonboard._geoarrow.row_index import add_positional_row_index
 from lonboard._serialization import infer_rows_per_chunk
 from lonboard._utils import auto_downcast as _auto_downcast
 from lonboard._utils import get_geometry_column_index, remove_extension_kwargs
@@ -361,6 +362,16 @@ def __init__(
             A Layer with the initialized data.
 
         """
+        imported_stream = import_arrow_c_stream(table)
+        if isinstance(imported_stream, Table):
+            table_o3 = imported_stream
+        else:
+            assert isinstance(imported_stream, ChunkedArray)
+            field = imported_stream.field.with_name("geometry")
+            schema = Schema([field])
+            table = Table.from_arrays([imported_stream], schema=schema)
+            table = add_positional_row_index(table)
+
         table_o3 = Table.from_arrow(table)
         parsed_tables = parse_serialized_table(table_o3)
         assert len(parsed_tables) == 1, (
@@ -1067,7 +1078,6 @@ def __init__(
         _rows_per_chunk: int | None = None,
         **kwargs: Unpack[PolygonLayerKwargs],
     ) -> None:
-        table = parse_box_encoded_table(Table.from_arrow(table))
         super().__init__(table=table, _rows_per_chunk=_rows_per_chunk, **kwargs)
 
     @classmethod
@@ -1857,7 +1867,6 @@ def __init__(
         _rows_per_chunk: int | None = None,
         **kwargs: Unpack[SolidPolygonLayerKwargs],
     ) -> None:
-        table = parse_box_encoded_table(Table.from_arrow(table))
         super().__init__(table=table, _rows_per_chunk=_rows_per_chunk, **kwargs)
 
     @classmethod

lonboard/_viz.py

@@ -24,6 +24,7 @@
 from lonboard._geoarrow.extension_types import construct_geometry_array
 from lonboard._geoarrow.geopandas_interop import geopandas_to_geoarrow
 from lonboard._geoarrow.parse_wkb import parse_serialized_table
+from lonboard._geoarrow.row_index import add_positional_row_index
 from lonboard._layer import PathLayer, PolygonLayer, ScatterplotLayer
 from lonboard._map import Map
 from lonboard._utils import (
@@ -447,18 +448,7 @@ def _viz_geoarrow_chunked_array(
     field = ca.field.with_name("geometry")
     schema = Schema([field])
     table = Table.from_arrays([ca], schema=schema)
-
-    num_rows = len(ca)
-    if num_rows <= np.iinfo(np.uint8).max:
-        arange_col = Array(np.arange(num_rows, dtype=np.uint8))
-    elif num_rows <= np.iinfo(np.uint16).max:
-        arange_col = Array(np.arange(num_rows, dtype=np.uint16))
-    elif num_rows <= np.iinfo(np.uint32).max:
-        arange_col = Array(np.arange(num_rows, dtype=np.uint32))
-    else:
-        arange_col = Array(np.arange(num_rows, dtype=np.uint64))
-
-    table = table.append_column("row_index", ChunkedArray([arange_col]))
+    table = add_positional_row_index(table)
     return _viz_geoarrow_table(table, **kwargs)
 
 

lonboard/traits.py

@@ -27,6 +27,8 @@
 from traitlets import TraitError, Undefined
 from traitlets.utils.descriptions import class_of, describe
 
+from lonboard._constants import EXTENSION_NAME
+from lonboard._geoarrow.box_to_polygon import parse_box_encoded_table
 from lonboard._serialization import (
     ACCESSOR_SERIALIZATION,
     TABLE_SERIALIZATION,
@@ -42,7 +44,6 @@
     from traitlets.traitlets import TraitType
     from traitlets.utils.sentinel import Sentinel
 
-    from lonboard._constants import EXTENSION_NAME
     from lonboard._layer import BaseArrowLayer
 
 DEFAULT_INITIAL_VIEW_STATE = {
@@ -198,6 +199,11 @@ def validate(self, obj: BaseArrowLayer, value: Any) -> Table:
 
         # No restriction on the allowed geometry types in this table
         if allowed_geometry_types:
+            # If we allow polygons as input, then we also allow geoarrow.box.
+            # Convert boxes to Polygons
+            if EXTENSION_NAME.POLYGON in allowed_geometry_types:
+                value = parse_box_encoded_table(value)
+
             geometry_extension_type = value.schema.field(geom_col_idx).metadata.get(
                 b"ARROW:extension:name",
             )

pyproject.toml

@@ -88,6 +88,7 @@ dev = [
     "pytest>=8.3.4",
     "ruff>=0.12.0",
     "sidecar>=0.7.0",
+    "types-geopandas>=1.1.1.20250708",
     "types-shapely>=2.1.0.20250512",
 ]
 # Note: this is defined as a separate group so that it can be not installed in

tests/test_box.py

@@ -1,7 +1,7 @@
 import geoarrow.pyarrow as ga
-from arro3.core import Table
+from arro3.core import ChunkedArray, Table
 
-from lonboard import PolygonLayer, SolidPolygonLayer, viz
+from lonboard import Map, PolygonLayer, SolidPolygonLayer, viz
 
 
 def test_viz_box():
@@ -17,6 +17,31 @@ def test_viz_box():
     assert isinstance(m.layers[0], PolygonLayer)
 
 
+def test_box_polygon_layer():
+    arr = ga.box(
+        [
+            "LINESTRING (0 10, 34 -1)",
+            "LINESTRING (10 20, 44 -10)",
+            "LINESTRING (20 40, 54 5)",
+        ],
+    )
+    layer = PolygonLayer(arr)
+    _m = Map(layer)
+
+
+def test_box_polygon_layer_chunked_array():
+    arr = ga.box(
+        [
+            "LINESTRING (0 10, 34 -1)",
+            "LINESTRING (10 20, 44 -10)",
+            "LINESTRING (20 40, 54 5)",
+        ],
+    )
+    ca = ChunkedArray([arr])
+    layer = PolygonLayer(ca)
+    _m = Map(layer)
+
+
 def test_viz_box_polygon_layer():
     arr = ga.box(
         [