JSAPIThree 加载 Cesium 数据学习笔记：使用 Cesium 地形和影像服务

作为一个刚开始学习 mapvthree 的小白，今天要学习加载 Cesium 数据了！听说这个功能可以加载真实的地形数据，还能使用 Cesium 的影像服务！想想就期待！

第一次听说 Cesium 数据加载

今天在文档里看到了"Cesium"这个词。文档说 Cesium 数据加载可以：

• 加载真实的地形数据
• 使用 Cesium 的影像服务
• 支持 Cesium Ion 服务
• 需要配置 AccessToken

我的理解：简单说就是"用 Cesium 的地形和影像服务"，让场景有真实的地形起伏！

第一步：配置 Cesium Ion AccessToken

作为一个初学者，我习惯先看看需要什么配置。文档说使用 Cesium 服务需要配置 Cesium Ion AccessToken！

我的发现：Cesium 需要 AccessToken 才能使用，这是必须的配置！

获取 Cesium Ion AccessToken

1. 访问 Cesium ion 获取 accessToken
2. 在项目中配置

全局配置 AccessToken

获取 AccessToken 后，在项目的入口处进行配置，全局执行一次即可：

import * as mapvthree from '@baidumap/mapv-three';

// 配置 Cesium accessToken
mapvthree.CesiumConfig.accessToken = '您的accessToken';

我的理解：全局配置后，使用 Cesium 的所有服务都不需要再配置了！

临时配置 AccessToken

如果没有全局配置，可以在构造函数参数中临时配置：

const mapView = engine.add(new mapvthree.MapView({
    terrainProvider: new mapvthree.CesiumTerrainTileProvider({
        accessToken: '您的accessToken', // 临时配置 Cesium accessToken
    }),
}));

我的发现：可以全局配置，也可以临时配置，根据需求选择！

第二步：加载 Cesium 地形

看到需要配置 AccessToken 后，我想：怎么加载地形？

文档说可以用 CesiumTerrainTileProvider 来加载 Cesium 地形！

import * as mapvthree from '@baidumap/mapv-three';

const container = document.getElementById('container');

const engine = new mapvthree.Engine(container, {
    map: {
        center: [94.09, 30.64],
        range: 50000,
        pitch: 50,
        provider: null, // 设置为 null，稍后手动添加
    },
});

// 添加 Cesium 地形
const mapView = engine.add(new mapvthree.MapView({
    terrainProvider: new mapvthree.CesiumTerrainTileProvider({
        // accessToken: '您的accessToken', // 如果没有全局配置，可以在这里直接传入
    }),
    imageryProvider: new mapvthree.BingImageryTileProvider(),
}));

我的发现：地形数据会让场景有真实的起伏，看起来更真实！

我的理解：

• 优点：真实的地形数据，场景更立体
• 缺点：需要网络请求，加载时间较长
• 适用场景：需要真实地形展示的场景

自定义地形服务

如果不提供 url 自定义地形服务，默认使用 Cesium 官方服务。如果需要使用自定义地形服务：

const mapView = engine.add(new mapvthree.MapView({
    terrainProvider: new mapvthree.CesiumTerrainTileProvider({
        url: '您的自定义地形服务地址',
        accessToken: '您的accessToken',
    }),
}));

我的发现：可以使用自定义地形服务，也可以使用 Cesium 官方服务！

第三步：配合影像图层使用

看到可以加载地形后，我想：地形是灰色的，能不能加上影像？

文档说可以配合影像图层使用，比如 BingImageryTileProvider！

const mapView = engine.add(new mapvthree.MapView({
    terrainProvider: new mapvthree.CesiumTerrainTileProvider({
        // 地形数据
    }),
    imageryProvider: new mapvthree.BingImageryTileProvider({
        // 影像数据
    }),
}));

我的发现：地形提供高度信息，影像提供颜色信息，两者配合才能看到完整的地图！

我的理解：

• terrainProvider：提供地形高度数据
• imageryProvider：提供影像颜色数据
• 两者配合使用，效果最好

第四步：理解 MapView 结构

看到可以加载地形和影像后，我想：它们是怎么组织的？

文档说 MapView 是引擎中底图的容器，包含 RasterSurface 和 VectorSurface。

我的理解：

• terrainProvider：地形数据，属于 RasterSurface
• imageryProvider：影像数据，属于 RasterSurface
• 多个 ImageryTileProvider 可以叠加渲染

我的发现：

• RasterSurface 能保证图层之间叠加顺序的正确性
• 适合二维地图的渲染
• 多个影像图层可以叠加，并分层设置透明度

第五步：完整示例

我想写一个完整的示例，把学到的都用上：

import * as mapvthree from '@baidumap/mapv-three';

// 全局配置 Cesium accessToken
mapvthree.CesiumConfig.accessToken = '您的accessToken';

const container = document.getElementById('container');

const engine = new mapvthree.Engine(container, {
    map: {
        center: [94.09, 30.64],
        range: 50000,
        pitch: 50,
        provider: null, // 设置为 null，稍后手动添加
    },
});

// 添加 Cesium 地形和影像
const mapView = engine.add(new mapvthree.MapView({
    terrainProvider: new mapvthree.CesiumTerrainTileProvider({
        // 使用默认的 Cesium 官方服务
    }),
    imageryProvider: new mapvthree.BingImageryTileProvider({
        // 使用 Bing 影像服务
    }),
}));

我的感受：写一个完整的示例，把学到的都用上，感觉很有成就感！

第六步：踩过的坑

作为一个初学者，我踩了不少坑，记录下来避免再犯：

坑 1：地形不显示

原因：没有配置 Cesium Ion AccessToken，或者 AccessToken 配置错误。

解决：确保正确配置了 Cesium Ion AccessToken，可以全局配置或临时配置。

坑 2：地形显示为灰色

原因：只加载了地形，没有加载影像图层。

解决 ：同时配置 terrainProvider 和 imageryProvider。

坑 3：地形加载很慢

原因：地形数据量大，网络请求需要时间。

解决：这是正常现象，地形数据需要从服务器加载，请耐心等待。

坑 4：AccessToken 过期

原因：Cesium Ion AccessToken 可能过期。

解决：重新获取 AccessToken 并更新配置。

坑 5：自定义地形服务不工作

原因：地形服务地址错误，或者格式不对。

解决：确保地形服务地址正确，格式符合 Cesium Terrain 规范。

我的学习总结

经过这一天的学习，我掌握了：

1. 配置 Cesium Ion AccessToken：全局配置或临时配置
2. 加载 Cesium 地形 ：使用 CesiumTerrainTileProvider
3. 配合影像图层 ：使用 imageryProvider 提供影像数据
4. 自定义地形服务：可以使用自定义地形服务地址
5. MapView 结构：理解地形和影像在 MapView 中的组织方式

我的感受：Cesium 数据加载功能真的很强大！虽然配置有点复杂，但是用起来其实不难。关键是要理解地形和影像的关系，然后正确配置 AccessToken！

下一步计划：

1. 学习更多地形和影像的配置选项
2. 尝试使用自定义地形服务
3. 做一个完整的地形展示项目

---

学习笔记就到这里啦！作为一个初学者，我觉得 Cesium 数据加载虽然配置有点复杂，但是用起来其实不难。关键是要理解地形和影像的关系，然后正确配置 AccessToken！希望我的笔记能帮到其他初学者！大家一起加油！