NormalAccessor (#376)

Adds NormalAccessor and draft tests
Respond to comments on #328 and move recent work here. Branch #328 will
be deleted

---------

Co-authored-by: Kyle Barron <kyle@developmentseed.org>

Author: naomatheus

docs/api/traits.md

@@ -1,11 +1,8 @@
 # lonboard.traits
 
-::: lonboard.traits.PyarrowTableTrait
-
 ::: lonboard.traits.ColorAccessor
-
 ::: lonboard.traits.FloatAccessor
-
-::: lonboard.traits.PointAccessor
-
 ::: lonboard.traits.GetFilterValueAccessor
+::: lonboard.traits.NormalAccessor
+::: lonboard.traits.PointAccessor
+::: lonboard.traits.PyarrowTableTrait

docs/ecosystem/panel.md

@@ -2,7 +2,7 @@
 
 [Panel](https://panel.holoviz.org/) is a tool to build interactive web applications and dashboards using Python code.
 
-Panel [has been reported to work](https://github.com/developmentseed/lonboard/issues/262) with Lonboard. However, it appears that Panel [does not support reactive updates](https://github.com/holoviz/panel/issues/5921) in the same way that [Shiny](./shiny) does, so the map will necessarily be recreated from scratch on every update.
+Panel [has been reported to work](https://github.com/developmentseed/lonboard/issues/262) with Lonboard. However, it appears that Panel [does not support reactive updates](https://github.com/holoviz/panel/issues/5921) in the same way that [Shiny](./shiny.md) does, so the map will necessarily be recreated from scratch on every update.
 
 ## Example
 

lonboard/traits.py

@@ -6,6 +6,7 @@
 
 from __future__ import annotations
 
+import warnings
 from typing import Any, List, Set, Tuple, Union, cast
 
 import matplotlib as mpl
@@ -706,3 +707,107 @@ def validate(self, obj, value) -> Union[float, pa.ChunkedArray, pa.DoubleArray]:
 
         self.error(obj, value)
         assert False
+
+
+class NormalAccessor(FixedErrorTraitType):
+    """
+    A representation of a deck.gl "normal" accessor
+
+    This is primarily used in the [lonboard.PointCloudLayer].
+
+    Acceptable inputs:
+    - A `list` or `tuple` with three `int` or `float` values. This will be used as the
+      normal for all objects.
+    - A numpy ndarray with two dimensions and floating point type. The size of the
+      second dimension must be 3, i.e. its shape must be `(N, 3)`.
+    - a pyarrow `FixedSizeListArray` or `ChunkedArray` containing `FixedSizeListArray`s
+      where the size of the inner fixed size list 3. The child array must have type
+      float32.
+    - Any Arrow array that matches the above restrictions from a library that implements
+      the [Arrow PyCapsule
+      Interface](https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html).
+    """
+
+    default_value = (0, 0, 1)
+    info_text = (
+        "List representing normal of all objects in [nx, ny, nz] or numpy ndarray or "
+        "pyarrow FixedSizeList representing the normal of each object, in [nx, ny, nz]"
+    )
+
+    def __init__(
+        self: TraitType,
+        *args,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self.tag(sync=True, **ACCESSOR_SERIALIZATION)
+
+    def validate(
+        self, obj, value
+    ) -> Union[Tuple[int, ...], List[int], pa.ChunkedArray, pa.FixedSizeListArray]:
+        """
+        Values in acceptable types must be contiguous
+        (the same length for all values)
+        """
+        if isinstance(value, (tuple, list)):
+            if len(value) != 3:
+                self.error(
+                    obj, value, info="normal scalar to have length 3, (nx, ny, nz)"
+                )
+
+            if not all(isinstance(item, (int, float)) for item in value):
+                self.error(
+                    obj,
+                    value,
+                    info="all elements of normal scalar to be int or float type",
+                )
+
+            return value
+
+        if isinstance(value, np.ndarray):
+            if not np.issubdtype(value.dtype, np.number):
+                self.error(obj, value, info="normal array to have numeric type")
+
+            if value.ndim != 2 or value.shape[1] != 3:
+                self.error(obj, value, info="normal array to be 2D with shape (N, 3)")
+
+            if not np.issubdtype(value.dtype, np.float32):
+                warnings.warn(
+                    """Warning: Numpy array should be float32 type.
+                    Converting to float32 point pyarrow array"""
+                )
+                value = value.astype(np.float32)
+
+            return pa.FixedSizeListArray.from_arrays(value.flatten("C"), 3)
+
+        # Check for Arrow PyCapsule Interface
+        # https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html
+        # TODO: with pyarrow v16 also import chunked array from stream
+        if not isinstance(value, (pa.ChunkedArray, pa.Array)):
+            if hasattr(value, "__arrow_c_array__"):
+                value = pa.array(value)
+
+        if isinstance(value, (pa.ChunkedArray, pa.Array)):
+            if not pa.types.is_fixed_size_list(value.type):
+                self.error(
+                    obj, value, info="normal pyarrow array to be a FixedSizeList."
+                )
+
+            if value.type.list_size != 3:
+                self.error(
+                    obj,
+                    value,
+                    info=("normal pyarrow array to have an inner size of 3."),
+                )
+
+            if not pa.types.is_floating(value.type.value_type):
+                self.error(
+                    obj,
+                    value,
+                    info="pyarrow array to be floating point type",
+                )
+
+            return value.cast(pa.list_(pa.float32(), 3))
+
+        self.error(obj, value)
+        assert False

tests/test_traits.py

@@ -9,7 +9,12 @@
 from lonboard._base import BaseExtension
 from lonboard._layer import BaseArrowLayer, BaseLayer
 from lonboard.layer_extension import DataFilterExtension
-from lonboard.traits import ColorAccessor, FloatAccessor, PyarrowTableTrait
+from lonboard.traits import (
+    ColorAccessor,
+    FloatAccessor,
+    NormalAccessor,
+    PyarrowTableTrait,
+)
 
 
 class ColorAccessorWidget(BaseLayer):
@@ -343,3 +348,77 @@ def test_filter_value_validation_filter_size_3():
             np.array([1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=np.float64), 3
         ),
     )
+
+
+class NormalAccessorWidget(BaseLayer):
+    _rows_per_chunk = 2
+
+    table = pa.table({"data": [1, 2, 3]})
+
+    value = NormalAccessor()
+
+
+def test_normal_accessor_validation_list_length():
+    with pytest.raises(TraitError, match="normal scalar to have length 3"):
+        NormalAccessorWidget(value=(1, 2))
+
+    with pytest.raises(TraitError, match="normal scalar to have length 3"):
+        NormalAccessorWidget(value=(1, 2, 3, 4))
+
+    NormalAccessorWidget(value=(1, 2, 3))
+
+
+def test_normal_accessor_validation_list_type():
+    # tuple or list must be of scalar type
+    with pytest.raises(
+        TraitError, match="all elements of normal scalar to be int or float type"
+    ):
+        NormalAccessorWidget(value=["1.1", 2.2, 3.3])
+
+
+def test_normal_accessor_validation_dim_shape_np_arr():
+    arr_size3 = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9]).reshape(-1, 3)
+    arr_size2 = np.array([1, 2, 3, 4, 5, 6]).reshape(-1, 2)
+
+    NormalAccessorWidget(value=arr_size3)
+
+    with pytest.raises(TraitError, match="normal array to be 2D with shape"):
+        NormalAccessorWidget(value=arr_size2)
+
+
+def test_normal_accessor_validation_np_dtype():
+    arr_size3_int = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9]).reshape(-1, 3)
+    arr_size3_float = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=np.float64).reshape(
+        -1, 3
+    )
+
+    NormalAccessorWidget(value=arr_size3_int)
+    NormalAccessorWidget(value=arr_size3_float)
+
+    arr_size3_str = np.array(["1", "2", "3", "4", "5", "6", "7", "8", "9"]).reshape(
+        -1, 3
+    )
+
+    # acceptable data types within a numpy array are float32
+    with pytest.raises(TraitError, match="expected normal array to have numeric type"):
+        NormalAccessorWidget(value=arr_size3_str)
+
+
+def test_normal_accessor_validation_pyarrow_array_type():
+    # array type must be FixedSizeList, of length 3, of float32 type
+    with pytest.raises(
+        TraitError, match="expected normal pyarrow array to be a FixedSizeList"
+    ):
+        NormalAccessorWidget(value=pa.array(np.array([1, 2, 3], dtype=np.float64)))
+
+    np_arr = np.array([1, 2, 3], dtype=np.float32).repeat(3, axis=0)
+    NormalAccessorWidget(value=pa.FixedSizeListArray.from_arrays(np_arr, 3))
+
+    np_arr = np.array([1, 2, 3], dtype=np.float64).repeat(3, axis=0)
+    NormalAccessorWidget(value=pa.FixedSizeListArray.from_arrays(np_arr, 3))
+
+    np_arr = np.array([1, 2, 3], dtype=np.uint8).repeat(3, axis=0)
+    with pytest.raises(
+        TraitError, match="expected pyarrow array to be floating point type"
+    ):
+        NormalAccessorWidget(value=pa.FixedSizeListArray.from_arrays(np_arr, 3))