1e6f4b338b
Backend: - Add /api/v1/ue/* endpoints (compute-points, cables, landing-points, satellites, status) returning flat JSON optimised for UE5 C++ parsing UE5 client (ue_client/): - PlanetDataManager: HTTP fetch + local mock JSON loader, spawns ComputePointActors - ComputePointActor / InteractiveObjectBase: hover/select state, material switching - GlobeInteractionComponent: drag-to-rotate via CesiumGeoreference origin shift, inertia, zoom - StereoRenderingManager: runtime SbS/TbB stereo toggle, IPD control (format TBD) - MotionCaptureInterface: protocol-agnostic gesture/rotate/zoom delegate interface (impl TBD) - PlanetPlayerController: unified mouse + motion-capture input routing - PlanetGameMode, Build.cs, Config, mock data Docs: - ue5_mvp_fused_plan.md updated to v3.0 for LED display context - ue_client_setup_guide.md: step-by-step editor setup guide - ue_todo.md: pending items blocked on vendor answers (stereo format + mocap protocol) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
153 lines
5.5 KiB
Markdown
153 lines
5.5 KiB
Markdown
# 智能星球 UE5 客户端实施方案（LED 大屏版）
|
||
|
||
> 版本：v3.0
|
||
> 日期：2026-04-14
|
||
> 背景更新：目标从"普通桌面地球"升级为"5m 被动偏振 3D LED 大屏 + 动捕交互演示系统"
|
||
|
||
---
|
||
|
||
## 一、真实场景描述
|
||
|
||
```
|
||
领导进入展示间
|
||
↓
|
||
5.12m × 2.88m 被动偏振 3D LED 大屏开机
|
||
↓
|
||
UE5 实时渲染的 3D 地球从屏幕"飞出"
|
||
（配合被动 3D 眼镜，数据点有真实景深）
|
||
↓
|
||
演示者做手势（无穿戴动捕摄像头捕捉）
|
||
→ 地球旋转、缩放
|
||
→ 指向数据点 → 高亮
|
||
→ 确认手势 → 信息卡弹出（漂浮在屏幕前方）
|
||
↓
|
||
鼠标/触控作为备用输入
|
||
```
|
||
|
||
---
|
||
|
||
## 二、系统架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ RTX 5090 渲染工作站 │
|
||
│ │
|
||
│ Planet 后端（FastAPI） │
|
||
│ ↕ /api/v1/ue/* │
|
||
│ UE5 主程序（本项目） │
|
||
│ ├── Cesium 地球 │
|
||
│ ├── 超算数据点 │
|
||
│ ├── 其他可交互物件 │
|
||
│ └── 立体渲染输出 (Side-by-Side / Top-Bottom) │
|
||
│ │
|
||
└─────────────┬───────────────────────────────────┘
|
||
│ HDMI/DP 视频信号
|
||
▼
|
||
视频处理器（随屏配套）
|
||
│ LED 驱动信号（行偏振）
|
||
▼
|
||
5.12m × 2.88m 被动偏振 3D LED 大屏
|
||
↑
|
||
观众戴无源 3D 眼镜（≤18g，无需充电）
|
||
|
||
动捕摄像头（×2）
|
||
↓ 手势识别（无穿戴）
|
||
动捕中间件 ─→ UE5（Live Link / OSC，待确认）
|
||
```
|
||
|
||
---
|
||
|
||
## 三、一期交付目标（6 项）
|
||
|
||
1. ✅ 地球在 3D 大屏上正确显示，有景深效果
|
||
2. ✅ 超算数据点散布在地球上，可悬停高亮
|
||
3. ✅ 点击/手势确认 → 弹出数据点信息卡
|
||
4. ✅ 鼠标拖拽/手势 → 地球旋转（带惯性）
|
||
5. ✅ 滚轮/手势 → 缩放
|
||
6. ⏳ 立体渲染格式配置（等视频处理器格式答复）
|
||
7. ⏳ 动捕手势接入（等中间件协议答复）
|
||
|
||
---
|
||
|
||
## 四、已完成的代码
|
||
|
||
### 后端（`backend/app/api/v1/ue_data.py`）
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| `GET /api/v1/ue/status` | 健康检查 |
|
||
| `GET /api/v1/ue/compute-points` | 超算数据（平铺 JSON）|
|
||
| `GET /api/v1/ue/landing-points` | 海缆登陆点 |
|
||
| `GET /api/v1/ue/cables` | 海缆几何 |
|
||
| `GET /api/v1/ue/satellites` | 卫星 TLE |
|
||
|
||
### UE5 C++ 源码（`ue_client/Source/PlanetClient/`）
|
||
|
||
| 文件 | 功能 |
|
||
|------|------|
|
||
| `PlanetDataTypes.h` | 数据结构（FComputePoint 等）|
|
||
| `PlanetDataManager.h/.cpp` | HTTP 拉取 + 本地 mock 数据 + 生成 Actor |
|
||
| `ComputePointActor.h/.cpp` | 单个超算点 Actor，三态材质 |
|
||
| `InteractiveObjectBase.h/.cpp` | 所有可交互物件的基类 |
|
||
| `GlobeInteractionComponent.h/.cpp` | 地球旋转/缩放，带惯性 |
|
||
| `StereoRenderingManager.h/.cpp` | 立体渲染框架，运行时切换模式 |
|
||
| `MotionCaptureInterface.h` | 动捕接口定义，协议无关 |
|
||
| `PlanetPlayerController.h/.cpp` | 统一处理鼠标 + 动捕输入 |
|
||
| `PlanetGameMode.h/.cpp` | 场景入口，自动初始化管理器 |
|
||
| `PlanetClient.Build.cs` | 模块依赖（含 TODO 注释）|
|
||
|
||
### 数据和配置
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `Content/Data/mock_compute_points.json` | 10 个真实超算的 mock 数据 |
|
||
| `Config/DefaultGame.ini` | GameMode 配置 |
|
||
| `Config/DefaultEngine.ini` | 渲染设置 |
|
||
| `Config/DefaultInput.ini` | 键鼠输入绑定 |
|
||
|
||
---
|
||
|
||
## 五、你需要在编辑器里做的操作
|
||
|
||
> 完整步骤见 `docs/ue_client_setup_guide.md`
|
||
|
||
**最小操作清单（Phase A 本地演示）：**
|
||
|
||
1. 安装 UE5.3 + Cesium for Unreal 插件
|
||
2. 打开 `ue_client/PlanetClient.uproject`，等待编译
|
||
3. 创建空关卡 `EarthMap`，通过 Cesium 菜单添加地球
|
||
4. 拖入 CesiumDynamicPawn，设置 Auto Possess Player 0
|
||
5. World Settings → GameMode → PlanetGameMode
|
||
6. 创建 `BP_ComputePointActor`（父类 `AComputePointActor`），配置球体网格 + 三色材质
|
||
7. 创建 `BP_PlanetDataManager`，拖入场景，绑定 `ComputePointClass`
|
||
8. Play → 看到 10 个橙色球体，可悬停 + 点击
|
||
|
||
---
|
||
|
||
## 六、TODO 项（等供应商答复）
|
||
|
||
> 详细对照表见 `docs/ue_todo.md`
|
||
|
||
### TODO-1：立体渲染格式
|
||
- **等待**：视频处理器接受什么 3D 输入格式（SbS / TbB / 行交错）
|
||
- **代码位置**：`StereoRenderingManager.cpp`
|
||
- **工作量**：0.5 天
|
||
|
||
### TODO-2：动捕协议
|
||
- **等待**：中间件使用 Live Link / OSC / 私有 SDK
|
||
- **代码位置**：`MotionCaptureInterface.h`，`PlanetPlayerController.cpp`
|
||
- **工作量**：Live Link=2h，OSC=1天，私有SDK=1-3天
|
||
|
||
---
|
||
|
||
## 七、后续阶段规划
|
||
|
||
| 阶段 | 内容 | 状态 |
|
||
|------|------|------|
|
||
| Phase A | 本地 mock 数据，鼠标交互，单目 2D | ✅ 代码就绪 |
|
||
| Phase B | 接入真实后端 `/api/v1/ue/*` | ✅ 代码就绪 |
|
||
| Phase C | 立体 3D 输出 | ⏳ 等格式确认 |
|
||
| Phase D | 动捕手势交互 | ⏳ 等协议确认 |
|
||
| Phase E | 海缆 Spline 渲染 | 待开发 |
|
||
| Phase F | 其他可交互物件（基类已就绪） | 待定义 |
|