AnimatedIconLayer

The AnimatedIconLayer renders directional markers at point features, rotated per-feature by a heading column — the natural fit for moving objects like AIS vessels (cog) or aircraft (heading). It draws through deck.gl's IconLayer (@deck.gl/layers), one binary sublayer per tile, animated window-mode by the shared TimeFilterExtension.

It extends SpatioTemporalLayer and follows the same instanced-at-points pattern as AnimatedPointLayer. Rotation, color, and size are full instanced attributes. The sprite itself is constant by default, but setting iconProperty keys it off a categorical column: the layer bakes the per-feature instanceIconDefs buffer itself — one iconMapping lookup per distinct category, then a typed-array fill — which bypasses deck's per-row getIcon accessor that binary tiles cannot run.

Installation#

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

Usage#

const layer = new AnimatedIconLayer({
  id: 'vessels',
  data: '/data/ais/manifest.json',
  currentTime,
  timeWindow: 24 * 3600 * 1000,
  iconAtlas: '/icons/arrow-atlas.png',
  iconMapping: { arrow: { x: 0, y: 0, width: 64, height: 64, mask: true } },
  icon: 'arrow',
  angle: 'cog', // rotate by the heading column (degrees, CCW)
  color: [80, 200, 255, 255],
  size: 16,
});

Properties#

Inherits all properties from SpatioTemporalLayer.

Stable categorical color#

Wake mode#

Column range filter#

Wires a baked numeric column into STTDataFilterExtension. Icons whose value falls inside filterRange render; the rest are hidden, or soft-faded via filterSoftRange. It composes with the time filter — an icon 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 not installed at all — zero attribute, zero uniform, zero shader change. A tile lacking the named column renders unfiltered; a tile where the column is categorical warns once and idles (v1 range-filters numeric columns only). The filter applies to the discrete window path — the glide path below filters by activity instead.

Motion interpolation (glide)#

Icon 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 marker pops. Glide pools the loaded tiles' samples by idProperty and emits one icon per active entity per frame, with position and heading CPU-interpolated between the samples bracketing the playhead.

Per-category icons#

Set iconProperty to a categorical column name and each feature gets its own sprite, mirroring how color keys a category column:

const layer = new AnimatedIconLayer({
  iconAtlas: '/icons/transport-atlas.png',
  iconMapping: {/* object form required */},
  iconProperty: 'vessel_type',
  iconCategoryMapping: { cargo: 'ship', tanker: 'tanker', tug: 'boat' },
  icon: 'marker', // fallback for categories the map misses
});

• The column value is resolved to an icon name through iconCategoryMapping when set; otherwise the category value is the icon name (a key of iconMapping).
• Categories absent from iconCategoryMapping fall back to icon. A resolved icon name absent from iconMapping falls back to iconMapping[icon]; only when that is missing too does the feature render a zero-size (invisible) sprite, matching deck's own MISSING_ICON behaviour — and the layer warns once, naming the unmapped icon.
• Requires an object iconMapping (a URL string warns once and falls back).
• Ignored on the glide (interpolate) path, which re-emits one pose per entity and has no per-sample category to read.
• Unset (the default) ⇒ every feature uses the constant icon and no instanceIconDefs attribute is baked.

Two load-options props#

iconLoadOptions is deliberately separate from the base SpatioTemporalLayer loadOptions:

• loadOptions (SttLoadOptions, inherited) — HTTP for the archive: manifest, directory, pack ranges.
• iconLoadOptions — loaders.gl options for the icon atlas fetch, reaching deck's IconManager as the sublayer's loadOptions.

CompositeLayer.getSubLayerProps does not forward loadOptions, so overloading one prop for both would either break archive loading or leak archive auth headers to a third-party atlas host.

Behavior notes#

• Heading convention: IconLayer.getAngle is degrees counter-clockwise from the icon's up orientation; compass headings (CW from north) may need 360 - heading baked into the source column.
• Point tiles only: tile layers whose geometryType is not Point are skipped with one named console warning rather than misread as one position per feature.
• The sublayer short id for _subLayerProps overrides is icons.

Source#

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