Implement TripsLayer for animating moving objects and connect to MovingPandas

lonboard/__init__.py

@@ -2,7 +2,7 @@
 Python library for fast, interactive geospatial vector data visualization in Jupyter.
 """
 
-from . import colormap, controls, layer_extension, traits
+from . import colormap, controls, experimental, layer_extension, traits
 from ._layer import (
     BaseArrowLayer,
     BaseLayer,

lonboard/experimental/__init__.py

@@ -4,4 +4,4 @@
 unexpected behavior when using them.
 """
 
-from ._layer import ArcLayer, TextLayer
+from ._layer import ArcLayer, TextLayer, TripsLayer

lonboard/experimental/_layer.py

@@ -5,17 +5,45 @@
 
 from __future__ import annotations
 
+import sys
+from typing import TYPE_CHECKING, Optional
+
+import numpy as np
 import traitlets
+from arro3.core import (
+    Array,
+    ChunkedArray,
+    Field,
+    Table,
+    fixed_size_list_array,
+    list_array,
+)
+from arro3.core.types import ArrowStreamExportable
 
 from lonboard._constants import EXTENSION_NAME
 from lonboard._layer import BaseArrowLayer
+from lonboard.experimental.traits import TimestampAccessor
 from lonboard.traits import (
     ArrowTableTrait,
     ColorAccessor,
     FloatAccessor,
     PointAccessor,
     TextAccessor,
 )
+from lonboard.types.layer import TripsLayerKwargs
+
+if TYPE_CHECKING:
+    from movingpandas import TrajectoryCollection
+
+    if sys.version_info >= (3, 11):
+        from typing import Self
+    else:
+        from typing_extensions import Self
+
+    if sys.version_info >= (3, 12):
+        from typing import Unpack
+    else:
+        from typing_extensions import Unpack
 
 
 class ArcLayer(BaseArrowLayer):
