mapv-cloudrenderengine 2.7.9 → 2.8.0

package/README.md

@@ -1,133 +1,282 @@
-# CloudRenderEngine
+# CloudRenderEngine 🌐
 
-CloudRenderEngine 是由百度地图开放平台FE团队推出的基于一个基于Unreal Engine 5 引擎封装的JavaScript API三维孪生SDK，支持前端开发人员快速完成实时三维数字孪生系统的开发，构建智慧城市、交通、文旅、园区、元宇宙、BIM等场景业务应用。
+CloudRenderEngine 是百度地图开放平台推出的 UE5 像素流三维数字孪生前端 SDK。  
+它通过 WebRTC 将 Unreal Engine 5 场景实时推流到浏览器，并提供统一 JavaScript API 完成场景渲染、交互控制、对象管理和行业可视化能力接入。
 
-开发者使用 CloudRenderEngine 提供的丰富 API 可以完成全球级别的球面和平面三维场景实时高性能渲染、三维场景交互、移动端高性能渲染和交互、各类点线面动态数据可视化展示、巡航、模型单体化应用、路侧资产数据挂接、地图路径规划、实时信号灯、路名、POI，全球实时路况等功能。CloudRenderEngine 降低了 UE 研发的门槛，提升数字孪生场景构建的效率，是一款具备强地图能力、大规模场景渲染、效果高保真、强业务支撑的数字孪生引擎 SDK。
+适用场景包括智慧城市、智慧交通、园区管理、文旅展陈、BIM 可视化、实时监控和数字底座应用。
 
 ---
 
-## 📚 API 文档
+## 产品能力 ✨
 
-[点击访问 API 文档](https://mapv.baidu.com/mapvunreal/docs/AssetLayer.html)
-
-## 🤖 SKill
-
-[点击访问SKill](https://github.com/baidu-maps/unreal-sdk-skills)
+- **云渲染交互**：浏览器低门槛接入 UE5 高保真场景，支持鼠标/触控/键盘交互。
+- **地图级可视化**：支持点、线、面、热力、雷达、粒子、轨迹、标签等对象体系。
+- **行业对象能力**：支持交通、资产、路况、监控、信息牌等业务对象挂接。
+- **相机与动画系统**：支持飞行、巡航、关键帧导航、场景切换。
+- **环境控制能力**：支持天气、时间、光照等全局场景调度。
+- **WebRTC 监控诊断**：可监控连接质量、码率、丢包与延迟指标。
 
 ---
 
-## 🚀 开始使用
+## 安装与引入 📦
 
-### 1️⃣ 接入 MapV CloudRenderEngine
+包名：`mapv-cloudrenderengine`
 
-#### 通过 npm 引入
 ```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' }} />;
+}
+```
+
 ---
 
-### 2️⃣ Hello World 示例
+## 快速开始 🧭
+
+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)
+);
 
-CloudRenderEngine 支持两种引擎连接模式：
-1. **单机像素流模式**
-2. **调度服务模式**
+engine.addEventListener('videoInitialised', () => {
+    console.log('画面就绪，可以安全调用场景 API');
+});
 
-#### 单机像素流模式
+engine.addEventListener('signalingServerError', () => {
+    console.error('信令服务连接异常');
+});
+```
+
+### 2) 单机像素流模式 🖥️
 
 ```javascript
-axios.get('http://10.18.165.2:8889/streamer?project=' + name);  
+import * as Engine from 'mapv-cloudrenderengine';
+
 const engine = new Engine.CloudRenderEngine({
-    wsUrl: wsUrl, // 重要参数
-    isShowTestUI: false,
+    wsUrl: 'ws://your-pixel-streaming-signaling',
     connectOnLoad: true,
     shouldShowPlayOverlay: false,
     matchViewportResolution: true,
 });
 
-// 渲染场景。 此时可以开启一个加载动画
 engine.load();
+engine.addEventListener('videoInitialised', () => {
+    console.log('画面就绪');
+});
+```
 
-const handleEngineLoaded = () => {
-    // 执行这个事件后代表资源加载完
-    // 加载完成才可以使用 engine 的一系列方法
-    // 此时可以关闭加载动画
-};
+---
+
+## 常用 API 模式 🛠️
+
+### 场景对象增删 🧱
 
-const disconnected = () => {
-    // 服务连接异常时会回调此方法
-};
+```javascript
+const line = new Engine.Line({ color: { r: 0, g: 1, b: 0 }, width: 5 });
+line.setData(geojsonData);
+engine.addToScene(line);
 
