Atlaslog / Field Notes / deck.gl visualization
Field note · deck.gl visualization
deck.gl layers drift behind the MapLibre basemap
Quick answer
When deck.gl and MapLibre each own a camera and viewState is pushed on the move event, the layer tracks a frame late and the offset grows with zoom. A transformed or padded container adds a fixed pixel offset on top.
Symptom
- While panning, the overlay follows late and only snaps into place after the pointer is released.
- Above zoom 12 the offset reaches tens of pixels, and inertial scrolling on mobile is the worst case.
- map.getCenter() and deck.viewState disagree immediately after a move event.
Checklist
- Check whether the app mounts MapboxOverlay or creates its own Deck instance.
- Compare map.getCenter() and getZoom() with deck.viewState at moveend.
- Inspect the map container for CSS transform: scale() or padding.
- Measure the pixel offset at zoom 18 on a known point.
Fix
Mount deck.MapboxOverlay as a map control so deck.gl reuses the MapLibre camera, use interleaved: true only for shared depth after load, and if managing Deck yourself pass longitude, latitude, zoom, pitch and bearing together.
Code
console.log('maplibre', map.getCenter(), map.getZoom());
console.log('deck', deck.viewState.longitude, deck.viewState.latitude, deck.viewState.zoom);var overlay = new deck.MapboxOverlay({
interleaved: false,
layers: [
new deck.ScatterplotLayer({
id: 'stations',
data: stations,
getPosition: function (d) { return [d.lng, d.lat]; },
getRadius: 8,
radiusUnits: 'pixels'
})
]
});
map.addControl(overlay);
map.on('load', function () {
overlay.setProps({ layers: buildLayers() });
});
Watch out
- Mounting MapboxOverlay and also calling setProps with viewState on move makes the two camera sources fight and produces regular jitter.
- Syncing only longitude, latitude and zoom drops pitch and bearing, so the layer still slides when the map is tilted.
English edition written for Atlaslog from the original Chinese field note. Code is unchanged and runs as-is.
Atlaslog (2026). deck.gl layers drift behind the MapLibre basemap. https://www.jingweizhi.com/en/cookbook/deckgl-maplibre-view-sync.html (accessed 2026-11-03).