Cesium实战(三):加载天地图(影像图,注记图)避坑指南

写在前面

还在为Cesium三维地球找不到合适的国内底图发愁？想用权威、更新及时的天地图作为可视化项目的底图，却不知道如何接入？

今天这篇教程，全程围绕Cesium官方API展开，从申请天地图密钥到编写完整代码，手把手教你如何在Cesium中加载天地图的影像、矢量、注记等各类地图服务。新手也能跟着敲出效果，彻底搞懂Cesium与天地图的集成方案。

1. 先搞懂：Cesium + 天地图 = 三维GIS项目的黄金搭档

Cesium（Web Graphics Library）是浏览器原生的三维地球渲染引擎，无需插件、直接调用GPU加速------但想要在国内项目中使用权威底图，天地图是绕不开的核心选择！

核心优势

数据权威合规：天地图是国家主导建设的地理信息公共服务平台，数据源具有天然的权威性和现势性，完全符合国内政务、规划等项目的数据合规要求。
服务稳定多样：提供影像、矢量、地形、注记等一系列标准在线服务，且在国内访问速度快、稳定性高。
接入简单高效 ：Cesium提供了多种ImageryProvider，只需几行代码就能将天地图无缝集成到三维场景中。

2. 准备工作：申请天地图密钥

天地图的所有服务都需要通过密钥（token）来调用，这是接入的第一步。

2.1 注册与登录

访问国家地理信息公共服务平台（天地图）官网：http://www.tianditu.gov.cn/
点击右上角"注册"按钮，完成个人信息填写并激活账号。

2.2 创建应用获取Key

登录后，点击右上角"控制台"，进入应用管理页面。
点击"创建新应用"，填写应用名称。
关键步骤------应用类型 ：必须选择**"浏览器端"**。天地图现已严格区分应用类型，浏览器端开发必须选择对应的类型，否则无法调用。
提交后，系统会生成一个唯一的字符串密钥（Key），形如"abcdefg1234567890"。请复制保存好，后续代码中会用到。

3. Cesium加载天地图核心原理

在Cesium中，所有影像图层都由ImageryLayer和ImageryProvider管理。

Viewer.imageryLayers：一个集合，包含当前视图中的所有影像图层。
ImageryProvider：影像数据的提供者，不同的地图服务对应不同的Provider。

接入天地图最常用、最推荐的两种方式：

UrlTemplateImageryProvider（推荐）：通过URL模板拼接瓦片地址，简单直观。
WebMapTileServiceImageryProvider：遵循WMTS标准协议，适合标准化集成。

4. 实战：纯代码实现Cesium加载天地图

4.1 基础环境搭建

创建 vue文件(需要安装vue环境)，引入Cesium的JS和CSS库。

html

复制代码

<template>
  <div id="cesiumContainer"></div>
</template>
 
<script setup>

  import * as Cesium from 'cesium'
  import "./Widgets/widgets.css"
  import { onMounted } from 'vue';
 
  window.CESIUM_BASE_URL = "/";
 
  onMounted(()=>{
 var viewer =  new Cesium.Viewer("cesiumContainer",{
      // 去掉对话框警告
      infoBox:false,
      // 是否显示查询按钮
      geocoder: false,
      // 不显示home按钮
      homeButton:false,
      // 控制查看器的显示模式（3D、2.5D、2D是否显示）
      sceneModePicker:false,
      // 是否显示图层选择
      baseLayerPicker:false,
      // 是否显示帮助按钮
      navigationHelpButton:false,
      // 是否显示播放动画、计时
      animation:false,
      // 是否显示时间轴
      timeline:false,
      // 是否显示全屏按钮
      fullscreenButton:false,
 
    });
    //隐藏 Cesium 的版权信息水印。
    viewer.cesiumWidget.creditContainer.style.display = "none";
    
 


  })
</script>
 
<style>
*{
  margin: 0;
  padding: 0;
}
</style>

4.2 核心接入：使用`UrlTemplateImageryProvider`加载天地图影像

这是最简洁、最推荐的加载方式。我们将用几行代码替换默认的Bing地图，显示天地图卫星影像。

javascript

复制代码

// --- 在 <script> 标签内编写以下代码 ---

// 1. 填入你自己的天地图浏览器端Key
const tdtToken = 'YOUR_TDT_TOKEN_HERE'; // 请替换为你在天地图申请的Key

