Cesium-1.143 中文版 API

楔子：为了方便光大 GISer 更好的使用 Cesium，这里提供 Cesium-1.143 中文版镜像，后续会随较大更新版本而更新。

访问方式

资源	链接
Cesium中文版API（1.143）	cesium.vip/

接下来介绍一下 Cesium 入门指南：从三维地球引擎的核心能力，到中文版 API 文档的获取、价值与共建。

一、Cesium 概述

1.1 什么是 Cesium

Cesium （正式名称为 CesiumJS ）是一个开源的 JavaScript 库，用于在浏览器中创建世界级的 3D 地球和 2D 地图 ，且无需任何插件。它基于 WebGL 技术，将地理空间数据与高性能图形渲染结合，使开发者能够在网页端呈现厘米级精度的三维地理场景。

Cesium 由 CesiumGS 公司（前身为 Analytical Graphics Inc.，即 AGI）主导开发与维护，并拥有一个活跃的开源社区。其设计目标是：让任意设备或浏览器都能流畅地加载、可视化和分析大规模的时空地理数据。

一句话理解：如果 OpenLayers / Leaflet 是二维地图的利器，那么 Cesium 就是三维地球与时空数据可视化的标杆。

1.2 技术基石

Cesium 的能力建立在一组开放标准与成熟技术之上：

技术 / 标准	作用
WebGL	浏览器端 GPU 硬件加速渲染，支撑海量几何与纹理
3D Tiles	OGC 社区标准，用于流式加载大规模三维地理数据（倾斜摄影、BIM、点云）
glTF / GLB	高效的 3D 模型格式（"JPEG of 3D"），Cesium 官方推荐模型格式
CZML	Cesium 专用时空数据描述语言，用于描述随时间变化的动态实体
GeoJSON / KML	通用矢量与标注数据格式
WGS84	统一的坐标参考系，保证全球数据对齐

1.3 核心特点

跨平台、零插件：纯前端运行，支持桌面与移动端的主流浏览器。
时间动态（Time-Dynamic）：原生支持时间轴与时钟，可回放卫星轨迹、车辆运动等随时间演变的数据。
大规模三维数据：借助 3D Tiles 流式加载技术，可流畅展示城市级倾斜摄影、BIM 模型与亿级点云。
开放与可互操作：兼容 OGC 标准，易于与 GIS、BIM、IoT 等系统对接。
高精度地形与影像：内置多种影像与地形服务提供方，支持自定义接入。

二、核心功能

2.1 三维地球与地图渲染

Cesium 的核心是 Viewer 对象，它封装了场景（Scene）、相机（Camera）、图层（ImageryLayer）、地形（Globe）与时间（Clock）等子系统。只需几行代码即可初始化一个可交互的三维地球：

javascript 复制代码

const viewer = new Cesium.Viewer('cesiumContainer', {
  terrain: Cesium.Terrain.fromWorldTerrain(),
  baseLayer: Cesium.ImageryLayer.fromWorldImagery()
});

2.2 时间动态数据（Time-Dynamic）

Cesium 天生为"时空"而生。通过 JulianDate、Clock、SampledPositionProperty 等类型，可以描述实体在任意时刻的位置、朝向与属性，并在时间轴上自由播放、暂停与倍速回放。

javascript 复制代码

const start = Cesium.JulianDate.fromIso8601('2024-01-01T00:00:00Z');
viewer.clock.startTime = start;
viewer.clock.currentTime = start;
viewer.clock.multiplier = 60; // 60 倍速

卫星过境预报、飞行器轨迹、车辆 GPS 回放等场景，均依赖这一能力。

2.3 3D Tiles 与大规模三维数据

3D Tiles 是 Cesium 处理超大规模三维地理数据的核心。它能够分块、分层级（LOD）地流式加载数据，使浏览器在有限内存下也能渲染整座城市：

倾斜摄影（Photogrammetry）：无人机航拍重建的实景三维模型
BIM / 建筑模型：设计阶段的建筑信息模型
点云（Point Cloud）：激光雷达等采集的亿级点数据
实例化模型（Instances）：重复结构（如路灯、树木）的高效表达

2.4 影像与地形

Cesium 提供统一的 ImageryProvider 与地形接口，可接入：

全球影像（Bing、ArcGIS、天地图、自定义 TMS/WMTS）
地形高程（Quantized Mesh、Google Photorealistic 3D Tiles、自定义地形服务）
多源图层叠加与透明度控制

2.5 实体 API（Entity）与图元（Primitive）

Cesium 提供两类编程模型：

Entity API（高级、面向数据）：以"实体"为单位描述点、线、面、模型、标签等，自动管理底层细节，适合快速开发。
Primitive API（底层、面向性能）：直接操作几何与外观，性能最优，适合海量静态数据的极致优化。

javascript 复制代码

viewer.entities.add({
  position: Cesium.Cartesian3.fromDegrees(116.39, 39.9),
  point: { pixelSize: 10, color: Cesium.Color.RED },
  label: { text: '北京', font: '14pt sans-serif' }
});

2.6 相机与交互控制

Cesium 的相机系统支持飞行（flyTo）、跟踪（trackedEntity）、第一/第三人称视角，以及鼠标键盘交互（缩放、倾斜、平移）。结合 ScreenSpaceEventHandler 可自定义拾取与交互逻辑。

2.7 空间分析能力

借助 Cesium 的几何与数学工具，可实现：

通视分析（Line of Sight）
视域分析（Viewshed / Frustum）
体积计算（Volume）
限高分析、天际线分析
距离 / 面积量算

三、主要应用场景

3.1 智慧城市与数字孪生

将城市倾斜摄影、BIM、地下管网与 IoT 实时数据融合，构建可交互的"数字孪生城市"，用于规划展示、应急指挥与资产管理。

