mapv-cloudrenderengine/README.md

CloudRenderEngine 是百度地图开放平台推出的 UE5 像素流三维数字孪生前端 SDK。 它通过 WebRTC 将 Unreal Engine 5 场景实时推流到浏览器，并提供统一 JavaScript API 完成场景渲染、交互控制、对象管理和行业可视化能力接入。

# CloudRenderEngine 🌐

CloudRenderEngine 是百度地图开放平台推出的 UE5 像素流三维数字孪生前端 SDK。  
它通过 WebRTC 将 Unreal Engine 5 场景实时推流到浏览器，并提供统一 JavaScript API 完成场景渲染、交互控制、对象管理和行业可视化能力接入。

适用场景包括智慧城市、智慧交通、园区管理、文旅展陈、BIM 可视化、实时监控和数字底座应用。

---

## 产品能力 ✨

- **云渲染交互**：浏览器低门槛接入 UE5 高保真场景，支持鼠标/触控/键盘交互。
- **地图级可视化**：支持点、线、面、热力、雷达、粒子、轨迹、标签等对象体系。
- **行业对象能力**：支持交通、资产、路况、监控、信息牌等业务对象挂接。
- **相机与动画系统**：支持飞行、巡航、关键帧导航、场景切换。
- **环境控制能力**：支持天气、时间、光照等全局场景调度。
- **WebRTC 监控诊断**：可监控连接质量、码率、丢包与延迟指标。

---

## 安装与引入 📦

包名：`mapv-cloudrenderengine`

```bash
npm install mapv-cloudrenderengine
```

```javascript
import * as Engine from 'mapv-cloudrenderengine';
```

---

## 必备前提 ✅

云渲染模式下，页面必须提供 `id="player"` 的容器作为视频输出目标：

```html
<div id="player" style="width: 100vw; height: 100vh;"></div>
```

建议 `player` 全屏铺设，并将业务 UI 通过更高 `z-index` 叠加显示。

---

## 最小可运行示例（React） 🚀

```jsx
import { useEffect } from 'react';
import * as Engine from 'mapv-cloudrenderengine';

export default function App() {
    useEffect(() => {
        Engine.CloudRenderEngine.DispatchServer.host = 'http://your-dispatch-host:8017';

        const engine = new Engine.CloudRenderEngine({
            projectName: 'your-project-name',
            connectOnLoad: true,
            shouldShowPlayOverlay: false,
            matchViewportResolution: true,
        });

        engine.load(
            () => console.log('connected'),
            err => console.error('load error', err)
        );

        engine.addEventListener('videoInitialised', () => {
            console.log('video ready');
        });

        return () => {
            // 业务侧可在此处补充销毁逻辑
        };
    }, []);

    return <div id="player" style={{ width: '100vw', height: '100vh' }} />;
}
```

---

## 快速开始 🧭

CloudRenderEngine 支持两种接入模式：

1. **调度服务模式（推荐）**：通过调度服务分配 UE5 渲染实例，适合生产环境。
2. **单机像素流模式**：直连单实例流服务，适合本地调试或固定部署场景。

### 1) 调度服务模式（推荐） ☁️

```javascript
import * as Engine from 'mapv-cloudrenderengine';

// 1. 配置调度服务
Engine.CloudRenderEngine.DispatchServer.host = 'http://your-dispatch-host:8017';
Engine.CloudRenderEngine.DispatchServer.tag = 'all'; // 可选
Engine.CloudRenderEngine.DispatchServer.username = 'admin'; // 可选
Engine.CloudRenderEngine.DispatchServer.password = 'admin'; // 可选

// 2. 检查可用容量（建议）
const capacity = await Engine.CloudRenderEngine.DispatchServer.GetAllCapacityInfo();
if (!capacity || capacity.all <= 0) {
    throw new Error('服务器暂无可用渲染容量');
}

// 3. 初始化引擎
const engine = new Engine.CloudRenderEngine({
    projectName: 'your-project-name',
    connectOnLoad: true,
    shouldShowPlayOverlay: false,
    matchViewportResolution: true,
});

// 4. 连接并监听状态
engine.load(
    () => console.log('调度成功'),
    err => console.error('调度失败', err)
);

engine.addEventListener('videoInitialised', () => {
    console.log('画面就绪，可以安全调用场景 API');
});

engine.addEventListener('signalingServerError', () => {
    console.error('信令服务连接异常');
});
```

### 2) 单机像素流模式 🖥️

