---
name: earthsdk3-dev
description: EarthSDK3 开发者文档。当用户问"EarthSDK3 是什么/项目架构/多引擎支持/部署方式"、"如何安装 earthsdk3"、"如何从源码克隆、构建、启动开发 earthsdk3"、"如何参与贡献代码"、"开发调试 / 构建打包 命令怎么用"、"引擎包怎么选"等时使用。包含项目简介、核心特性、安装、快速开始、开发构建指南、贡献规范与社区资源。
---

# EarthSDK3 开发者文档

本技能是 **EarthSDK3 的开发者文档**，面向参与 EarthSDK3 开发、构建与贡献的开发者及其 AI 助手。涵盖项目简介、核心特性、安装、快速开始、核心 API、从源码开发与构建、贡献规范。

## 何时使用

- 用户问 EarthSDK3 是什么、项目定位、版本演进历史
- 用户问多引擎支持（Cesium / UE / OpenLayers）与各引擎包名
- 用户问部署方式（WebGL 渲染 / 像素流 / 本地大屏 / H5 模式）
- 用户要安装 earthsdk3、选择引擎包、配置 Cesium / ol
- 用户要从源码开发 earthsdk3：克隆仓库、`change-mode.js`、`pnpm run dev-app1`
- 用户要构建 earthsdk3：`build-earthsdk3` 系列命令
- 用户要参与贡献：Fork、分支规范、代码风格

## 简介

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`     | 二维地图可视化渲染              |

### 丰富的场景对象

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

### 安装 EarthSDK 核心包

```sh
# 安装核心
pnpm add earthsdk3 --save
```

### 按需安装引擎包

EarthSDK 核心包是必装的，引擎包可根据业务需求选择：

```sh
# Cesium 引擎（必选其一）
pnpm add earthsdk3-cesium --save

# Unreal Engine 引擎
pnpm add earthsdk3-ue --save

# OpenLayers 引擎
pnpm add earthsdk3-ol --save
```

> 安装 `earthsdk3-cesium` 时需要额外[配置 Cesium](https://cesium.com/blog/2024/02/13/configuring-vite-or-webpack-for-cesiumjs/)。安装 `earthsdk3-ol` 时需要额外安装 `ol`。

## 快速开始

### 初始化对象管理器

创建 `ESObjectsManager` 对象管理器，通过泛型参数注册需要使用的引擎：

```typescript
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 方式直接引入：

```html
<!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>
```

## 开发指南

### 环境搭建

```sh
# 克隆仓库
git clone https://github.com/cesiumlab/earthsdk3-code.git

# 安装依赖
pnpm install

# 切换调试/构建模式
node change-mode.js debug   # main 指向源码

# 启动开发模式
pnpm run dev-app1
```

### 构建

```sh
# 切换调试/构建模式
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
```

## 许可证

本开发包版权归 [北京西部世界科技有限公司](https://www.bjxbsj.cn) 所有。

基于 [MIT 许可证](LICENSE) 开源。

## 参与贡献

我们欢迎社区的各种贡献！无论是修复 Bug、开发新功能、改进文档还是翻译——每一份贡献都让 EarthSDK 变得更好。

### 如何贡献

#### Fork 本仓库

- 创建 功能分支（`git checkout -b feature/amazing-feature`）
- 提交 清晰描述的变更
- 推送 到你的分支
- 创建 Pull Request

#### 贡献规范

- 遵循现有代码风格（ESLint + Prettier）
- 为新功能编写测试
- 按需更新文档
- 保持提交原子化且描述清晰

## 社区与支持

- 🌐 官方网站: [www.earthsdk.com](https://www.earthsdk.com)
- 🌏 公众号: 地球可视化实验室
- 🌐 公司官网: [北京西部世界科技有限公司](https://www.bjxbsj.cn)
- 🌐 CesiumLab 地理信息基础数据处理平台: [CesiumLab](https://www.bjxbsj.cn/cesiumlab.html)
- 🌐 PipeSer 管线管网云服务: [PipeSer](https://www.bjxbsj.cn/pipeser.html)
- 🌐 ModelSer 实景三维数据分布式管理平台: [ModelSer](https://www.bjxbsj.cn/modelser.html)
- 🌐 CIMRTS 城市信息模型数据服务平台: [CIMRTS](https://www.bjxbsj.cn/cimrts.html)
- 🌐 TerrainRTS 地形高程数据实时切片服务平台: [TerrainRTS](https://www.bjxbsj.cn/terrainrts.html)