3.2 航空航天与卫星

可视化卫星轨道、地面站覆盖、星座组网，结合时间轴回放卫星过境与任务过程。

3.3 军事与国防仿真

战场环境三维推演、兵力机动模拟、通视与雷达覆盖分析等。

3.4 气象与环境监测

气象云图、污染扩散、海浪流场等时空数据的动态呈现。

3.5 教育与科研

地理、测绘、遥感等课程的三维教学演示与科研成果展示。

四、Cesium 中文版 API 详解

4.1 为什么需要中文版 API

尽管 Cesium 功能强大，但其官方文档（cesium.com/learn）与本地 Build/Documentation 全部为英文，且包含大量地理信息、图形学、计算机术语。对英语基础薄弱或刚接触三维地理开发的国内开发者而言，存在明显门槛：

阅读官方 API 耗时，概念理解易偏差
团队内部文档难以统一，新人上手慢
关键时刻"查得到英文、读不懂含义"

中文版 API 文档正是在这一背景下，对 Cesium 完整 API 参考文档进行系统翻译的成果。

4.2 中文版 API 的内容覆盖

本中文版 API 对 Cesium 发布包内 Build/Documentation 目录下的全部文档文件进行了翻译，覆盖：

类别	说明
类（Class）	如 `Viewer`、`Entity`、`Cesium3DTileset`、`Camera` 等数百个类
全局函数（Global Functions）	如 `binarySearch`、`sampleTerrain`、`createWorldTerrainAsync` 等
枚举（Enum）	如 `ArcType`、`VerticalOrigin`、`ClassificationType` 等
类型定义（Typedef）	如 `MetadataValue`、`HeadingPitchRollValues` 等
描述、参数、返回值、示例	每个成员的描述文本、参数说明、See Also 与示例

翻译既覆盖类成员的 description（功能描述），也覆盖参数表 td.description、参数描述 param-desc 等细节，力求"读中文即懂含义"。

4.3 资源获取方式

中文版 API 文档以静态 HTML 文件形式提供，与官方结构完全一致：

本地文件 ：翻译成果位于 Cesium 包的 Build/Documentation/ 目录下（如 Build/Documentation/global.html、Build/Documentation/Viewer.html 等），直接用浏览器打开即可。
离线浏览：将所有文档文件放入任意静态服务器或直接双击打开，无需联网，适合内网与涉密环境。
与官方在线版对照：中文文档的文件名、锚点（anchor）与官方一一对应，可中英文并排对照阅读，快速定位原始出处。

提示：文档中的类名、方法名、属性名、类型名、枚举值、URL、代码块等均保持英文原文，仅对描述性散文进行翻译，以确保与代码世界的一致性，避免"翻译后与源码对不上"的问题。

4.4 对国内开发者的价值

降低学习曲线：术语与概念用母语表达，理解速度显著提升。
加速项目落地：查阅 API 不再被语言卡住，开发效率提高。
统一团队认知：团队共用中文文档，减少沟通歧义。
利于知识沉淀：便于内部培训、技术文档与 Wiki 的二次整理。

五、中文版 API 的翻译过程

5.1 翻译范围与粒度

翻译以"描述块"为最小单元，覆盖文档中的：

div.description：成员主描述
td.description.last：参数 / 属性说明单元格
div.param-desc：参数详细描述
ul.see-list：参见（See Also）交叉引用
div.help：页脚帮助信息

同时为兼顾技术准确性，以下刻意保留英文：

代码路径、URL、类名、方法名、属性名、类型名、枚举值
内联代码（code）、JS 代码块
WebGL、3D、URL 等专有缩写
optional、构造函数选项骨架（Object with the following properties:）、表头（Name/Type/Description）等

5.2 翻译约定（术语一致性）

专有名词与代码标识符不翻译 ，如 Cartesian3、Entity、buildModuleUrl。
通用术语建立统一译法，如 Globe→地球、Camera→相机、Terrain→地形、Imagery→影像、Primitive→图元。
长句按中文表达习惯拆分，优先"信、达"，兼顾"雅"。

六、快速上手示例

下面一个最小可运行示例，展示如何创建一个带地形与影像的 Cesium 地球，并添加一个实体。对照中文版 API 阅读 Viewer、Cartesian3、Color 等类的说明，可更快理解每个参数的含义。

html 复制代码

<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="utf-8">
  <title>我的第一个 Cesium 应用</title>
  <script src="https://cesium.com/downloads/cesiumjs/releases/1.143/Build/Cesium/Cesium.js"></script>
  <link href="https://cesium.com/downloads/cesiumjs/releases/1.143/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
  <style>#cesiumContainer { width: 100%; height: 100vh; }</style>
</head>
<body>
  <div id="cesiumContainer"></div>
  <script>
    // 创建 Viewer（详见中文版 API：Viewer 类）
    const viewer = new Cesium.Viewer('cesiumContainer', {
      terrain: Cesium.Terrain.fromWorldTerrain(),
      baseLayer: Cesium.ImageryLayer.fromWorldImagery()
    });

    // 添加一个实体（详见中文版 API：Entity、Cartesian3、Color）
    viewer.entities.add({
      name: '示例点',
      position: Cesium.Cartesian3.fromDegrees(116.39, 39.9, 100),
      point: { pixelSize: 12, color: Cesium.Color.RED },
      label: { text: '北京', font: '16pt sans-serif', pixelOffset: new Cesium.Cartesian2(0, -24) }
    });

    // 飞向该位置（详见中文版 API：Camera.flyTo）
    viewer.camera.flyTo({
      destination: Cesium.Cartesian3.fromDegrees(116.39, 39.9, 1500000)
    });
  </script>
</body>
</html>