立即体验 • 快速上手 • 示例中心 • API 文档 • EarthUI 开源地址
简体中文 | English
EarthSDK 是一套基于 JavaScript/TypeScript 的开源免费三维地球可视化二次开发框架。整套框架独立于渲染引擎之外，不依赖特定引擎，与可视化引擎互为插件。它不是简单的封装层，而是赋能原生引擎，实现了数字孪生项目所需的全部基础功能和效果，并支持一套代码多引擎无缝切换。
EarthSDK 最初于 2019 年发布，经历多次重大迭代：
| 时间 | 版本 | 说明 |
|---|---|---|
| 2019 年 | EarthSDK 1 | 依赖 Cesium 引擎，提供大量易用性扩展 |
| 2022 年 11 月 | EarthSDK 2 | 整合 Cesium 与 Unreal Engine 两种引擎实现 |
| 2024 年 10 月 | EarthSDK 3 | 模块化拆分，支持灵活组合不同引擎模块 |
EarthSDK 3 目前支持以下渲染引擎,多引擎秒切换,未来还将扩展更多：
| 引擎 | 包名 | 说明 |
|---|---|---|
| Cesium JS | earthsdk3-cesium |
浏览器端 WebGL 地球可视化渲染 |
| Unreal Engine | earthsdk3-ue |
本地/云端高质量渲染，支持像素流 |
| OpenLayers | earthsdk3-ol |
二维地图可视化渲染 |
| H5 WebGL | earthsdk3-h5 |
UE 在浏览器中以 WebGL 方式运行 |
EarthSDK 3 内置 100+ 种场景对象，涵盖数字孪生各类应用场景：
- 数据加载: 3DTileset、glTF 模型、影像图层、地形图层、矢量数据等
- 地理矢量: GeoJSON、多边形、线串、矩形、拉伸多边形、贝塞尔曲线等
- 分析工具: 视域分析、日照分析、淹没分析、控高分析、天际线分析、体积测量等
- 测量工具: 距离测量、面积测量、高度测量、方向测量、位置测量等
- 特效对象: 动态水面、爆炸粒子、火焰粒子、高斯溅射等
- 可视化: POI、文本标签、图片标签、热力图、聚合图层等
- 地形编辑: 挖掘、裁剪平面、盒子裁剪等
EarthSDK 3 支持根据项目需求灵活选择部署模式：
| 部署方式 | 技术栈 | 适用场景 |
|---|---|---|
| WebGL 渲染 | EarthSDK JS + Cesium JS | 纯浏览器端渲染，零部署 |
| 像素流渲染 | EarthSDK JS + UE + ESForUE + ESSS | 云渲染，高画质，支持大规模场景 |
| 本地大屏 | EarthSDK JS + UE + ESWebView | 本地部署，低延迟，高画质 |
| H5 模式 | EarthSDK JS + H5 | UE 以 WebGL 方式在浏览器运行 |
- 基于 TypeScript 构建，提供完整的类型安全
- 内置响应式变量系统，支持数据绑定和变更通知
- 所有对象支持 JSON 序列化/反序列化
- 组件化设计模式，模块职责清晰
- Node.js >= 18
- pnpm / npm / yarn
# 安装核心
pnpm add earthsdk3 --save
EarthSDK 核心包是必装的，引擎包可根据业务需求选择：
# Cesium 引擎（必选其一）
pnpm add earthsdk3-cesium --save
# Unreal Engine 引擎
pnpm add earthsdk3-ue --save
# OpenLayers 引擎
pnpm add earthsdk3-ol --save安装
earthsdk3-cesium时需要额外安装配置 Cesium。安装earthsdk3-ol时需要额外安装ol（当前支持版本^7.1.0）。
创建 ESObjectsManager 对象管理器，通过泛型参数注册需要使用的引擎：
import { ESObjectsManager } from "earthsdk3";
import { ESCesiumViewer } from "earthsdk3-cesium";
import { ESUeViewer } from "earthsdk3-ue";
import { ESOlViewer } from "earthsdk3-ol";
// 创建对象管理器，同时注册多个引擎
const objm = new ESObjectsManager(ESCesiumViewer, ESUeViewer, ESOlViewer);
// 创建 Cesium 视口
const viewer = objm.createViewer({
type: "ESCesiumViewer",
container: "container-id-or-element",
});
//创建一个基础影像图层
const imageryLayer = objm.createSceneObjectFromJson({
id: "94f8b01b-8659-4a34-942b-15e6ece246ca",
type: "ESImageryLayer",
name: "全球影像",
url: "https://server.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}",
maximumLevel: 18,
});
如不方便使用构建工具，可通过 IIFE 方式直接引入：
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<link
href="https://cesium.com/downloads/cesiumjs/releases/1.123/Build/Cesium/Widgets/widgets.css"
rel="stylesheet"
/>
<script src="https://cesium.com/downloads/cesiumjs/releases/1.123/Build/Cesium/Cesium.js"></script>
<script src="js/earthsdk3.iife.js"></script>
<script src="js/earthsdk3-cesium.iife.js"></script>
<script src="js/earthsdk3-ue.iife.js"></script>
<script src="js/earthsdk3-ol.iife.js"></script>
</head>
<body>
<div id="viewerContainer"></div>
<script>
const { ESObjectsManager } = window["EarthSDK3"];
const { ESCesiumViewer } = window["EarthSDK3_Cesium"];
const { ESUeViewer } = window["EarthSDK3_UE"];
const { ESOlViewer } = window["EarthSDK3_OL"];
// 创建对象管理器
const objm = new ESObjectsManager();
// 创建视口
const viewer = objm.createViewer({
type: "ESCesiumViewer",
container: "viewerContainer",
});
//创建一个基础影像图层
const imageryLayer = objm.createSceneObjectFromJson({
id: "94f8b01b-8659-4a34-942b-15e6ece246ca",
type: "ESImageryLayer",
name: "全球影像",
url: "https://server.arcgisonline.com/arcgis/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}",
maximumLevel: 18,
});
</script>
</body>
</html>对象管理器，负责管理所有场景对象和视口实例，以下列出一部分。
| 方法 | 说明 |
|---|---|
createViewer(option) |
创建视口实例 |
createSceneObject(type, id?) |
创建场景对象 |
getSceneObject(option?) |
按类型或 ID 获取场景对象 |
destroySceneObject(obj) |
销毁场景对象 |
switchViewer(option, viewSync?, attributeSync?, destroy?) |
切换视口 |
createCesiumViewer(params) |
创建 Cesium 视口 |
createOpenLayersViewer(params) |
创建 OpenLayers 视口 |
createUeViewer(params) |
创建 UE 视口 |
视口基类，定义统一的视口操作接口，以下列出一部分。
| 方法 | 说明 |
|---|---|
flyTo(flyToParam, position, flyMode?) |
飞行到目标位置 |
flyIn(position, rotation?, duration?, flyMode?) |
飞入动画 |
pick(screenPosition) |
拾取对象 |
pickPosition(screenPosition) |
获取地面坐标 |
changeToWalk(position, jumpZVelocity?, eyeHeight?) |
切换到步行模式 |
changeToMap() |
切换到地图模式 |
changeToRotateGlobe(latitude?, height?, cycleTime?) |
切换到旋转地球模式 |
capture(resx?, resy?) |
捕获视口图像 |
# 克隆仓库
git clone https://github.com/cesiumlab/earthsdk3-code.git
# 安装依赖
pnpm install
# 切换调试/构建模式
node change-mode.js debug # main 指向源码
# 启动开发模式
pnpm run dev-app1# 切换调试/构建模式
node change-mode.js build # main 指向发布产物
# 构建所有包
pnpm run build-earthsdk3
pnpm run build-earthsdk3-cesium
pnpm run build-earthsdk3-ue
pnpm run build-earthsdk3-ol本开发包版权归 北京西部世界科技有限公司 所有。
基于 ISC 许可证 开源。
- 🌐 官方网站: www.earthsdk.com
- 🌏 公众号: 地球可视化实验室
- 🌐 公司官网: 北京西部世界科技有限公司
- 🌐 CesiumLab 地理信息基础数据处理平台: CesiumLab
- 🌐 PipeSer 管线管网云服务: PipeSer
- 🌐 ModelSer 实景三维数据分布式管理平台: ModelSer
- 🌐 CIMRTS 城市信息模型数据服务平台: CIMRTS
- 🌐 TerrainRTS 地形高程数据实时切片服务平台: CIMRTS
Built with ❤️ by 北京西部世界科技有限公司