-engine.addEventListener('videoInitialised', handleEngineLoaded);
-engine.addEventListener('signalingServerError', disconnected);
+// 资源释放
+engine.destoryObject(line);
 ```
 
-[查看详细文档](https://mapv.baidu.com/mapvunreal/docs/singlePixel.html)
+### 相机飞行与巡航 🎥
 
----
+```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
-import { CloudRenderEngine } from '@baidu/cloudrenderengine';
-
-// 配置调度服务 host 必须
-CloudRenderEngine.DispatchServer.host = 'http://10.18.165.2:8889';
-// 设置要调度的集群 tag 可选
-CloudRenderEngine.DispatchServer.tag = 'online';
-
-// 设置用户名和密码 可选，默认都是 admin
-Engine.CloudRenderEngine.DispatchServer.username = 'maptest';
-Engine.CloudRenderEngine.DispatchServer.password = 'maptest';
-
-CloudRenderEngine.DispatchServer.GetAllCapacity()
-    .then(capacity => {
-        if (capacity > 0) {
-            // 可以连接了  
-        }
-    });
-
-const engine = new CloudRenderEngine({
-    isShowTestUI: false,
-    connectOnLoad: true,
-    shouldShowPlayOverlay: false,
-    // consul 里配置的英文项目名称
-    projectName: 'beijing',
+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);
+    }
 });
+```
 
-const onSuccessed = message => {
-    // 调度成功
-};
 
-const onLoadError = error => {
-    // 调度失败，此处会给出具体原因，比如权限不足、可用调度容量不足、用户名或者密码错误、已达到该用户的最大连接数等。
-};
+---
 
-// 渲染场景。调用 GetAllCapacity 检查 capacity 大于 0 后才可以
-engine.load(onSuccessed, onLoadError);
+## AssetLayer 使用要求（重点） 📌
 
-const handleEngineLoaded = () => {
-    // 执行这个事件后代表资源加载完
-    // 加载完成才可以使用 engine 的一系列方法
-};
+`AssetLayer` 依赖模型信息初始化，必须遵循顺序：
 
-const disconnected = () => {
-    // 服务连接异常时会回调此方法
-};
+1. 在 `videoInitialised` 中调用一次 `engine.setupModelInfo(...)`
+2. 再创建 `new Engine.AssetLayer(...)`
+3. 最后 `engine.addToScene(assetLayer)`
 
-engine.addEventListener('videoInitialised', handleEngineLoaded);
-engine.addEventListener('signalingServerError', disconnected);
-```
+如果跳过第 1 步，`AssetLayer` 将无法正常工作。
+
+---
+
+## 数据格式约定 📐
+
+- 坐标系：WGS84 经纬度
+- 位置结构：`{ x: 经度, y: 纬度, z: 高度(米) }`
+- 旋转结构：`{ roll, pitch, yaw }`
+- 颜色结构：`{ r, g, b }`，范围 `0~1`
+- 可视化对象数据：GeoJSON
+
+---
 
-[查看详细文档](https://mapv.baidu.com/mapvunreal/docs/schServer.html)
+## 连接与性能诊断建议 📊
+
+- 使用 `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)
 
 ---
 
-## 🛠️ 常见问题
 
-### 如何获取更多支持？
-- 访问 [官方文档](https://mapv.baidu.com/mapvunreal/docs/AssetLayer.html)
-- 联系百度地图开放平台技术支持团队
+## 常见问题 ❓
+
+**Q1：页面无画面输出？**  
+优先检查：`#player` 容器是否存在、调度服务配置是否正确、项目容量是否充足。
+
+**Q2：对象已创建但不显示？**  
+检查数据坐标、GeoJSON 结构、`visible` 状态、相机位置和高度。
+
+**Q3：点击无法获取坐标？**  
+使用 `engine.camera.addEventListener('clickLocation', ...)` 并确认画面已 `videoInitialised`。
+
+**Q4：连接卡顿或延迟高？**  
+查看 WebRTC 统计指标（RTT/丢包/码率），并优先排查网络与服务端资源瓶颈。
 
 ---
 
+
+## 如何获取更多支持 📮
+
+- 技术支持：联系百度地图开放平台技术支持团队
+- 商务合作：[百度地图开放平台](https://jiaotong.baidu.com/contactus/)
+