// 2. 初始化Cesium Viewer
const viewer = new Cesium.Viewer('cesiumContainer', {
    // 简化UI，让界面更清爽
    baseLayerPicker: false,   // 关闭底图选择器
    geocoder: false,          // 关闭地理编码器
    homeButton: true,        
    sceneModePicker: true,    
    navigationHelpButton: false,
    animation: false,
    timeline: false,
    fullscreenButton: false
});

// 3. 构建天地图影像图层提供器
const tdtImgProvider = new Cesium.UrlTemplateImageryProvider({
    // 天地图影像瓦片URL模板（关键！）
    // 参数说明：T=img_w 表示影像底图；x,y,z为行列号与层级；tk=你的密钥
    url: 'https://t{s}.tianditu.gov.cn/DataServer?T=img_w&x={x}&y={y}&l={z}&tk=' + tdtToken,
    // 子域列表，用于负载均衡，加速瓦片加载
    subdomains: ['0', '1', '2', '3', '4', '5', '6', '7'],
    // 投影方式：天地图在线服务使用Web墨卡托投影(EPSG:3857)
    tilingScheme: new Cesium.WebMercatorTilingScheme(),
    // 最大缩放级别（天地图影像一般支持18级）
    maximumLevel: 18,
    // 最小缩放级别
    minimumLevel: 1
});

// 4. 将图层添加到Viewer中
viewer.imageryLayers.addImageryProvider(tdtImgProvider);

// 5. 可选：移除Cesium默认加载的底图（如果不移除，会有两层底图）
viewer.imageryLayers.remove(viewer.imageryLayers.get(0));

// 6. 设置初始视角（比如定位到北京）
viewer.camera.setView({
    destination: Cesium.Cartesian3.fromDegrees(116.397, 39.907, 5000000) // 经度, 纬度, 高度（米）
});

console.log('✅ 天地图影像加载成功！');

代码详解

URL模板 ：https://t{s}.tianditu.gov.cn/DataServer?T=img_w&x={x}&y={y}&l={z}&tk=你的Key 这是天地图提供的标准瓦片请求地址。{s}会被subdomains数组中的值替换，{x}、{y}、{z}是Cesium自动计算的瓦片坐标。
T=img_w参数：指定服务类型。天地图提供了多种图层，通过修改这个参数即可切换：
- img_w：全球影像底图
- vec_w：全球矢量底图（道路、行政边界等）
- cia_w：影像注记（标注地名）
- cva_w：矢量注记
- ter_w：地形晕渲

4.3 进阶应用：叠加多个图层（影像+注记）

在实际项目中，通常需要"影像底图"和"注记图层"叠加，才能看到清晰的卫星照片和地名标注。

javascript

复制代码

// 天地图影像底图（卫星图）
const tiandituImgLayer = new Cesium.WebMapTileServiceImageryProvider({
  url: "http://t0.tianditu.gov.cn/img_w/wmts?tk=xxxx", //修改成自己的token
  layer: "img",
  style: "default",
  tileMatrixSetID: "w",
  format: "tiles",
  maximumLevel: 18
});
viewer.imageryLayers.addImageryProvider(tiandituImgLayer);


// 天地图影像注记（卫星图上的标注）
const tiandituCiaLayer = new Cesium.WebMapTileServiceImageryProvider({
  url: "http://t0.tianditu.gov.cn/cia_w/wmts?tk=xxxx",
  layer: "cia",
  style: "default",
  tileMatrixSetID: "w",
  format: "tiles",
  maximumLevel: 18
});

viewer.imageryLayers.addImageryProvider(tiandituCiaLayer);

4.4 完整示例：一键运行代码

将以下完整代码保存为一个HTML文件，替换YOUR_TDT_TOKEN_HERE为你自己的密钥，双击运行即可看到效果。

html

复制代码

<template>
  <div id="cesiumContainer"></div>
</template>
 
