CollisionFilterExtension

The CollisionFilterExtension hides colliding instances — overlapping icons or text labels — so a crowded layer de-clutters itself, keeping the higher-priority instance where two overlap. deck.gl's own CollisionFilterExtension class is re-exported unchanged from @poopdeck.gl/layers, so both barrels hand you the identical object; only the collisionFilterProps helper is poopdeck-native — it makes the one-import ergonomic and spells out the constant configuration that already works on binary STT tiles.

deck's constant configuration (collisionEnabled / collisionGroup / collisionTestProps) works on the STT layers today through the plain top-level extensions prop — the composite layer forwards those scalars onto every binary sublayer, the same passthrough used for Brushing / Mask / Clip. collisionFilterProps bundles the extension and those props into one spreadable object.

Installation#

import {
  CollisionFilterExtension,
  collisionFilterProps,
  COLLISION_PRIORITY_MIN,
  COLLISION_PRIORITY_MAX,
} from '@poopdeck.gl/layers';

Usage#

Spread collisionFilterProps(...) onto any STT layer. It merges the extension into any extensions you already pass and wires the constant collision props:

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

new AnimatedIconLayer({
  // …tileset / icon props…
  ...collisionFilterProps({ collisionEnabled: true, collisionGroup: 'labels' }),
});

The constant case can equivalently be written with the extension directly:

new AnimatedIconLayer({
  // …tileset / icon props…
  extensions: [new CollisionFilterExtension()],
  collisionEnabled: true,
  collisionGroup: 'labels',
});

Options#

collisionFilterProps(options: CollisionFilterOptions) accepts:

Returned props#

collisionFilterProps returns a CollisionFilterProps object, spreadable onto any STT layer:

Priority constants#

Priorities outside [-1000, 1000] are meaningless to deck; collisionFilterProps clamps them into range and emits a one-time console warning.

Behavior#

• Constant configuration works today. collisionEnabled, collisionGroup, and collisionTestProps are forwarded verbatim from the composite layer onto every binary sublayer, so de-cluttering icons and labels needs no layer-level change.
• A constant collisionPriority works. Ranking a whole layer above or below another group is forwarded as the constant getCollisionPriority prop. The value is clamped to [COLLISION_PRIORITY_MIN, COLLISION_PRIORITY_MAX].
• A shared extension instance keeps the shader cache warm. When no CollisionFilterExtension is present in the passed extensions, a single shared instance is appended; a caller-supplied instance is reused rather than duplicated, keeping the extension set stable.
• Data-driven priority is deferred. deck's extension always registers the collisionPriorities attribute; what is deferred is the layer baking per-feature values into it from a tile column. On a binary tile there are no JS rows for an accessor to run over, so that needs a layer-level change the STT layers do not make yet: passing collisionPriorityProperty warns once and falls back to the constant collisionPriority, meaning every feature ranks equally.
• It costs one vertex-attribute slot on every host, used or not, and collisionEnabled: true also makes the layer request a picking buffer. Pair it with icon / text / point layers; on the path family it does not fit. AnimatedPathLayer sits at 15 of WebGL2's guaranteed 16 slots, so this extension takes its last one (and then pickable: true or filterProperty overflows); AnimatedTripsLayer, FlowCorridorLayer and FlowStrokeLayer are already at 16, so it overflows outright — a blank layer, not an error (see renderer-architecture.md §2.13 and the per-class budget in extensions.md).

Source#

packages/layers/src/extensions/collision-filter-extension.ts