【Cesium】介绍及基础使用

文章目录

一、Cesium 介绍
二、使用
- 1、引入 cesium
- 2、Viewer 配置选项
- - 1. 基础控件配置
  - 2. 场景与渲染配置
  - 3. 地形配置
  - 4. 天空与大气效果
- 3、坐标系系统
- - 3.1 地理坐标系
  - 3.2 笛卡尔空间直角坐标系
  - 3.3 屏幕坐标系
- 4、Entity 实体
- - 4.1 简介
  - 4.2 Entity 常见图形类型
  - - Point 点
    - Polyline 线
    - Polygon 多边形
    - Label 文本
    - Billboard 广告牌
    - Model 模型
  - 4.3 DataSource 数据源
  - - GeoJsonDataSource
    - KmlDataSource
    - CzmlDataSource
- 5、Camera
- - 5.1 核心属性
  - 5.2 位置控制方法
  - - 1. setView(options)
    - 2. flyTo(options)
    - 3. lookAt(target, offset)
  - 5.3 视角控制方法
  - 5.4 控制模式
  - 5.5 事件
- 6、Scene
- - 6.1 常用属性
  - 6.2 常用方法
  - - 1. pick
  - 6.3 事件

一、Cesium 介绍

CesiumJS 是一个开源 JavaScript 库，用于创建具有最佳性能、精度、视觉质量和易用性的世界级 3D 地球仪和地图

官网： https://cesium.com/
官方示例： https://sandcastle.cesium.com/
API文档： https://cesium.com/learn/cesiumjs/ref-doc/
Cesium 中文网： http://cesium.xin/

二、使用

注：当前使用的是 1.132 版本

1、引入 cesium

两种方式引入:

从 CDN 导入
使用 NPM 安装

（1）使用 CDN，如下示例：

<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><script src="https://cesium.com/downloads/cesiumjs/releases/1.132/Build/Cesium/Cesium.js"></script><link href="https://cesium.com/downloads/cesiumjs/releases/1.132/Build/Cesium/Widgets/widgets.css" rel="stylesheet">
</head>
<body><div id="cesiumContainer"></div><script type="module">Cesium.Ion.defaultAccessToken = 'your_access_token';const viewer = new Cesium.Viewer('cesiumContainer');    </script></div>
</body>
</html>

（2）使用 npm

npm install cesium

使用示例：

import { Viewer } from 'cesium';
import "cesium/Build/Cesium/Widgets/widgets.css";const viewer = new Viewer('cesiumContainer');

2、Viewer 配置选项

new Cesium.Viewer(container, options)

options所有可配选项：Cesium.Viewer.ConstructorOptions

1. 基础控件配置

animation
Boolean，默认 true
控制是否显示左下角的动画控件（播放/暂停/时间倍率调整）
baseLayerPicker
Boolean，默认 true
是否显示右上角的底图选择器（切换影像/地形）
fullscreenButton
Boolean，默认 true
是否显示全屏按钮
geocoder
Boolean | Array，默认 true
是否显示地理编码搜索框（支持地名搜索）
homeButton
Boolean，默认 true
是否显示"返回初始视角"按钮
infoBox
Boolean，默认 true
点击实体时是否显示信息框
sceneModePicker
Boolean，默认 true
是否显示场景模式切换按钮（3D/2D/哥伦布视图）
timeline
Boolean，默认 true
是否显示时间轴控件
navigationHelpButton
Boolean，默认 true
是否显示操作帮助按钮

2. 场景与渲染配置

scene3DOnly
Boolean，默认 false
设为true时所有几何体仅以3D模式渲染（节省GPU内存）
sceneMode
Cesium.SceneMode，默认 SCENE3D
初始场景模式（SCENE2D/SCENE3D/COLUMBUS_VIEW）
mapProjection
MapProjection，默认 GeographicProjection
2D/哥伦布视图使用的地图投影方式
shadows
Boolean，默认 false
是否启用光源阴影
terrainShadows
ShadowMode，默认 RECEIVE_ONLY
地形是否投射/接收阴影
requestRenderMode
Boolean，默认 false
是否启用按需渲染模式（减少资源占用）