<script setup>

  //导入3D 地理空间可视化库
  import * as Cesium from 'cesium'
  //导入Cesium 的 UI 组件样式
  import "./Widgets/widgets.css"

  //导入生命周期钩子，组件挂载后执行
  import { onMounted } from 'vue';
 
  window.CESIUM_BASE_URL = "/";
 
  
  onMounted(()=>{
    var viewer =  new Cesium.Viewer("cesiumContainer",{
      // 去掉对话框警告
      infoBox:false,
      // 是否显示查询按钮
      geocoder: false,
      // 不显示home按钮
      homeButton:false,
      // 控制查看器的显示模式（3D、2.5D、2D是否显示）
      sceneModePicker:false,
      // 是否显示图层选择
      baseLayerPicker:false,
      // 是否显示帮助按钮
      navigationHelpButton:false,
      // 是否显示播放动画、计时
      animation:false,
      // 是否显示时间轴
      timeline:false,
      // 是否显示全屏按钮
      fullscreenButton:false,
 
    });
    //隐藏 Cesium 的版权信息水印。
    viewer.cesiumWidget.creditContainer.style.display = "none";

 
// 天地图影像底图（卫星图）
const tiandituImgLayer = new Cesium.WebMapTileServiceImageryProvider({
  url: "http://t0.tianditu.gov.cn/img_w/wmts?tk=xxxx", //修改成自己的token
  layer: "img",
  style: "default",
  tileMatrixSetID: "w",
  format: "tiles",
  maximumLevel: 18
});
viewer.imageryLayers.addImageryProvider(tiandituImgLayer);






// 天地图地形晕渲图
const tiandituTerLayer = new Cesium.WebMapTileServiceImageryProvider({
  url: "http://t0.tianditu.gov.cn/ter_w/wmts?tk=xxxx", //修改成自己的token
  layer: "ter",
  style: "default",
  tileMatrixSetID: "w",
  format: "tiles",
  maximumLevel: 18
});

viewer.imageryLayers.addImageryProvider(tiandituTerLayer);


// 天地图影像注记（卫星图上的标注）
const tiandituCiaLayer = new Cesium.WebMapTileServiceImageryProvider({
  url: "http://t0.tianditu.gov.cn/cia_w/wmts?tk=460cc03369dfd1fcc6e2fce1e7fd34c0",
  layer: "cia",
  style: "default",
  tileMatrixSetID: "w",
  format: "tiles",
  maximumLevel: 18
});

viewer.imageryLayers.addImageryProvider(tiandituCiaLayer);

 



 

  })

 
 

 

</script>
 
<style>
*{
  margin: 0;
  padding: 0;
}
</style>

5. 常见问题与避坑指南

5.1 地图瓦片加载不出来或显示空白？

检查Key：确认Key是否正确，以及应用类型是否为"浏览器端"。服务端Key无法在浏览器中使用。
检查网络 ：天地图域名tianditu.gov.cn是否能够正常访问？是否存在跨域问题？
检查参数 ：URL中的T=参数是否正确？img_w是影像，vec_w是矢量，不要写错。

5.2 加载的地图偏移或位置不对？

检查投影 ：天地图在线服务默认使用Web墨卡托投影 ，必须在tilingScheme中设置为new Cesium.WebMercatorTilingScheme()。如果误设置为经纬度投影，会导致瓦片错位。

5.3 如何切换矢量底图、地形图？

只需修改T=参数即可：
- 矢量底图：T=vec_w
- 地形晕渲：T=ter_w
- 影像注记：T=cia_w
- 矢量注记：T=cva_w

5.4 叠加多个图层时，顺序很重要

viewer.imageryLayers是一个类似数组的结构，先添加的图层在底层，后添加的在上层。通常的叠加顺序是：

影像底图 (img_w) 或矢量底图 (vec_w)
注记图层 (cia_w 或 cva_w)

5.5 关于调用限额

天地图对个人开发者有每日调用次数限制（如影像底图10000次/日），开发测试足够，但若用于高并发商业项目，建议升级企业账号或申请更高配额。

6. 核心总结

接入三要素：Key + 正确URL + 正确投影（Web墨卡托）。
推荐方式 ：UrlTemplateImageryProvider，简单直观，适合快速开发。
图层类型 ：通过T=参数自由切换影像、矢量、注记、地形。
叠加技巧：先底图后注记，构建完整视觉体验。

关注我，下期解锁更多Cesium 三维 GIS 玩法！

Cesium实战(三):加载天地图(影像图,注记图)避坑指南

写在前面

1. 先搞懂：Cesium + 天地图 = 三维GIS项目的黄金搭档

核心优势

2. 准备工作：申请天地图密钥

2.1 注册与登录

2.2 创建应用获取Key

3. Cesium加载天地图核心原理

4. 实战：纯代码实现Cesium加载天地图

4.1 基础环境搭建

4.2 核心接入：使用UrlTemplateImageryProvider加载天地图影像

4.3 进阶应用：叠加多个图层（影像+注记）

4.4 完整示例：一键运行代码

5. 常见问题与避坑指南

5.1 地图瓦片加载不出来或显示空白？

5.2 加载的地图偏移或位置不对？

5.3 如何切换矢量底图、地形图？

5.4 叠加多个图层时，顺序很重要

5.5 关于调用限额

6. 核心总结

4.2 核心接入：使用`UrlTemplateImageryProvider`加载天地图影像