在 Cesium 中使用 SDK

实验功能

需要平台开启三维开关（GEOBRIDGE_FEATURE_3D=true，见功能开关）。开关关闭时三维服务的接口不存在，请求得到 404。

JS SDK 的 client.cesium 在 CesiumJS 中加载平台的三维服务；栅格地形用 client.maplibre.setRasterTerrain() 加到 MapLibre 地图上。SDK 的安装与 client 的创建见 SDK 指南。

引入 CesiumJS

• SDK 不包含 Cesium，也不依赖它。请自行引入 CesiumJS 1.146 或更高版本（高斯泼溅只在 1.146 起支持的格式下显示）。
• 每个方法的第一个参数是你的 Cesium 命名空间对象：用打包工具时为 import * as Cesium from 'cesium'，用 <script> 引入构建版本时为全局变量 Cesium。
• 平台的三维服务不需要 Cesium ion。创建 Viewer 或 CesiumWidget 时传 baseLayer: false，再自行添加影像层（例如平台 MapServer 的切片），并关闭依赖 ion 的控件（如 geocoder: false）。
• Key 的传递与二维相同：SDK 用 client.cesium.resource() 生成带 Key 的 Cesium.Resource，子瓦片、地形瓦片沿用同样的 Key。

常用方法

方法	作用
cesium.terrainProvider()	网格地形服务的地形提供者
cesium.addTileset()	加载 3D Tiles 服务（网格、实景、点云、高斯泼溅）并加入场景
cesium.pointCloudStyle()	点云按 RGB、分类、强度、高程着色的样式
cesium.addModels()	按默认位置放置三维模型服务里的模型，泼溅按 3D Tiles 加载
cesium.flyToExtent()	按服务的数据范围斜视飞行
cesium.resource()	带 Key 的 Cesium.Resource，自行加载平台地址时使用
maplibre.setRasterTerrain()	把栅格地形服务设为 MapLibre 的三维地形，可选山体阴影

示例

// 页面已用 <script> 引入 CesiumJS（全局 Cesium）与 SDK（全局 GeoBridge）
const client = new GeoBridge.GeoBridgeClient({ baseUrl: 'https://map-demo.geobridge.cn/geobridge-mapserver', apiKey: 'gb_xxx…' })

// 只用 CesiumWidget，不用 ion：影像层用平台地图服务的切片（{z}/{y}/{x}）
const widget = new Cesium.CesiumWidget('cesiumContainer', { baseLayer: false })
widget.imageryLayers.addImageryProvider(
  new Cesium.UrlTemplateImageryProvider({ url: client.cesium.resource(Cesium, client.services.tileUrl('basemap')) }),
)

// 网格地形
widget.scene.terrainProvider = await client.cesium.terrainProvider(Cesium, 'terrain-mesh')

// 3D Tiles，加载后飞过去
const tileset = await client.cesium.addTileset(Cesium, widget, 'city-3d', { flyTo: true })

// 点云按分类着色
const cloud = await client.cesium.addTileset(Cesium, widget, 'pointcloud')
cloud.style = client.cesium.pointCloudStyle(Cesium, cloud, 'classification', { pointSize: 3 })

// 三维模型与高斯泼溅：按默认位置加载，未加载的项说明原因
const { models, tilesets, skipped } = await client.cesium.addModels(Cesium, widget, 'models')
skipped.forEach((s) => console.warn(s.name, s.message))

栅格地形在 MapLibre 中：

const map = new maplibregl.Map({ container: 'map', style: client.maplibre.mapStyleUrl('<地图方案 id>'), pitch: 60, maxPitch: 85 })
await new Promise((resolve) => map.once('load', resolve))
await client.maplibre.setRasterTerrain(map, 'terrain-dem', { exaggeration: 1.5, hillshade: true })

以上 'basemap'、'terrain-mesh' 等是服务路径（形如 目录/服务名），换成你自己的服务。

在沙箱里试运行

在线沙箱为三维示例准备好了全局变量 Cesium（CesiumJS 1.146）：代码里用到 Cesium 时自动加载，二维示例不受影响。七个三维示例的代码与说明见三维示例。

打开在线沙箱

下载为 HTML 时，三维示例的页面引用沙箱的 vendor/cesium/ 目录，需要把它一起拷走，见在线沙箱。