3. 地形配置

terrainProvider

示例：

terrainProvider: await Cesium.createWorldTerrainAsync()

4. 天空与大气效果

skyBox
SkyBox | false
自定义星空背景，设为false可禁用
skyAtmosphere
SkyAtmosphere | false
是否显示地球大气层辉光效果

3、坐标系系统

3.1 地理坐标系

Cartographic
- 表示 WGS84 弧度坐标系（经度、纬度、高度，单位为弧度）。
- 使用 Cesium.Cartographic(longitude, latitude, height) 表示，其中经度和纬度为弧度值
- 主要方法：
  - Cartographic.fromDegrees(longitude, latitude, height)（角度转弧度）
  - Cartographic.fromRadians(longitude, latitude, height)（直接使用弧度）
  - Cartographic.fromCartesian(cartesian3)（笛卡尔坐标转地理坐标）

3.2 笛卡尔空间直角坐标系

Cartesian3
- 表示 3D 笛卡尔坐标（x, y, z），原点在地球中心。
  - X轴指向本初子午线(经度0°)与赤道(纬度0°)的交点
  - Z轴指向北极
  - Y轴与X、Z轴构成右手坐标系，指向东经90°与赤道的交点
- 用于三维空间计算，如模型变换、相机控制等
- 通过 Cesium.Cartesian3(x, y, z) 定义
- 主要方法：
  - Cartesian3.fromDegrees(longitude, latitude, height)
    - 经纬度转笛卡尔坐标
  - Cesium.Cartesian3.fromDegreesArray(coordinates)
    - 返回一个 Cartesian3 位置数组，给定一个以度为单位给出的经度和纬度值数组
  - Cesium.Cartesian3.fromDegreesArrayHeights(coordinates)
    - 返回一个笛卡尔3位置数组，给定经度、纬度和高度值数组，其中经度和纬度以度为单位。
  - Cartesian3.fromRadians(longitude, latitude, height)
    - 弧度转笛卡尔坐标
  - Cartesian3.fromElements(x, y, z)（直接构造)

3.3 屏幕坐标系

用于与屏幕交互的 2D 坐标系：
- 原点在画布左上角
- X轴向右，Y轴向下单位：像素
- 使用 Cartesian2 表示

示例：

const handler = new Cesium.ScreenSpaceEventHandler(viewer.scene.canvas);
handler.setInputAction((event) => {const screenPosition = event.position; // Cartesian2 类型console.log("点击屏幕坐标:", screenPosition.x, screenPosition.y);// 转换为世界坐标const ray = viewer.camera.getPickRay(screenPosition);const cartesian3Position = viewer.scene.globe.pick(ray, viewer.scene);  // Cartesian3 类型if (cartesian3Position) {console.log("对应的世界坐标:", cartesian3Position);}
}, Cesium.ScreenSpaceEventType.LEFT_CLICK);

4、Entity 实体

4.1 简介

实体实例将多种形式的可视化聚合到单个高级对象中。
它们可以手动创建，并添加到数据源 Viewer#entities
或由数据源生成，例如 CzmlDataSource 和 GeoJsonDataSource 。

entity 配置选项文档：Entity.html#.ConstructorOptions

Entity 常用方法：
添加 Entity

const entity = viewer.entities.add({ /* 配置 */ });

移除 Entity

viewer.entities.remove(entity);

查找 Entity

const entity = viewer.entities.getById('unique-id');

集合操作

// 移除所有实体
viewer.entities.removeAll();// 显示/隐藏所有实体
viewer.entities.show = false;

4.2 Entity 常见图形类型

Point 点

属性文档： PointGraphics.html#.ConstructorOptions

示例：

viewer.entities.add({name: "RedPoint",position: Cesium.Cartesian3.fromDegrees(-75, 35),point: {show: true,pixelSize: 30,color: Cesium.Color.RED,},
});

Polyline 线

属性文档： PolylineGraphics.html#.ConstructorOptions

示例：

