AnimatedPolygonLayer

The AnimatedPolygonLayer renders time-series polygon data (e.g., county boundaries, zones). It extends SpatioTemporalLayer and provides GPU time-based visibility filtering for polygon features, with one SolidPolygonLayer sublayer per tile.

Installation#

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

Usage#

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

const layer = new AnimatedPolygonLayer({
  id: 'covid-counties',
  data: 'https://example.com/covid-counties/manifest.json',
  currentTime: 1672531200000,
  timeWindow: 86400000 * 30, // 30 days
  fillColor: 'status', // categorical property name
  colorPalette: [
    [255, 255, 178, 180],
    [254, 204, 92, 180],
    [253, 141, 60, 180],
    [240, 59, 32, 180],
    [189, 0, 38, 180],
  ],
});

Properties#

Inherits all properties from SpatioTemporalLayer.

Render Options#

Data Accessors#

Floating extrusions#

deck's SolidPolygonLayer extrudes from the polygon's own vertex z (pos.z += elevations * elevationScale), and STT polygon geometry is 2D, so a plain extruded polygon is always a prism standing on the ground. When the elevation column describes a surface in the air — a cloud-top height, a sea surface, a canopy — that prism hangs a full-height curtain from the basemap up to the surface, and the shape reads as a wall rather than a sheet.

baseElevation and elevationThickness give the extrusion a floor, so the walls span exactly [floor, elevation]:

new AnimatedPolygonLayer({
  extruded: true,
  elevation: 'top_alt_m', // metres MSL, per feature
  elevationThickness: 300, // 300 m-thick shell hugging each band's own top
  elevationScale: 4, // shared vertical exaggeration
});

• elevationThickness hugs each feature's own top, so nested bands read as separate floating shelves you can see between. Use it for data that carries only a top surface.
• baseElevation sets an absolute floor: a constant gives every polygon the same base (nested bands fuse into one terraced mesa), a column name gives each feature its own (a true base-to-top slab, e.g. a cloud base).

The floor is baked into the tile's vertex z once per tile, pre-multiplied by elevationScale (the shader scales only the thickness above the floor), and elevation is rewritten to top - floor. Two consequences: the tile pays one 1.5× position-buffer copy instead of the zero-copy geometry path, and elevationScale re-prepares tiles instead of being a live uniform — so animate it only on layers that are not floating. An inverted floor (base > top) clamps to zero thickness rather than extruding downward. With stroked: true the outline rides the floor plane.

Outline pass#

Set stroked: true to draw an outline. This emits a second sublayer per tile — a NoPickingPathLayer on the polygon ring geometry (_pathType: 'loop'), drawn over the fill. The outline is only constructed when stroked is true. For a standalone outline with no fill, set filled: false and stroked: true. The outline is never a pick target — it renders with pickable: false regardless of the layer's own pickable; picking resolves against the fill.

One path per RING. The outline is fed from the tile's ringIndices — the per-ring vertex offsets the decoder surfaces alongside the feature-level startIndices — so holes and MultiPolygon parts are each outlined, and no bridge segment is drawn from a polygon's exterior into its first hole. Archives predating the ringIndices column fall back to startIndices, i.e. one loop per feature.

stroked and extruded. Following upstream PolygonLayer, the stroke is ignored for ground-anchored extrusion: an extruded polygon's ring stroke stays at the geometry's own z, which for STT's 2D polygon geometry is 0 — a ghost ring lying on the basemap under each prism. The one deliberate divergence is floating extrusion (baseElevation / elevationThickness), which lifts the vertices themselves to the floor plane: there the outline rides the slab with the fill and is kept. When the fill is extruded the outline is emitted before it (upstream's extruded ordering), so translucent slabs blend the way deck's do; for a flat fill the outline is emitted after, drawing on top.

Geometry interpretation (escape hatches)#

These are SolidPolygonLayer pass-throughs whose defaults are the zero-copy tile path. Changing either of the last two is a per-dataset decision, not a styling knob.

Space-time cube#

timeHeightOrigin (the absolute time mapped to altitude 0) is inherited from SpatioTemporalLayer.

Column range filter#

Installs STTDataFilterExtension when — and only when — filterProperty is set; unset means zero attribute, zero uniform, zero shader change. The per-feature value is expanded per-vertex like the time attributes, so a polygon filters as a whole; the stroked outline reuses the same buffer and clips/fades in lock-step with the fill. Composes with the time filter and the categorical fill path (SolidPolygonLayer's non-instanced fill has attribute headroom the tight PathLayer family does not).

Deliberate default drift#

Two defaults intentionally differ from upstream deck.gl's composite PolygonLayer:

Architecture & performance#

• Geometry-kind guard: before preparing a tile the layer checks the tile layer's geometryType and skips any layer that is not Polygon, emitting one named console warning. startIndices alone does not identify a polygon tile — LineString tiles carry it too, and used to sail into this path to be tesselated as degenerate polygons. Tiles that predate the geometry-kind tag (geometryType: undefined) are trusted, not rejected.
• Categorical fill, flat vs extruded: with extruded: false (the default) categorical fills lift to the GPU via CategoryColorExtension at zero CPU cost. With extruded: true the palette is instead expanded on the CPU into a per-vertex getFillColor buffer (4 bytes/vertex, once per tile prep). SolidPolygonLayer computes phong lighting in the vertex shader and the fragment shader only forwards it, so the extension's DECKGL_FILTER_COLOR hook — which replaces rgb — would discard the lighting and render every prism flat and unlit. Feeding the color in through the attribute puts it where deck's own getFillColor accessor would have, so lighting survives.
• Pre-baked triangles (MLT-style): when the tile carries a triangles index buffer it feeds SolidPolygonLayer directly through the binary indices attribute, skipping deck.gl's CPU earcut at tile-arrival time entirely. Sublayers run with _normalize: false by default, so deck's re-normalization pass is bypassed either way. This is also the path that renders polygon holes correctly: the fill's startIndices collapse a feature's rings into one contiguous run, and the exterior/hole structure rides the baked indices instead. stt-build bakes them for the whole layer whenever --pre-tessellate is passed or any feature in it is multi-ring (a hole, or a MultiPolygon), so holed archives get correct fills without the flag; --pre-tessellate only extends the sidecar to simple single-ring polygons. (Per-ring outlines come from ringIndices instead — see Outline pass.)
• Known limitation (tile-seam overdraw): polygons spanning a tile boundary are split across tiles and drawn by separate sublayers. With opacity < 1 the two halves blend twice along the seam; extruded polygons can z-fight. The stroked outline has the same limitation (the ring is split across sublayers, so it double-draws along the seam). Prefer fully-opaque fills.

The sublayer short ids for _subLayerProps overrides are polygons (the fill) and outline (the stroked NoPickingPathLayer): _subLayerProps: { polygons: { type: MyLayer, ... }, outline: { ... } }.

Source#

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