AnimatedPointLayer

The AnimatedPointLayer renders time-series point data as circles. It extends SpatioTemporalLayer and provides GPU-accelerated time filtering (window, wake, and cumulative modes) with support for categorical coloring.

Installation#

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

Usage#

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

const layer = new AnimatedPointLayer({
  id: 'earthquakes',
  data: 'https://example.com/earthquakes/manifest.json',
  currentTime: 1672531200000,
  timeWindow: 3600000, // 1 hour
  fillColor: [255, 128, 0, 255],
  radius: 5,
  radiusScale: 2,
  radiusUnits: 'meters',
});

With Categorical Coloring#

const layer = new AnimatedPointLayer({
  id: 'flights',
  data: 'https://example.com/flights/manifest.json',
  currentTime: Date.now(),
  timeWindow: 3600000,
  fillColor: 'airline', // categorical property name → GPU palette lookup
  colorPalette: [
    [31, 119, 180, 255],
    [255, 127, 14, 255],
    [44, 160, 44, 255],
  ],
  radius: 'altitude', // numeric property name → per-feature radius
});

Wake mode (ship-wake aesthetic)#

const layer = new AnimatedPointLayer({
  id: 'vessels',
  data: '/data/ais/manifest.json',
  currentTime,
  wakeLength: 30 * 60 * 1000, // 30 min comet tail behind each point
  wakeTailScale: 0.15,
  timeWindow: 60 * 60 * 1000, // must be >= 2 × wakeLength (loader window)
});

Cumulative mode ("the map draws itself")#

const layer = new AnimatedPointLayer({
  id: 'osm-nodes',
  data: '/data/osm-nyc/manifest.json',
  currentTime,
  cumulative: true,
  fadeInDuration: 500, // appear ramp
  timeWindow: WHOLE_DATASET_MS, // keep revealed tiles resident
});

Properties#

Inherits all properties from SpatioTemporalLayer.

Render Options#

Mode Options#

Glide (motion interpolation)#

Point archives carry one row per entity per sample, so a GPU time-window filter shows every sample in the window at once and a moving entity POPS between them. Glide instead pools the loaded samples by idProperty and emits one CPU-interpolated pose per active entity per frame.

Data Accessors#

Accessor aliases. The upstream get* names accept a constant or a property-column name — not a function accessor, since binary tiles cannot run per-feature JS. A function warns once and falls back to the plain prop.

Deliberate default drift#

Three defaults intentionally differ from upstream ScatterplotLayer. Porting a deck config that relied on the upstream values will look different until these are passed explicitly.

Note that lineWidthUnits does not drift — it keeps deck's 'meters', which is why it differs from radiusUnits in this same layer.

Color precedence. colorVectorColumn wins over everything, then rgbColorColumns, then rampProperty (the continuous ramp), then colorMapping/colorPalette (categorical), then a constant fillColor. Every column path falls through to the next when its column is absent from a tile. The ramp is not applied on the CPU glide (interpolate) path, which colors per-track.

colorMapping is the only way to get stable colors across tiles whose categorical column contains different category subsets — the GPU palette texture cannot look up by string, so setting it forces CPU palette expansion.

rgbColorColumns reads three numeric columns (each 0–255) as [r, g, b, 255], e.g. LIDAR returns colored by projecting them into camera images at build time (waymo_extract.py --colorize). Alpha comes from layer opacity.

colorVectorColumn reads one interleaved column baked by stt-build --vector-group point_rgba=r,g,b,a:u8 and binds the contiguous u8 buffer to getFillColor zero-copy — the GPU-ready analogue of rgbColorColumns. It defaults off on this layer because a truthy default would silently shadow an explicit fillColor on any tile that happened to carry the column; AnimatedPointCloudLayer defaults it to 'point_rgba'.

In cumulative mode a property-column strokeWidth is ignored (slabs don't pack stroke widths); the constant branch still applies.

Column filter#

Wires a baked numeric column into STTDataFilterExtension. Points whose value falls inside filterRange render; the rest are hidden, or soft-faded via filterSoftRange. It composes with the time filter — a point must pass both.

filterProperty is the accessor-alias of deck's getFilterValue: pass a column name, not a function (a function warns once and is ignored). Leaving it unset means the extension is never installed — zero cost. A categorical column cannot be range-filtered and warns once. The filter is ignored in cumulative mode, where slabs bake a fixed schema.

A null filterRange keeps the column bound with no active range, so a range set later animates purely by uniform with no tile re-preparation. filterSoftRange and filterEnabled have no effect unless filterProperty (and for the former, filterRange) is set.

3D props#

Tile geometry is 2D lon/lat. With elevationProperty set, each point's z is baked as column[i] * elevationScale into the position buffer at tile-prepare time, on both the per-tile sublayer path and the cumulative slab path. Negative and zero values pass through unchanged (below-grade to rooftop LIDAR returns). Left unset, z stays 0 — byte-identical to a flat 2D render.

3D is otherwise inferred automatically: tiles whose positionDimensions is 3 ride their z zero-copy, and 2D tiles are padded with z=0 (or the elevationProperty-baked z). There is no separate "3D mode" to opt into beyond setting elevationProperty for 2D tiles, or building the archive with 3D positions in the first place.

Architecture & performance#

• Geometry-kind guard: tile layers whose geometryType is not Point are skipped with one named console warning. geometryType is the only thing that distinguishes a point tile from a linestring tile once the columns are decoded — this layer would otherwise read the first featureCount vertices of a flattened vertex run as one position per feature: no error, no blank map, just points silently bunched along the first few paths. Tiles predating the geometry-kind tag are trusted, not rejected.
• Cumulative slabs: in cumulative mode points pack append-only into consolidated slabs rather than one sublayer per tile, which is why a property-column strokeWidth and filterProperty are ignored there (see Data Accessors and Column filter).

The sublayer short id for _subLayerProps overrides is points (covers both per-tile and slab sublayers): _subLayerProps: { points: { type: MyLayer, ... } }.

Source#

packages/layers/src/layers/core/animated-point-layer.ts