viewer.entities.add({name: "Red line on terrain",polyline: {positions: Cesium.Cartesian3.fromDegreesArray([-75, 35, -125, 35]),width: 5,material: Cesium.Color.RED,},
});

官方示例： Polyline 示例

Polygon 多边形

属性文档： PolygonGraphics.html#.ConstructorOptions

示例：

viewer.entities.add({name: "Red polygon",polygon: {hierarchy: Cesium.Cartesian3.fromDegreesArray([118.12, 24.69, 118.22, 24.69, 118.22, 24.79, 118.12, 24.79]),height: 10,material: Cesium.Color.RED.withAlpha(0.5),outline: true,outlineColor: Cesium.Color.BLUE,},
});

官方示例： Polygon 示例

Label 文本

属性文档： LabelGraphics.html#.ConstructorOptions

示例：

viewer.entities.add({position: Cesium.Cartesian3.fromDegrees(-75.1641667, 39.9522222),label: {text: "Philadelphia",font: "24px Helvetica",fillColor: Cesium.Color.SKYBLUE,outlineColor: Cesium.Color.BLACK,outlineWidth: 2,style: Cesium.LabelStyle.FILL_AND_OUTLINE,scale: 2.0,showBackground: true,},
});

Billboard 广告牌

属性文档： BillboardGraphics.html#.ConstructorOptions

示例：

viewer.entities.add({position: Cesium.Cartesian3.fromDegrees(-75.59777, 40.03883),billboard: {show: true,image: "./dist/assets/Cesium_Logo_Color.jpg",scale: 1,width: 100,height: 25,},
});

官方示例： Billboards 示例

Model 模型

Cesium 支持加载多种格式的 3D 模型，包括 glTF/GLB (推荐)、OBJ 等格式

属性文档： ModelGraphics.html#.ConstructorOptions

示例：

const entity =  viewer.entities.add({name: "air",position: Cesium.Cartesian3.fromDegrees(-123.0744619, 44.0503706),model: {uri: './dist/SampleData/models/CesiumDrone/CesiumDrone.glb',minimumPixelSize: 128,maximumScale: 2000,},
});
viewer.zoomTo(entity);

官方示例： Models 示例

4.3 DataSource 数据源

GeoJsonDataSource

A DataSource 处理 GeoJSON 和 TopoJSON 数据

GeoJSON 介绍：点击查看

示例：

viewer.dataSources.add(Cesium.GeoJsonDataSource.load('../../SampleData/ne_10m_us_states.topojson', {stroke: Cesium.Color.HOTPINK,fill: Cesium.Color.PINK,strokeWidth: 3,markerSymbol: '?'})
);

API文档： GeoJsonDataSource
官方示例： GeoJSON 和 TopoJSON

KmlDataSource

A DataSource 处理 Keyhole Markup Language 2.2 （KML）
KML 标准： https://www.ogc.org/standards/kml/

示例：

viewer.dataSources.add(Cesium.KmlDataSource.load("../SampleData/kml/facilities/facilities.kml",{camera: viewer.scene.camera,canvas: viewer.scene.canvas,},),
);

API文档： KmlDataSource
官方示例： KML 示例

CzmlDataSource

处理 DataSource CZML。
API文档： CzmlDataSource
官方示例： CZML Demo
CZML 指南: CZML-Guide
CZML Packet - CZML 文档/流中存在的标准内容的架构 /czml-writer/wiki/Packet

CZML 是 Cesium 的专有数据格式，具有以下特点：

基于 JSON 的文本格式
用于描述随时间变化的场景
支持点、线、面、模型、标签等多种可视化元素
支持时间动态属性（位置、颜色、大小等随时间变化）

示例：

