# 智能星球 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 | 其他可交互物件（基类已就绪） | 待定义 |