@diginestai/deckgl-bridge — deck.gl Bridge

@diginestai/deckgl-bridge bridges deck.gl layers into MapLibre GL JS via @deck.gl/mapbox MapboxOverlay. Both renderers share a single WebGL context — no double-buffer, no visual seam.

---

Installation

pnpm add @diginestai/deckgl-bridge

---

Architecture

• A MapboxOverlay (with interleaved: true) is added as a MapLibre control on first use.
• The overlay is cached in a WeakMap keyed by the MapLibre map instance — calling getOrCreateOverlay(map) with the same map reference always returns the same handle (singleton per map).
• Layer constructors are resolved lazily from @deck.gl/* packages and cached in a module-level Map to avoid repeated dynamic imports.

---

Quick Start

import { getOrCreateOverlay, createHeatmapLayerSpec } from '@diginestai/deckgl-bridge';
import { useMap } from '@diginestai/core';

function HeatLayer() {
  const { map } = useMap();

  useEffect(() => {
    if (!map) return;
    const overlay = getOrCreateOverlay(map);
    overlay.addLayer(createHeatmapLayerSpec('my-heat', points));
    return () => overlay.removeLayer('my-heat');
  }, [map]);

  return null;
}

---

getOrCreateOverlay(map)

Returns (or creates) the DeckGLOverlayHandle for a given MapLibre map instance.

Parameter	Type	Description
map	MapLibreMapLike	MapLibre Map instance (or any object implementing addControl/removeControl).

DeckGLOverlayHandle API

Method	Signature	Description
addLayer	(spec: DeckGLLayerSpec) => Promise<void>	Adds a deck.gl layer (lazily imports the constructor).
removeLayer	(id: string) => Promise<void>	Removes the layer by ID.
updateLayer	(id: string, partial: Partial<DeckGLLayerSpec>) => Promise<void>	Merges new props into an existing layer.
destroy	() => void	Removes the overlay from the map and clears the registry entry.

---

Layer Spec Factories

All factories return a DeckGLLayerSpec object ready to pass to overlay.addLayer().

createHeatmapLayerSpec(id, data, opts?)

Creates a deck.gl HeatmapLayer spec.

Parameter	Type	Description
id	string	Unique layer ID.
data	[lon, lat, weight][]	Point array with weight.
opts.radiusPixels	number	Heatmap radius in pixels (default: 30).
opts.colorRange	[r,g,b,a][]	Custom 6-stop colour ramp.
opts.intensity	number	Global intensity multiplier.

---

createTripsLayerSpec(id, trips, opts?)

Creates a deck.gl TripsLayer spec for animated path playback.

Parameter	Type	Description
id	string	Unique layer ID.
trips	{ path: [lon,lat][]; timestamps: number[] }[]	Trip path and timestamps.
opts.currentTime	number	Playhead position (ms).
opts.trailLength	number	Length of the trail in ms.

---

createShapeLayerSpec(id, shapes)

Creates a spec for 3D extruded shapes (delegates to @diginestai/3d under the hood).

---

createAnimatedRoutePathSpec(id, route, opts?)

Creates an animated route path spec backed by AnimatedRoute3D.

Parameter	Type	Description
id	string	Unique layer ID.
route	Route	Route with segments: { floor: string; path: [lon, lat][] }[].
opts.color	[r,g,b,a]	Path colour (default: blue).
opts.widthMeters	number	Path width in metres.

---

<AnimatedRoute3D> (via @diginestai/core)

AnimatedRoute3D is a React component that wraps createAnimatedRoutePathSpec in a declarative API. Import it from @diginestai/core:

import { AnimatedRoute3D } from '@diginestai/core';

<AnimatedRoute3D
  route={myRoute}
  color={[0.1, 0.5, 1.0, 1.0]}
  widthMeters={2}
  animationDurationMs={3000}
  loop
/>

AnimatedRoute3DProps

Prop	Type	Default	Description
route	Route	—	Route to animate. Required.
color	[r,g,b,a]	[0.15, 0.55, 1, 1]	Path colour.
widthMeters	number	2	Path width in metres.
animationDurationMs	number	2000	Full loop duration in milliseconds.
loop	boolean	true	Continuously animate.

---

Available Layer Types

The DeckGLLayerSpec.type discriminated union supports:

HeatmapLayer · ScatterplotLayer · TripsLayer · IconLayer · GeoJsonLayer · ColumnLayer · PathLayer · TextLayer · ArcLayer · PolygonLayer · SolidPolygonLayer · HexagonLayer · GridLayer · TileLayer · MVTLayer