const czml = [{id: "document",name: "Basic CZML billboard and label",version: "1.0",},{id: "some-unique-id",name: "AGI",billboard: {show: true,image: "./dist/assets/Cesium_Logo_Color.jpg",scale: 1,width: 100,height: 25,},position: {cartesian: [1216361.4096947117, -4736253.175342511, 4081267.4865667094], // },},{id: "some-unique-id2",name: "Label Demo",label: {show: true,text: "Label文本",font: "18px sans-serif",},position: {cartographicDegrees: [-91.17466499519793, 40.31480547471602, 0]},}
]
viewer.dataSources.add(Cesium.CzmlDataSource.load(czml));

5、Camera

官方API: https://cesium.com/learn/cesiumjs/ref-doc/Camera.html
相机由位置、方向和视锥体定义。
作用：控制场景的观察视角和位置

5.1 核心属性

position: Cartesian3 相机位置
direction : Cartesian3 相机的观察方向
DEFAULT_VIEW_RECTANGLE：创建时相机将查看的默认矩形

示例：

// 获取相机位置
const position = viewer.camera.position;// 获取相机方向向量
const direction = viewer.camera.direction;// 设置全局默认视角为中国上空
// 在创建 Viewer 实例之前，设置默认的视图矩形区域
Cesium.Camera.DEFAULT_VIEW_RECTANGLE = Cesium.Rectangle.fromDegrees(75.0, // 西经 (West Longitude)0.0,  // 南纬 (South Latitude)140.0, // 东经 (East Longitude)60.0  // 北纬 (North Latitude)
);
const viewer = new Cesium.Viewer("cesiumContainer");

5.2 位置控制方法

1. setView(options)

设置相机位置、方向和变换。

options属性：

destination 摄像机在世界坐标中的最终位置或从自上而下视图可见的矩形。
orientation 包含方向和向上属性或航向、俯仰和滚动属性的对象。默认情况下，方向在 3D 视图中指向帧的中心，在哥伦布视图中指向负 z 方向。向上方向将在 3D 中指向当地北方，在哥伦布视图中指向正 y 方向。在无限滚动模式下，在 2D 中不使用方向
endTransform
convert

示例1：

viewer.camera.setView({destination : Cesium.Cartesian3.fromDegrees(-117.16, 32.71, 15000.0)
});

示例2：

viewer.camera.setView({destination: Cesium.Cartesian3.fromDegrees(116.39, 39.91, 10000.0),orientation: {heading: Cesium.Math.toRadians(0.0),    // 偏航角pitch: Cesium.Math.toRadians(-90.0),    // 俯仰角roll: 0.0                               // 翻滚角}
});

2. flyTo(options)

将相机从当前位置飞行到新位置。
options:

destination 摄像机在世界坐标中的最终位置
orientation 包含方向和向上属性或航向、俯仰和滚动属性的对象
duration 飞行持续时间（以秒为单位）
complete 完成时要执行的函数
cancel 取消时要执行的函数

示例：

viewer.camera.flyTo({destination: Cesium.Cartesian3.fromDegrees(116.39, 39.91, 2000.0),duration: 3.0,  // 飞行时间（秒）complete: function() {console.log('飞行完成');}
});

3. lookAt(target, offset)

使用目标和偏移设置相机位置和方向。目标必须以世界坐标给出

name	type	描述
target	Cartesian3	世界坐标中的目标位置
offset	Cartesian3\|HeadingPitchRange	以目标为中心的局部东西向上参考系中与目标的偏移量。

示例：

viewer.camera.lookAt(Cesium.Cartesian3.fromDegrees(116.39, 39.91, 1000.0), // 目标点new Cesium.HeadingPitchRange(0.0, -1.57, 1000.0)      // 相对偏移
);

5.3 视角控制方法

1. 旋转相机：
注： angle：旋转的角度，以弧度为单位

viewer.camera.rotate(axis, angle);  // 绕轴旋转
viewer.camera.rotateUp(angle);         // 向上旋转
viewer.camera.rotateDown(angle);       // 向下旋转
viewer.camera.rotateLeft(angle);       // 向左旋转
viewer.camera.rotateRight(angle);      // 向右旋转

2. 移动相机
注： amount：移动的量，以米为单位

viewer.camera.move(direction, amount);  // 沿方向移动
viewer.camera.moveForward(amount);     // 向前移动
viewer.camera.moveBackward(amount);    // 向后移动
viewer.camera.moveUp(amount);          // 向上移动
viewer.camera.moveDown(amount);        // 向下移动
viewer.camera.moveLeft(amount);        // 向左移动
viewer.camera.moveRight(amount);       // 向右移动

3. 缩放
注： amount：移动的量，以米为单位

viewer.camera.zoomIn(amount);          // 放大
viewer.camera.zoomOut(amount);         // 缩小

5.4 控制模式

// 获取相机控制器
const controller = viewer.scene.screenSpaceCameraController;// 配置控制参数
controller.enableRotate = true;        // 允许旋转
controller.enableTranslate = true;     // 允许平移
controller.enableZoom = true;          // 允许缩放
controller.enableTilt = true;          // 允许倾斜
controller.enableLook = true;          // 允许环视// 灵敏度设置
controller.zoomFactor = 2.0;           // 缩放灵敏度
controller.rotateFactor = 1.0;         // 旋转灵敏度

5.5 事件

// 相机移动事件
viewer.camera.moveStart.addEventListener(function() {console.log('相机开始移动');
});viewer.camera.moveEnd.addEventListener(function() {console.log('相机移动结束');
});

6、Scene

Cesium 场景中所有3D图形对象和状态的容器。通常，场景不是直接创建的；而是由CesiumWidget隐式创建。

官方API: https://cesium.com/learn/cesiumjs/ref-doc/Scene.html

Scene 的作用:

管理场景中所有可视化对象（实体、图元、数据源等）
控制渲染流程和渲染状态
处理场景的视觉效果（光照、雾、大气等）
管理相机和视图变换

Scene 的层级结构:

// Scene 包含的主要组件
const scene = viewer.scene;
const globe = scene.globe;           // 地球对象
const camera = scene.camera;         // 相机对象
const primitives = scene.primitives; // 图元集合
const groundPrimitives = scene.groundPrimitives; // 地面图元集合

6.1 常用属性

场景模式属性：

// 场景模式
scene.mode = Cesium.SceneMode.SCENE3D; // 3D模式
// scene.mode = Cesium.SceneMode.SCENE2D; // 2D模式
// scene.mode = Cesium.SceneMode.COLUMBUS_VIEW; // 哥伦布视图

globe（地球）
文档： Globe
示例：

viewer.scene.globe.show = false

Primitives（图元）
文档： PrimitiveCollection
示例：

viewer.scene.primitives.add(primitive); // 添加图元
scene.primitives.remove(primitive);   // 移除图元
scene.primitives.removeAll();         // 移除所有图元
scene.primitives.lowerToBottom(primitive); // 移动到底层
scene.primitives.raiseToTop(primitive);    // 移动到顶层

6.2 常用方法

1. pick

pick (windowPosition, width , height )
返回具有’ primitive’属性的对象，该对象包含场景中的第一个（顶部）基本体在特定的窗口坐标处
示例：

const handler = new Cesium.ScreenSpaceEventHandler(scene.canvas);
handler.setInputAction(function(movement) {const feature = scene.pick(movement.endPosition);console.log('feature', feature)
}, Cesium.ScreenSpaceEventType.MOUSE_MOVE);

对比 drillPick ：
pick ：方法只返回鼠标位置最顶层的可见对象；如果多个对象重叠，只返回最上面的一个
drillPick：方法返回鼠标位置的所有对象（从顶层到底层）；适合需要选择多个重叠对象的场景

6.3 事件

postRender
获取将在渲染场景后立即引发的事件。
活动订阅者接收Scene实例作为第一个参数，并接收当前时间作为第二个参数。

preRender
获取在场景更新之后以及场景渲染之前立即引发的事件。
事件的订阅者将Scene实例作为第一个参数，将当前时间作为第二个参数参数。

preUpdate
获取在更新或渲染场景之前将引发的事件。
活动订阅者接收Scene实例作为第一个参数，并接收当前时间作为第二个参数。

示例：

// 预渲染事件
scene.preRender.addEventListener(function(scene, time) {// 每帧渲染前执行console.log('预渲染:', scene);
});// 渲染后事件
scene.postRender.addEventListener(function(scene, time) {// 每帧渲染后执行console.log('渲染完成:', scene);
});