```javascript
import * as Engine from 'mapv-cloudrenderengine';

const engine = new Engine.CloudRenderEngine({
    wsUrl: 'ws://your-pixel-streaming-signaling',
    connectOnLoad: true,
    shouldShowPlayOverlay: false,
    matchViewportResolution: true,
});

engine.load();
engine.addEventListener('videoInitialised', () => {
    console.log('画面就绪');
});
```

---

## 常用 API 模式 🛠️

### 场景对象增删 🧱

```javascript
const line = new Engine.Line({ color: { r: 0, g: 1, b: 0 }, width: 5 });
line.setData(geojsonData);
engine.addToScene(line);

// 资源释放
engine.destoryObject(line);
```

### 相机飞行与巡航 🎥

```javascript
engine.moveTo(
    { x: 116.404, y: 39.915, z: 500 },
    { roll: 0, pitch: -45, yaw: 0 },
    { duration: 2.0, zoom: 1500 }
);

engine.navigateByKeypoints(
    [[116.40, 39.91, 20, 0, -30, 160], [116.41, 39.92, 30, 0, -40, 130]],
    { speed: 36, lockAll: true }
);
```

### 环境控制（天气/时间） 🌤️

```javascript
engine.UDS.changeWeather('clearSkies');
engine.UDS.changeTime(14, 30);
```

### 获取点击坐标 📍

```javascript
engine.camera.addEventListener('clickLocation', event => {
    const loc = event?.content?.Location;
    if (loc) {
        console.log(loc.longitude, loc.latitude, loc.altitude);
    }
});
```


---

## AssetLayer 使用要求（重点） 📌

`AssetLayer` 依赖模型信息初始化，必须遵循顺序：

1. 在 `videoInitialised` 中调用一次 `engine.setupModelInfo(...)`
2. 再创建 `new Engine.AssetLayer(...)`
3. 最后 `engine.addToScene(assetLayer)`

如果跳过第 1 步，`AssetLayer` 将无法正常工作。

---

## 数据格式约定 📐

- 坐标系：WGS84 经纬度
- 位置结构：`{ x: 经度, y: 纬度, z: 高度(米) }`
- 旋转结构：`{ roll, pitch, yaw }`
- 颜色结构：`{ r, g, b }`，范围 `0~1`
- 可视化对象数据：GeoJSON

---

## 连接与性能诊断建议 📊

- 使用 `videoInitialised` 作为“可操作场景”的唯一就绪信号。
- 连接前先检查调度容量，避免无效重试。
- 通过 `engine.onWebRtcConnectionStats()` 监控 RTT、丢包、码率等指标。
- 对于大量对象场景，及时调用 `engine.destoryObject()` 回收资源。

---

## 版本与发布 🏷️

- npm 包名：`mapv-cloudrenderengine`
- 当前版本可在 `package.open.json` 中查看

---

## 文档与资源 📚

- API 文档：[https://mapv.baidu.com/mapvunreal/docs/AssetLayer.html](https://mapv.baidu.com/mapvunreal/docs/AssetLayer.html)
- 调度服务接入说明：[https://mapv.baidu.com/mapvunreal/docs/schServer.html](https://mapv.baidu.com/mapvunreal/docs/schServer.html)
- 单机像素流说明：[https://mapv.baidu.com/mapvunreal/docs/singlePixel.html](https://mapv.baidu.com/mapvunreal/docs/singlePixel.html)

---

## Skill 介绍 🤖

为方便开发者和 AI 助手快速接入，本 SDK 提供配套 Skill 知识库，覆盖以下能力：

- 引擎初始化与调度服务接入
- 点线面与行业对象可视化代码生成
- 相机控制、事件处理、天气时间控制
- AssetLayer 使用规范与常见问题排障

Skill 仓库地址：
[https://github.com/baidu-maps/unreal-sdk-skills](https://github.com/baidu-maps/unreal-sdk-skills)

---


## 常见问题 ❓

**Q1：页面无画面输出？**  
优先检查：`#player` 容器是否存在、调度服务配置是否正确、项目容量是否充足。

**Q2：对象已创建但不显示？**  
检查数据坐标、GeoJSON 结构、`visible` 状态、相机位置和高度。

**Q3：点击无法获取坐标？**  
使用 `engine.camera.addEventListener('clickLocation', ...)` 并确认画面已 `videoInitialised`。

**Q4：连接卡顿或延迟高？**  
查看 WebRTC 统计指标（RTT/丢包/码率），并优先排查网络与服务端资源瓶颈。

---


## 如何获取更多支持 📮

- 技术支持：联系百度地图开放平台技术支持团队
- 商务合作：[百度地图开放平台](https://jiaotong.baidu.com/contactus/)