首页 / deck.gl / API 文档

ScenegraphLayer

先看结论

场景图图层。加载完整 glTF 模型（含节点层级、材质、贴图），再按数据把这些模型摆到地图上。

最后验证 2026-11-03 · deck.gl 9.0 · 更新 2026-10-29 · 引用本文

new deck.ScenegraphLayer(props)

核心参数

参数	默认	说明
`scenegraph`	必填	模型 URL，通常是 `.glb` 或 `.gltf`
`scenegraphOptions`	—	加载选项，如 `{ node: 'wheel' }` 只取某个节点
`data`	—	实例数据
`getPosition`	[0, 0, 0]	实例位置，`[lng, lat, z]`
`getColor`	[255, 255, 255, 255]	整体染色，RGBA
`getOrientation`	[0, 0, 0]	朝向，`[pitch, yaw, roll]`，单位为度
`getScale`	[1, 1, 1]	三轴缩放
`getTransformMatrix`	—	4x4 变换矩阵，优先于位置、朝向与缩放
`sizeScale`	1	模型整体尺寸倍率
`opacity`	1	整体透明度
`pickable`	false	是否参与拾取

示例：车辆沿轨迹摆放

var vehicles = new deck.ScenegraphLayer({
  id: 'vehicles',
  data: tracks,
  scenegraph: '/models/vehicle.glb',
  getPosition: function (d) { return [d.lng, d.lat, d.z || 0]; },
  getOrientation: function (d) { return [0, d.heading, 0]; },
  getColor: function (d) {
    return d.congested ? [214, 74, 74, 255] : [90, 140, 220, 255];
  },
  sizeScale: 1,
  pickable: true
});

朝向的约定

getOrientation 返回的是 [pitch, yaw, roll]，与常见 API 的 [yaw, pitch, roll] 顺序不同。模型文件本身的朝向也有影响：多数 glTF 模型正面朝 +Z，摆到地图上通常需要 yaw 加 90 度才能对准行进方向。先拿单个模型试摆，确定偏移量后再批量应用。

加载与显示

scenegraph 是异步加载的资源，首帧看到的是空白，加载完成后自动出现，不需要手动触发重绘。模型较大时压缩纹理、减少节点数量比调整图层参数有效。 scenegraphOptions 里的 node 可以只取其中一个子节点，用于从整机模型中拆出某个零件单独实例化。

v9 的不可变更新

deck.gl 9 的图层实例不可变，运行中换模型不会生效。正确做法是 clone 出新图层，再交给 deckgl.setProps 替换 layers：

var next = vehicles.clone({
  scenegraph: '/models/vehicle-lod1.glb',
  sizeScale: 0.8
});

deckgl.setProps({ layers: [next] });

实例化的是同一份场景图。所有实例共享材质与纹理，改一个实例的颜色会走 getColor 的染色通道，不能给单个实例换贴图。需要不同外观时拆成多个图层，各用各的模型。

引用本文

经纬志（2026）。《ScenegraphLayer》。https://www.jingweizhi.com/deckgl/api/scenegraph-layer.html（访问日期 2026-11-03）。