基础概念

本页介绍使用 DMap3D SDK 开发时需要了解的核心概念。

Viewer（场景容器）

Viewer 是 Cesium 的核心类，负责管理整个 3D 场景的渲染和交互。一个页面通常只创建一个 Viewer 实例。

const viewer = new Cesium.Viewer('cesiumContainer', {
  animation: false,    // 动画控件
  timeline: false,     // 时间轴
  baseLayerPicker: false, // 底图选择器
})

常用属性

属性	说明
viewer.scene	场景对象，管理渲染和地球
viewer.camera	相机对象，控制视角
viewer.entities	实体集合
viewer.imageryLayers	影像图层集合
viewer.scene.primitives	图元集合（3DTiles 等）

生命周期

// 创建
const viewer = new Cesium.Viewer(container, options)

// 使用
viewer.entities.add({ ... })
viewer.camera.flyTo({ ... })

// 销毁（释放内存，必须调用）
viewer.destroy()

注意

在 React 中务必在 useEffect 的清理函数中调用 viewer.destroy()，防止内存泄漏。

坐标系统

Cesium 使用多种坐标系统，理解它们之间的关系很重要。

经纬度（度）

最直观的地理坐标表示：

// 经度、纬度、高度（米）
const longitude = 116.4074  // 东经
const latitude = 39.9042    // 北纬
const height = 100          // 海拔高度

Cartesian3（笛卡尔坐标）

Cesium 内部使用的三维直角坐标系，地心为原点：

// 经纬度 → Cartesian3
const position = Cesium.Cartesian3.fromDegrees(116.4074, 39.9042, 100)

// 弧度 → Cartesian3
const position2 = Cesium.Cartesian3.fromRadians(lon, lat, height)

Cartographic（弧度坐标）

// Cartesian3 → Cartographic
const carto = Cesium.Cartographic.fromCartesian(position)
const lon = Cesium.Math.toDegrees(carto.longitude)
const lat = Cesium.Math.toDegrees(carto.latitude)
const alt = carto.height

坐标转换速查

经纬度（度） ←→ Cartesian3 ←→ Cartographic（弧度）

转换方向	方法
度 → Cartesian3	Cesium.Cartesian3.fromDegrees(lon, lat, height)
Cartesian3 → 度	Cesium.Cartographic.fromCartesian(pos) + Math.toDegrees
度 → 弧度	Cesium.Math.toRadians(degrees)
弧度 → 度	Cesium.Math.toDegrees(radians)

Entity（实体）

Entity 是在场景中添加可视化对象的最简单方式，支持点、线、面、标签等。

// 添加点
viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.4074, 39.9042),
  point: {
    pixelSize: 10,
    color: Cesium.Color.RED,
  },
})

// 添加线
viewer.entities.add({
  polyline: {
    positions: Cesium.Cartesian3.fromDegreesArray([
      116.39, 39.90,
      116.41, 39.92,
    ]),
    width: 3,
    material: Cesium.Color.YELLOW,
  },
})

// 添加多边形
viewer.entities.add({
  polygon: {
    hierarchy: Cesium.Cartesian3.fromDegreesArray([
      116.39, 39.90,
      116.41, 39.90,
      116.41, 39.92,
      116.39, 39.92,
    ]),
    material: Cesium.Color.BLUE.withAlpha(0.5),
  },
})

Camera（相机）

相机控制场景的观察视角。

即时定位

viewer.camera.setView({
  destination: Cesium.Cartesian3.fromDegrees(116.4074, 39.9042, 10000),
  orientation: {
    heading: Cesium.Math.toRadians(0),    // 朝向（0=北）
    pitch: Cesium.Math.toRadians(-45),    // 俯仰（负值=向下看）
    roll: 0,
  },
})

飞行动画

viewer.camera.flyTo({
  destination: Cesium.Cartesian3.fromDegrees(116.4074, 39.9042, 10000),
  duration: 2.0,  // 飞行时间（秒）
})

视角参数

参数	说明	范围
heading	水平朝向	0°=北, 90°=东, 180°=南, 270°=西
pitch	俯仰角	-90°=正下方, 0°=水平
roll	翻滚角	通常为 0

影像图层（Imagery）

影像图层是覆盖在地球表面的 2D 地图底图。

天地图（推荐国内使用）

