AnimatedBoundingBoxLayer

The AnimatedBoundingBoxLayer renders one smooth-moving oriented 3D box per tracked object — the streetscape.gl / avs.auto tracked-object look, and the AV-cockpit detected-object overlay. The tile archive carries one POINT feature per object per keyframe (a snapshot: track_id, category, heading, length/width/height, speed, timestamped). The layer pools every loaded tile's keyframes by track_id and, once per frame, CPU-interpolates each active track's pose between the two keyframes bracketing the playhead — so an object glides continuously instead of leaving a "train" of one box per keyframe behind it.

It extends SpatioTemporalLayer, but unlike its window-mode siblings it does not use the TimeFilterExtension: a track's visibility is implicit (it only produces a sample while the playhead lies inside its keyframe span), so there is no window/trail uniform to configure. timeWindow still governs which tile buckets stay resident — it only needs to cover roughly one keyframe gap so both bracketing keyframes are loaded.

How a box is posed#

• Position — the interpolated point (lon/lat/alt) between the two bracketing keyframes.
• Orientation — the headingProperty column (radians, 0 = +x/east, CCW), angle-interpolated the shortest way around the ±π seam, becomes getOrientation: [0, heading°, 0] — a yaw about the vertical axis (slot 1 of deck.gl SimpleMeshLayer's [pitch, yaw, roll]). With no heading column, or NaN at both keyframes, boxes are axis-aligned.
• Scale — [length, width, height] (meters) → getScale × 0.5 × sizeScale. CubeGeometry spans ±1, so the ×0.5 makes one scale unit one meter.
• Ground anchor — each box is lifted by height / 2 × sizeScale (getTranslation z) so its base rests on the ground rather than straddling it.
• Color — the colorProperty category is resolved on the CPU through colorMapping into a per-instance RGBA getColor attribute, applied before the mesh's phong lighting so the box faces still read as a lit 3D volume (a GPU color extension would write after lighting and flatten it). The color is multiplied by a CPU appear/disappear fade driven by fadeInDuration/fadeOutDuration.

The optional 12-edge outline (stroked), labels (showLabels), and velocity arrows (showVelocity) are built from the same interpolated pose — see How it works.

Installation#

import { AnimatedBoundingBoxLayer } from '@poopdeck.gl/layers';

Usage#

const layer = new AnimatedBoundingBoxLayer({
  id: 'detected-objects',
  data: '/data/av-scene/objects/manifest.json',
  currentTime,
  timeWindow: 200, // ms — tile-loading window, not per-box visibility
  colorProperty: 'category',
  colorMapping: {
    car: [80, 170, 255, 255],
    pedestrian: [255, 90, 90, 255],
    bicycle: [255, 200, 60, 255],
  },
  sizeScale: 1,
});

Feed it the AV-cockpit objects/ point archive (one snapshot per tracked object per keyframe, with a track_id column). When a tile lacks length/width/height columns, boxes fall back to the constant defaultLength/defaultWidth/defaultHeight.

streetscape.gl detection-box look (outline + labels + velocity)#

const layer = new AnimatedBoundingBoxLayer({
  id: 'detected-objects',
  data: '/data/av-scene/objects/manifest.json',
  currentTime,
  filled: false,
  stroked: true,
  colorProperty: 'category',
  colorMapping: { car: [80, 170, 255, 255], pedestrian: [255, 90, 90, 255] },
  showLabels: true,
  showVelocity: true,
});

filled: false together with stroked: true gives the classic outline-only box you can see the LIDAR through. showLabels and showVelocity add a per-object category label and speed/heading arrow, each only for objects currently active.

Properties#

Inherits all properties from SpatioTemporalLayer.

Identity & color#

Pose & geometry#

Fill & outline#

Labels#

Label appearance is fixed — 11 px white glyphs with a 2 px dark SDF outline, anchored bottom-center 16 px above the box. Override it through deck's composite escape hatch, e.g. _subLayerProps: { labels: { getSize: 14, getColor: [255, 220, 80, 255] } }.

Velocity arrows#

How it works#

1. Cross-tile pooling — a track's keyframes are spread across temporal-bucket tiles (e.g. a 1s bucket at 2Hz holds ~2 of them), so the two keyframes bracketing the playhead can live in adjacent tiles. Every loaded tile's snapshots are grouped by trackIdProperty, with each keyframe's time rebased to absolute epoch-ms (startTime + tile.timeOffset) so snapshots from tiles with different timeOffsets sort into one timeline. The pooled, track-grouped index is rebuilt only when the visible tile set changes (or a style prop that feeds it changes) — not every frame.
2. Per-frame interpolation — for every track active at the playhead, a binary search finds the two bracketing keyframes and linearly interpolates position, dimensions, and speed; heading is interpolated the shortest way around the ±π seam. Missing dimension/heading/speed columns fall back to the default* props (or axis-aligned, for heading).
3. Implicit visibility & fade — a track only produces a sample while the playhead lies within its keyframe span; there is no separate time-filter window to configure. Just inside the start/end of that span, fadeInDuration/fadeOutDuration ramp the box's alpha from/to zero. A track with only one loaded keyframe (nothing to interpolate against) is instead held, un-interpolated, for ±300ms around that keyframe.
4. Sublayers — every enabled sublayer is rebuilt from the same per-frame active-track samples, so they appear and vanish together with their object:
   • boxes — a SimpleMeshLayer (@deck.gl/mesh-layers) instancing a unit CubeGeometry, one instance per active box (when filled).
   • edges — a LineLayer of each box's 12 true edges, computed from the same interpolated pose (when stroked).
   • labels — a TextLayer of each active object's labelProperty value, billboarded above the box (when showLabels).
   • velocity — a LineLayer velocity arrow per active object, from its interpolated speedProperty + headingProperty (when showVelocity).
5. Redraw — the layer forces a renderLayers() pass every frame (like AnimatedTripHeadsLayer) so the CPU-computed instance buffers advance; the base class's shader-uniform redraw path never runs for this layer.

Cost scales with the number of active tracks over the visible tiles (AV scenes carry tens of active objects and a few thousand snapshots per scene) — a binary-search + lerp per active track, well under a millisecond per frame.

Picking#

At most one sublayer carries picking: boxes when filled, otherwise edges when stroked (a solid box is easier to click than a thin edge, so fill wins when both are on). labels and velocity are never pickable. Nothing ever forces picking on — that choice only decides which sublayer may inherit the composite's own pickable, so pickable: false on the layer really does let clicks fall through. A hit's info.object is set to that track's flat decoded props — track_id, category, heading, length, width, height, speed — the shape the AV cockpit's click-to-inspect handler reads.

Source#

packages/layers/src/layers/core/animated-bounding-box-layer.ts