AnimatedPathLayer

The AnimatedPathLayer renders time-series path/trajectory data as lines. It extends SpatioTemporalLayer and provides GPU-accelerated time filtering.

It operates in window mode by default: each feature is shown (with optional fade) whenever its [startTime, endTime] overlaps the current time window — whole paths render at once. Set revealTrail for a progressive per-vertex reveal (see Reveal (trail) mode), or use AnimatedTripsLayer when the archive carries real per-vertex times.

Installation#

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

Usage#

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

const layer = new AnimatedPathLayer({
  id: 'ship-tracks',
  data: 'https://example.com/ships/manifest.json',
  currentTime: 1672531200000,
  timeWindow: 3600000, // 1 hour
  pathColor: [0, 150, 255, 255],
  pathWidth: 3,
});

Properties#

Inherits all properties from SpatioTemporalLayer.

Render Options#

Reveal (trail) mode#

Data Accessors#

Closed rings (pathType)#

'open' (the default) draws a START_CAP at a feature's first vertex and an END_CAP at its last. On CLOSED geometry — contour rings, lane loops, footprints baked as LineStrings — that leaves a visible notch at the ring seam where a mitred joint belongs. pathType: 'loop' closes the joint instead.

⚠️ 'loop' is not a drop-in for arbitrary tiles, for two reasons:

1. It is tile-WIDE, not per-feature. STT tiles feed PathLayer binary data (normalize: false), and its tessellator then reads closedness from the loop flag alone rather than comparing each path's endpoints. Every feature in every tile is treated as closed — so only set it for datasets that are all rings.
2. The buffer must already carry the +2 wrap vertices. For a closed path the tessellator expects numPoints + 2 vertices — the ring followed by a repeat of its first TWO vertices (B0 B1 B2 B3 B0 B1) — and it reads that padding out of the tile's own positions/startIndices; the binary path never synthesizes it. A ring baked in the usual first-vertex-repeated-last form does not satisfy this and renders a short, mis-capped final segment. The layer checks the tile's buffers for the padding and warns once when it is missing.

Elevation (space-time relief)#

A path layer is normally flat: every vertex rides the tile's ground-plane z. Setting elevationProperty lifts each feature (the whole path, not individual vertices) to a per-feature altitude, turning a set of flat rings — most usefully nested density iso-contours — into a 3D terraced relief, the classic stacked contour plot. Combined with elevationOpacityRange, the upper terraces can also be graded translucent so a top-down camera sees through the roof to the layers underneath instead of the topmost band occluding everything below it.

Together they produce a readable 3D iso-surface from one dataset:

new AnimatedPathLayer({
  pathColor: 'band',
  colorMapping: { low: [40, 90, 180, 255], high: [220, 60, 40, 255] },
  elevationProperty: 'band_value',
  elevationScale: 50,
  elevationOpacityRange: [0, 10],
  elevationOpacityFar: 0.35,
});

Architecture & performance#

• Geometry-kind guard: tile layers whose geometryType is not LineString are skipped with one named console warning, rather than misreading the position buffer (a point tile's featureCount positions are not a vertex run). Tiles predating the geometry-kind tag are trusted.
• Per-tile binary sublayers: one PathLayer per (tile, layer) pair using the binary data: { length, startIndices, attributes } interface; typed arrays reference the tile's Arrow buffers zero-copy. New tiles are additive — one sublayer, one GPU upload.
• Sublayer + prepared-data caches with content-keyed style digests, so unchanged tiles short-circuit deck.gl's prop diff entirely.
• Per-tile timeOffset through a window-mode TimeFilterExtension; time updates flow via getTime() per draw (no layer recreation per frame).
• Categorical color on the CPU: PathLayer instances are SEGMENTS, so CategoryColorExtension's per-FEATURE instanceCategoryIndex would under-size the draw. colorPalette / colorMapping are instead resolved per tile and expanded into a per-vertex getColor RGBA buffer at prepare time (cached, never on the draw path). The extension is not installed at all, which also frees a vertex-attribute slot.
• Picking and the attribute budget: counting in declarations in deck.gl 9.3's shipped PathLayer vertex shader — stock PathLayer 13, NoPickingPathLayer 12 (picking colors stripped), + TimeFilterExtension 3,
  • STTDataFilterExtension 1 — the four combinations are 15 (default), 16 (filterProperty), 16 (pickable) and 17 (filterProperty + pickable). Only the last exceeds WebGL2's guaranteed 16-slot floor and can fail to link (blank paths) on GPUs that report exactly 16; the layer warns once for exactly that combination. Prefer pickable: false when filtering, or filter with AnimatedPointLayer.

The sublayer short id for _subLayerProps overrides is paths. Without a type override the class is PathLayer when pickable, NoPickingPathLayer otherwise.

Source#

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