// 卫星影像
const imgLayer = new Cesium.WebMapTileServiceImageryProvider({
  url: 'https://t0.tianditu.gov.cn/img_w/wmts?tk=YOUR_TOKEN',
  layer: 'img',
  style: 'default',
  tileMatrixSetID: 'w',
  format: 'tiles',
  maximumLevel: 18,
})

// 矢量注记（叠加在影像上显示地名）
const ciaLayer = new Cesium.WebMapTileServiceImageryProvider({
  url: 'https://t0.tianditu.gov.cn/cia_w/wmts?tk=YOUR_TOKEN',
  layer: 'cia',
  style: 'default',
  tileMatrixSetID: 'w',
  format: 'tiles',
  maximumLevel: 18,
})

// 添加注记图层
viewer.imageryLayers.addImageryProvider(ciaLayer)

图层管理

// 添加图层
const layer = viewer.imageryLayers.addImageryProvider(provider)

// 设置透明度
layer.alpha = 0.5

// 移除图层
viewer.imageryLayers.remove(layer)

地形（Terrain）

地形让地球表面有真实的高程起伏。

// 使用 Cesium Ion 全球地形
const viewer = new Cesium.Viewer(container, {
  terrain: Cesium.Terrain.fromWorldTerrain(),
})

// 无地形（平面椭球体）
const viewer = new Cesium.Viewer(container, {
  terrainProvider: new Cesium.EllipsoidTerrainProvider({}),
})

选择地形

• 需要地形分析（坡度、剖面等）时使用 fromWorldTerrain()
• 只需要平面展示时使用 EllipsoidTerrainProvider，加载更快

3DTiles（三维模型）

3DTiles 是用于流式传输大规模三维数据（建筑、倾斜摄影等）的标准格式。

// 加载 3DTiles
const tileset = await Cesium.Cesium3DTileset.fromUrl(
  '/3DTiles/model/tileset.json'
)
viewer.scene.primitives.add(tileset)

// 飞到模型位置
viewer.zoomTo(tileset)

DMap3D 命名空间

DMap3D SDK 通过命名空间组织所有功能模块：

DMap3D
├── measurement          // 测量工具
│   ├── spaceDistance     // 空间距离
│   ├── horizontalDistance // 水平距离
│   ├── surfaceDistance   // 贴地距离
│   ├── area             // 面积
│   ├── height           // 高度
│   ├── angle            // 角度
│   ├── slope            // 坡度
│   └── azimuth          // 方位角
├── analysis             // 分析工具
│   ├── viewshed         // 可视域
│   ├── viewshedArea     // 区域可视域
│   ├── contour          // 等高线
│   ├── profile          // 剖面
│   ├── skyline          // 天际线
│   ├── bufferAnalysis   // 缓冲区
│   ├── elevationExtremum // 高程极值
│   ├── aspectAnalyse    // 坡向
│   ├── slopAnalyse      // 坡度分析
│   ├── cutFill          // 填挖方
│   └── flattenAnalysis  // 压平
├── drawing              // 绘制工具
│   ├── point            // 点
│   ├── polyline         // 线
│   ├── polygon          // 多边形
│   └── circle           // 圆
└── military             // 军事标绘
    ├── FineArrow        // 精细箭头
    ├── StraightArrow    // 直箭头
    └── ...              // 更多标绘

使用模式

所有工具遵循统一的生命周期：

// 1. 创建工具（传入 viewer）
const tool = new DMap3D.measurement.spaceDistance(viewer, options)

// 2. 激活工具
tool.activate()

// 3. 用户交互（左键操作，右键结束）

// 4. 清除结果
tool.clear()

// 5. 销毁工具
tool.destroy()

资源清理

在 Cesium 和 DMap3D 中，正确清理资源非常重要：

useEffect(() => {
  const viewer = new Cesium.Viewer(container)
  const tool = new DMap3D.measurement.area(viewer)

  return () => {
    // 先销毁工具
    tool.destroy()
    // 再销毁 Viewer
    viewer.destroy()
  }
}, [])

内存泄漏

如果不调用 destroy()，Cesium 的 WebGL 上下文和事件监听器不会被释放，会导致严重的内存泄漏。

下一步

掌握了基础概念后，可以深入学习：

• API 文档 - 查看所有工具的详细参数
• 示例库 - 每个功能的完整代码示例
• 测量工具 - 从距离测量开始
• 绘制工具 - 学习交互式绘制