Basemaps, projections and offsets
Quick answer
This tutorial compares three ways to give deck.gl a basemap: a TileLayer with BitmapLayer sublayers, a MapLibre or Mapbox map through MapboxOverlay, and a Leaflet map whose camera is synced manually. It explains the tile URL order, the TMS row flip, GCJ-02 and BD-09 offsets, layer ordering and interleaved mode. Readers can align data with real tiles and avoid drift after panning.
Key points
- Return a BitmapLayer from renderSubLayers using props.tile.boundingBox as bounds.
- Use MapboxOverlay with interleaved: false unless depth testing against 3D buildings is needed.
- On Leaflet, sync viewState on move and use map.getZoom() minus one.
Example
var basemap = new deck.TileLayer({
id: 'basemap',
data: 'https://services.arcgisonline.com/ArcGIS/rest/services/Canvas/World_Dark_Gray_Base/MapServer/tile/{z}/{y}/{x}',
minZoom: 0,
maxZoom: 16,
tileSize: 256,
renderSubLayers: function (props) {
var bb = props.tile.boundingBox; // [[西, 南], [东, 北]]
return new deck.BitmapLayer(props, {
data: null,
image: props.data,
bounds: [bb[0][0], bb[0][1], bb[1][0], bb[1][1]]
});
}
});
var deckgl = new deck.Deck({
canvas: 'cv',
width: '100%',
height: '100%',
initialViewState: { longitude: 116.39, latitude: 39.9, zoom: 9, pitch: 0 },
controller: true,
layers: [basemap, dataLayer] // 先底图,后数据
});var overlay = new deck.MapboxOverlay({
interleaved: false, // 需要与三维建筑混合时设为 true
layers: [dataLayer]
});
map.addControl(overlay);
Notes
- TMS services need the y axis flipped, or tiles render upside down or return 404.
- Baidu BD-09 and Gaode GCJ-02 tiles shift WGS84 data by tens to hundreds of meters.
English edition written for Atlaslog. Code is taken from the original Chinese page and runs unchanged.
Atlaslog (2026). Basemaps, projections and offsets. https://www.jingweizhi.com/en/deckgl/tutorials/basemap.html (accessed 2026-11-03).