首页 / Cesium / API 文档

Cesium3DTileset

先看结论

3D Tiles 数据集的运行时对象，负责瓦片调度、细节层级切换和内存管理。

最后验证 2026-11-03 · CesiumJS 1.121 · 更新 2026-10-27 · 引用本文

创建方式

Cesium.Cesium3DTileset.fromUrl(url, options) → Promise<Cesium3DTileset>

推荐写法。返回 Promise，能准确拿到加载完成的时机。

new Cesium.Cesium3DTileset(options) → Cesium3DTileset

旧写法，对象立即返回但数据还在异步加载。需要监听 readyPromise 才能做定位或读取属性。

参数

参数	默认	说明
`maximumScreenSpaceError`	16	屏幕空间误差阈值。数值越小越精细，性能开销也越大
`maximumMemoryUsage`	512	瓦片缓存上限，单位 MB。超出后会卸载远处瓦片
`skipLevelOfDetail`	false	开启后跳过中间层级直接加载，首屏更快但可能出现跳变
`baseScreenSpaceError`	1024	配合上一项使用，控制跳层时的判断阈值
`preloadWhenHidden`	false	隐藏状态下是否预加载
`dynamicScreenSpaceError`	true	随相机距离动态调整误差，远景更省性能
`cullWithChildrenBounds`	true	用子节点包围盒做剔除，减少无效绘制
`modelMatrix`	—	整体变换矩阵，用于平移旋转缩放
`shadows`	—	阴影模式，`ENABLED` / `DISABLED` / `RECEIVE_ONLY`

常用成员与方法

成员	说明
`tileset.root`	根瓦片，可读取 `transform`、`boundingVolume`
`tileset.boundingSphere`	整体包围球，用于定位相机
`tileset.properties`	数据集自带属性表的定义
`tileset.style`	3D Tiles 样式语言写的着色表达式
`tileset.colorBlendMode`	颜色混合模式，`HIGHLIGHT` / `REPLACE` / `MIX`
`tileset.maximumScreenSpaceError`	运行时可直接改，用于动态调节画质
`tileset.statistics`	当前已加载瓦片数、几何数量等统计

加载与定位

var tileset = await Cesium.Cesium3DTileset.fromUrl(
  '/data/city/tileset.json',
  { maximumScreenSpaceError: 16, maximumMemoryUsage: 512 }
);

viewer.scene.primitives.add(tileset);
await viewer.zoomTo(tileset);

zoomTo 会自动根据包围球计算合适的相机位置。如果模型位置本身有偏差，定位也会跟着偏，先检查 tileset.root.transform。

按属性上色

tileset.style = new Cesium.Cesium3DTileStyle({
  color: {
    conditions: [
      ['${height} > 100', 'color("red")'],
      ['${height} > 50',  'color("orange")'],
      ['true',              'color("lightblue")']
    ]
  }
});

条件里的字段要在数据集中存在，否则整条样式不生效且不会报错。先用 tileset.properties 确认有哪些字段再写。

性能调节只有一个旋钮最关键：maximumScreenSpaceError。从 16 调到 32，同时显示的瓦片数大约减半；调到 64 会更流畅但地形边缘会明显粗糙。移动端建议从 32 起步。

引用本文

经纬志（2026）。《Cesium3DTileset》。https://www.jingweizhi.com/cesium/api/tileset.html（访问日期 2026-11-03）。