mapv-cloudrenderengine

v2.8.4

Published

3 days ago

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

0High
0Medium
0Low

leeran

unreal cloud render

CloudRenderEngine 🌐

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

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

产品能力 ✨

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

安装与引入 📦

包名：mapv-cloudrenderengine

npm install mapv-cloudrenderengine

import * as Engine from 'mapv-cloudrenderengine';

必备前提 ✅

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

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

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

最小可运行示例（React） 🚀

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 支持两种接入模式：

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

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

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) 单机像素流模式 🖥️

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 模式 🛠️

场景对象增删 🧱

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

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

相机飞行与巡航 🎥

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 }
);

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

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

获取点击坐标 📍

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

AssetLayer 使用要求（重点） 📌

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

在 videoInitialised 中调用一次 engine.setupModelInfo(...)
再创建 new Engine.AssetLayer(...)
最后 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/schServer.html
单机像素流说明：https://mapv.baidu.com/mapvunreal/docs/singlePixel.html

Skill 介绍 🤖

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

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

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

常见问题 ❓

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

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

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

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

如何获取更多支持 📮

技术支持：联系百度地图开放平台技术支持团队
商务合作：百度地图开放平台