# UE5 3D 大屏客户端开发计划

## 项目概述

基于智能星球计划架构，开发 UE5 3D 可视化大屏客户端，实现全球态势感知数据的沉浸式展示。

## 技术选型

| 组件 | 版本 | 用途 |
|------|------|------|
| Unreal Engine | 5.3+ | 3D 渲染引擎 |
| Cesium for Unreal | 1.5+ | 地理可视化 |
| Niagara | - | 粒子系统 |
| WebSocket API | - | 实时数据推送 |

## 项目结构

```
unreal/
├── Content/
│   ├── Levels/
│   │   ├── Main.umap          # 主场景
│   │   └── Components/        # 组件关卡
│   ├── Blueprints/
│   │   ├── BP_GlobeController     # 地球控制器
│   │   ├── BP_DataVisualizer      # 数据可视化基类
│   │   ├── BP_Supercomputer        # TOP500 超算标记
│   │   ├── BP_GPUCluster          # GPU 集群标记
│   │   ├── BP_IXPNode            # IXP 节点标记
│   │   ├── BP_SubmarineCable     # 海缆连接线
│   │   ├── BP_DataFlow           # 数据流向粒子
│   │   ├── BP_AlarmIndicator      # 告警指示器
│   │   └── BP_CameraController    # 相机控制器
│   ├── Materials/
│   │   ├── M_Globe            # 地球材质
│   │   ├── M_DataPoint        # 数据点材质
│   │   ├── M_Cable             # 海缆材质
│   │   └── M_DataFlow          # 数据流材质
│   ├── Widgets/
│   │   ├── W_MainHUD          # 主 HUD
│   │   ├── W_DataInfo         # 数据信息面板
│   │   └── W_AlarmPanel       # 告警面板
│   └── UI/
│       └── UMG/
├── Source/
│   ├── PlanetAPI/             # 后端 API 客户端
│   │   ├── PlanetAPIClient    # WebSocket 连接
│   │   ├── DataModels         # 数据模型
│   │   └── HttpClient         # HTTP 客户端
│   ├── CesiumIntegration/      # Cesium 集成
│   │   ├── GlobeManager       # 地球管理
│   │   └── GeoUtils           # 地理坐标工具
│   └── Visualization/          # 可视化组件
│       ├── PointRenderer       # 点渲染
│       ├── LineRenderer        # 线渲染
│       └── ParticleSystem      # 粒子系统
└── Planet.unproject
```

## 功能模块

### 1. 3D 地球渲染

CesiumIntegration 组件:
- 集成 Cesium ion 地图服务
- 支持多分辨率地球纹理
- 地理坐标 转 UE 坐标转换
- 光照和大气效果

### 2. 算力点可视化

数据点类型:

| 数据源 | 点类型 | 颜色 | 标识 |
|--------|--------|------|------|
| TOP500 | 超算 | 红色 | HPLinpack 性能 |
| Epoch AI | GPU集群 | 橙色 | GPU数量 |
| HuggingFace | 模型部署 | 蓝色 | 模型大小 |

### 3. 海缆可视化

CableVisualization 组件:
- 海缆路径渲染 (Spline Mesh)
- 带宽/容量可视化 (颜色编码)
- 实时流量状态

### 4. 数据流向粒子

DataFlowNiagara 系统:
- 源 → 目的地的粒子流动
- 带宽决定粒子密度/速度
- 支持动画和颜色渐变

### 5. 告警系统

AlarmIndicators:
- 异常数据红色高亮
- 闪烁效果
- 点击显示详情

### 6. WebSocket 实时更新

PlanetAPIClient:
- 连接 ws://backend:8000/ws
- 自动重连机制
- 数据更新回调

### 7. 相机控制

CameraController:
- 自动巡航模式
- 聚焦特定区域
- 平滑过渡动画

## 数据模型

```cpp
// 地理位置
struct FGeographicPoint
{
    double Latitude;   // 纬度 (-90 to 90)
    double Longitude;  // 经度 (-180 to 180)
    double Altitude;  // 高度 (米)
};

// 算力点数据
struct FComputePointData
{
    FString Id;
    FString Name;
    FString Source;           // top500, epoch_ai
    FGeographicPoint Location;
    float Performance;        // PFLOPS
    int32 CoreCount;
    int32 GpuCount;
    FString Country;
};
```

## API 对接

### WebSocket 消息格式

```json
{
  "type": "update",
  "data": {
    "source": "top500",
    "action": "add/update/remove",
    "payload": {
      "id": "top500_1",
      "name": "Frontier",
      "location": {
        "latitude": 33.7756,
        "longitude": -84.3962,
        "altitude": 0
      },
      "performance": 1682.65,
      "cores": 8730112
    }
  }
}
```

### HTTP API 端点

| 端点 | 用途 |
|------|------|
| GET /api/v1/collected?source=top500 | 获取 TOP500 数据 |
| GET /api/v1/collected?source=telegeography_cables | 获取海缆数据 |
| WS /ws/updates | 实时数据推送 |

## 开发阶段

### Phase 1: 基础框架 (1-2 周)

- [ ] 创建 UE5 项目
- [ ] 安装 Cesium for Unreal 插件
- [ ] 实现基础地球渲染
- [ ] 创建 WebSocket 客户端框架

### Phase 2: 数据点可视化 (2-3 周)

- [ ] 实现 TOP500 超算标记
- [ ] 实现 GPU 集群标记
- [ ] 添加交互功能
- [ ] 实现信息面板

### Phase 3: 海缆可视化 (1-2 周)

- [ ] 实现海缆路径渲染
- [ ] 添加带宽可视化
- [ ] 实现数据流向粒子

### Phase 4: 实时更新 (1-2 周)

- [ ] 完成 WebSocket 集成
- [ ] 实现数据自动更新
- [ ] 添加告警系统

### Phase 5: UI 和优化 (1 周)

- [ ] 添加 HUD 界面
- [ ] 实现相机控制
- [ ] 性能优化
- [ ] 测试和修复

## 资源需求

### 必要资源

1. **Cesium ion 账户**
   - 免费注册: https://cesium.com/ion/
   - 用于访问全球 3D 地形和影像

2. **UE5 安装**
   - 从 Epic Games Launcher 安装
   - 建议版本: 5.3 或 5.4

### 可选资源

- 区域高程数据
- 夜间灯光纹理

## 验收标准

### 基础功能

- [ ] 地球正常渲染，无明显卡顿
- [ ] TOP500 数据点正确显示位置
- [ ] 超算信息面板可点击查看
- [ ] WebSocket 连接正常

### 高级功能

- [ ] 海缆路径可视化
- [ ] 数据流向粒子效果
- [ ] 告警指示
- [ ] 自动巡航模式

### 性能要求

- [ ] 60 FPS 稳定运行 (4K 分辨率)
- [ ] 1000+ 数据点无明显性能下降
- [ ] WebSocket 消息延迟 < 1 秒