AnimatedTextLayer

The AnimatedTextLayer renders time-filtered map labels at point features — each feature's text is drawn from a categorical (string) property column and shown only while the playhead is inside its keyframe window. It draws through deck.gl's TextLayer (@deck.gl/layers), one sublayer per resident tile.

It extends SpatioTemporalLayer. TextLayer does have a binary branch — given data = { length, startIndices, attributes: { getText: { value: Uint8Array | Uint16Array | Uint32Array } } } it derives every label (and the auto character set) straight from the code points, with no per-row JS accessor. So this layer decodes each (tile, layer) pair once (cached by a style digest) into flat typed arrays — a UTF-32 code-point buffer plus per-row char offsets, positions, times, RGBA colors, optional size/angle — and never materializes a per-feature row object. Only the time filter is on the CPU (TextLayer has no per-instance time attribute); the visible subset is handed over as deck's binary getText payload. See How it works.

Installation#

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

Usage#

const layer = new AnimatedTextLayer({
  id: 'place-labels',
  data: '/data/places/manifest.json',
  currentTime,
  timeWindow: 24 * 3600 * 1000,
  textProperty: 'name', // string column drawn as each label
  color: 'category', // categorical column → colorMapping lookup
  colorMapping: {
    city: [255, 255, 255, 255],
    town: [180, 200, 255, 255],
  },
  size: 20,
  background: true,
  getBackgroundColor: [0, 0, 0, 160], // NOT `backgroundColor` — see the note below
  backgroundBorderRadius: 4,
  fontFamily: 'Inter, sans-serif',
});

Properties#

Inherits all properties from SpatioTemporalLayer.

Per-feature JS function accessors are not supported — every styling prop is a constant or a baked column NAME. The upstream getText / getColor / getSize / getAngle names are accepted as aliases with that same value domain; passing a function warns once and falls back to the plain prop. When an alias is set, it wins over its plain counterpart.

Text & Data Accessors#

Layout & Anchoring#

Background & Border#

⚠️ backgroundColor is a name collision, not a pass-through. In upstream deck.gl, TextLayer.backgroundColor is a deprecated alias of a different thing — background + getBackgroundColor combined. Here it is the legacy STT name for the modern getBackgroundColor accessor, and it is forwarded to the sublayer as getBackgroundColor, never as backgroundColor (which would trip deck's deprecation path). If you are reading upstream docs, the prop you want here is getBackgroundColor; use background: true to turn the rectangle on.

SDF Outline#

Font#

characterSet: 'auto' is a deliberate divergence. Upstream TextLayer defaults to ASCII 32–127; STT label columns hold arbitrary text (place names, vessel names, CJK), so 'auto' is the safe default here. And unlike deck's own 'auto' — which re-derives the set from the currently visible rows, handing _updateFontAtlas a fresh Set on every membership change and bumping styleVersion (a full glyph re-layout) each time — this layer derives the exact set from the tile's distinct label values once at decode and reuses that array reference, so the atlas settles after the first update. Pass an explicit set to pin it.

Size System#

Wrapping & Billboard#

Content box (per-label clipping & alignment)#

Time Fades#

How it works#

• Point tiles only: tile layers whose geometryType is not Point are skipped with one named console warning.
• Decode once, filter per frame: each resident (tile, layer) pair is decoded a single time (cached by a style digest) into flat typed arrays — a UTF-32 code-point buffer + per-row char offsets, xyz positions, absolute [start, end] times, RGBA colors, optional size/angle. No per-feature row object is ever built. That set is then filtered on the CPU against the playhead every frame — a row is visible while its absolute [startTime, endTime] overlaps the window [now - timeWindow/2, now + timeWindow/2], the same overlap test the TimeFilterExtension window-mode shader runs.
• Binary search when the tile is sorted: when the tile declares timesSorted, the membership pass is two binary searches over startTimes (widened by the tile's longest feature duration) instead of a full scan.
• Cheap membership signature: the visible set is summarized by a contiguous-run token, or count + first/last + an FNV-1a hash of the indices — never by concatenating indices into a multi-KB string. An early-out reuses the previous frame's prepared payload whenever the signature is unchanged, so updateTriggers.getText (which upstream maps onto updateTriggers.all for the characters sublayer) holds steady and the per-glyph transformParagraph layout does not re-run. Sublayer instances are cached on the same gate, so an unchanged frame costs zero prop diffing.
• GPU time filtering is deferred: TimeFilterExtension cannot compose through TextLayer → MultiIconLayer as a zero-copy attribute — its instanceStartTime/instanceEndTime are per-FEATURE while MultiIconLayer instances are per-CHARACTER, and deck expands a per-object binary buffer across a row's characters only through the accessor auto-updater, which Attribute.setBinaryValue short-circuits past when data.startIndices is the array the layer already reports.
• Fades: when fadeInDuration/fadeOutDuration is active, the appear/disappear ramp is folded into each row's glyph color alpha and applied in lock-step to the background and border colors. The SDF glyph outlineColor is a layer-level uniform and does not fade.
• Picking: getPickingInfo maps a hit's index in the filtered row subset back to the original feature index and decodes that feature's binary columns into info.object.
• The sublayer short id for _subLayerProps overrides is text — one TextLayer per resident (tile, layer) pair.

Source#

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