@@ -329,3 +357,216 @@ class TextLayer(BaseArrowLayer):
     default [0, 0]
     """
     #  ?: Accessor<DataT, [number, number]>;
+
+
+class TripsLayer(BaseArrowLayer):
+    """ """
+
+    _layer_type = traitlets.Unicode("trip").tag(sync=True)
+
+    table = ArrowTableTrait(
+        allowed_geometry_types={
+            EXTENSION_NAME.LINESTRING,
+        }
+    )
+
+    width_units = traitlets.Unicode(default_value=None, allow_none=True).tag(sync=True)
+    """
+    The units of the line 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'`
+    """
+
+    width_scale = traitlets.Float(default_value=None, allow_none=True, min=0).tag(
+        sync=True
+    )
+    """
+    The path width multiplier that multiplied to all paths.
+
+    - Type: `float`, optional
+    - Default: `1`
+    """
+
+    width_min_pixels = traitlets.Float(default_value=None, allow_none=True, min=0).tag(
+        sync=True
+    )
+    """
+    The minimum path width in pixels. This prop can be used to prevent the path from
+    getting too thin when zoomed out.
+
+    - Type: `float`, optional
+    - Default: `0`
+    """
+
+    width_max_pixels = traitlets.Float(default_value=None, allow_none=True, min=0).tag(
+        sync=True
+    )
+    """
+    The maximum path width in pixels. This prop can be used to prevent the path from
+    getting too thick when zoomed in.
+
+    - Type: `float`, optional
+    - Default: `None`
+    """
+
+    joint_rounded = traitlets.Bool(default_value=None, allow_none=True).tag(sync=True)
+    """
+    Type of joint. If `True`, draw round joints. Otherwise draw miter joints.
+
+    - Type: `bool`, optional
+    - Default: `False`
+    """
+
+    cap_rounded = traitlets.Bool(default_value=None, allow_none=True).tag(sync=True)
+    """
+    Type of caps. If `True`, draw round caps. Otherwise draw square caps.
+
+    - Type: `bool`, optional
+    - Default: `False`
+    """
+
+    miter_limit = traitlets.Int(default_value=None, allow_none=True).tag(sync=True)
+    """
+    The maximum extent of a joint in ratio to the stroke width.
+    Only works if `jointRounded` is `False`.
+
+    - Type: `float`, optional
+    - Default: `4`
+    """
+
+    billboard = traitlets.Bool(default_value=None, allow_none=True).tag(sync=True)
+    """
+    If `True`, extrude the path in screen space (width always faces the camera).
+    If `False`, the width always faces up.
+
+    - Type: `bool`, optional
+    - Default: `False`
+    """
+
+    fade_trail = traitlets.Bool(default_value=None, allow_none=True).tag(sync=True)
+    """Whether or not the path fades out.
+
+    - Type: `bool`, optional
+    - Default: `True`
+    """
+
+    trail_length = traitlets.Float(default_value=None, allow_none=True).tag(sync=True)
+    """Trail length.
+
+    - Type: `float`, optional
+    - Default: `120`
+    """
+
+    current_time = traitlets.Float(0).tag(sync=True)
+    """The current time of the frame.
+
+    - Type: `float`, optional
+    - Default: `0`
+    """
+
+    get_color = ColorAccessor(None, allow_none=True)
+    """
+    The color of each path 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 color for all
+          paths.
+        - If a numpy or pyarrow array is provided, each value in the array will be used
+          as the color for the path at the same row index.
+    - Default: `[0, 0, 0, 255]`.
+    """
+
+    get_width = FloatAccessor(None, allow_none=True)
+    """
+    The width of each path, in units specified by `width_units` (default `'meters'`).
+
+    - Type: [FloatAccessor][lonboard.traits.FloatAccessor], optional
+        - If a number is provided, it is used as the width for all paths.
+        - If an array is provided, each value in the array will be used as the width for
+          the path at the same row index.
+    - Default: `1`.
+    """
+
+    get_timestamps = TimestampAccessor(None, allow_none=True)
+    """
+    The timestamp of each coordinate.
+
+    - Type: [TimestampAccessor][lonboard.traits.TimestampAccessor]
+    """
+
+    def __init__(
+        self,
+        *,
+        table: ArrowStreamExportable,
+        get_timestamps: ArrowStreamExportable,
+        _rows_per_chunk: Optional[int] = None,
+        **kwargs: Unpack[TripsLayerKwargs],
+    ):
+        super().__init__(
+            table=table,
+            _rows_per_chunk=_rows_per_chunk,
+            get_timestamps=get_timestamps,  # type: ignore
+            **kwargs,
+        )
+
+    @classmethod
+    def from_movingpandas(
+        cls,
+        traj_collection: TrajectoryCollection,
+        **kwargs: Unpack[TripsLayerKwargs],
+    ) -> Self:
+        import shapely
+
+        num_coords = 0
+        num_rows = len(traj_collection)
+        offsets = np.zeros(num_rows + 1, dtype=np.int32)
+
+        for i, traj in enumerate(traj_collection.trajectories):
+            num_coords += traj.size()
+            offsets[i + 1] = num_coords
+
+        coords = np.zeros((num_coords, 2), dtype=np.float64)
+        timestamps = np.zeros(num_coords, dtype=np.int64)
+
+        for i, traj in enumerate(traj_collection.trajectories):
+            start_offset = offsets[i]
+            end_offset = offsets[i + 1]
+
+            # millisecond-based timestamps
+            int64_ms_timestamps = traj.df.index.to_series().astype(np.int64) // (
+                1000**2
+            )
+            timestamps[start_offset:end_offset] = int64_ms_timestamps
+
+            coords[start_offset:end_offset, 0] = shapely.get_x(traj.df.geometry).values
+            coords[start_offset:end_offset, 1] = shapely.get_y(traj.df.geometry).values
+
+        # offset by earliest timestamp
+        timestamps -= timestamps.min()
+
+        # Cast to float32
+        timestamps = timestamps.astype(np.float32)
+
+        coords_arr = Array.from_numpy(coords.ravel("C"))
+        coords_fixed_size_list = fixed_size_list_array(coords_arr, 2)
+        linestrings_arr = list_array(Array.from_numpy(offsets), coords_fixed_size_list)
+        timestamp_arr = list_array(
+            Array.from_numpy(offsets), Array.from_numpy(timestamps)
+        )
+        timestamp_col = ChunkedArray([timestamp_arr])
+
+        linestrings_field = Field(
+            "geometry",
+            linestrings_arr.type,
+            nullable=True,
+            metadata={"ARROW:extension:name": "geoarrow.linestring"},
+        )
+
+        # TODO: don't add timestamps onto table
+        table = Table.from_pydict({"timestamps": timestamp_col})
+        table = table.append_column(linestrings_field, ChunkedArray([linestrings_arr]))
+        return cls(table=table, get_timestamps=timestamp_col, **kwargs)

lonboard/experimental/traits.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Any, Union
+
+from arro3.core import Array, ChunkedArray, DataType
+from traitlets.traitlets import TraitType
+
+from lonboard._serialization import ACCESSOR_SERIALIZATION
+from lonboard.traits import FixedErrorTraitType
+
+
+class TimestampAccessor(FixedErrorTraitType):
+    """A representation of a deck.gl coordinate-timestamp accessor.
+
+    - A pyarrow [`ListArray`][pyarrow.ListArray] containing either a numeric array. Each
+        value in the array will be used as the value for the object at the same row
+        index.
+    - Any Arrow list array from a library that implements the [Arrow PyCapsule
+      Interface](https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html).
+    """
+
+    default_value = None
+    info_text = "a Arrow ListArray representing a nested array of timestamps"
+
+    def __init__(
+        self: TraitType,
+        *args,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self.tag(sync=True, **ACCESSOR_SERIALIZATION)
+
+    def validate(self, obj, value) -> Union[Array, ChunkedArray]:
+        # Check for Arrow PyCapsule Interface
+        if hasattr(value, "__arrow_c_array__"):
+            value = Array.from_arrow(value)
+
+        elif hasattr(value, "__arrow_c_stream__"):
+            value = ChunkedArray.from_arrow(value)
+
+        if isinstance(value, (ChunkedArray, Array)):
+            if not DataType.is_list(value.type):
+                self.error(obj, value, info="timestamp array to be a list-type array")
+
+            return value
+
+        self.error(obj, value)
+        assert False