# UE5 智能星球可视化项目 - 完整文档索引

## 项目概览

本项目为"智能星球计划"的 UE5 3D 可视化大屏客户端，用于展示全球态势感知数据。

## 目录结构

```
unreal/
├── Config/
│   └── PlanetConfig.ini              # Cesium ion 配置
├── Content/
│   ├── Blueprints/                   # 蓝图规格文档
│   │   ├── BP_GlobeController_Spec.md
│   │   ├── BP_DataPoint_Spec.md
│   │   ├── BP_Supercomputer_Spec.md
│   │   ├── BP_SubmarineCable_Spec.md
│   │   └── BP_DataFlow_Spec.md
│   ├── Materials/
│   │   └── Materials_Spec.md         # 材质规格文档
│   ├── Particles/
│   │   └── Niagara_Spec.md           # Niagara 粒子规格文档
│   ├── Levels/
│   │   └── Scene_Setup_Guide.md      # 场景搭建指南
│   ├── UI/
│   └── Widgets/
├── QUICK_START.md                    # 快速启动指南
└── setup.sh                         # 设置脚本
```

## 文档列表

### 1. 蓝图规格文档

| 文档 | 蓝图名称 | 用途 |
|------|----------|------|
| [BP_GlobeController_Spec.md](./Content/Blueprints/BP_GlobeController_Spec.md) | BP_GlobeController | 地球控制器，管理 Cesium |
| [BP_DataPoint_Spec.md](./Content/Blueprints/BP_DataPoint_Spec.md) | BP_DataPoint | 数据点基类 |
| [BP_Supercomputer_Spec.md](./Content/Blueprints/BP_Supercomputer_Spec.md) | BP_Supercomputer | TOP500 超算标记 |
| [BP_SubmarineCable_Spec.md](./Content/Blueprints/BP_SubmarineCable_Spec.md) | BP_SubmarineCable | 海底光缆可视化 |
| [BP_DataFlow_Spec.md](./Content/Blueprints/BP_DataFlow_Spec.md) | BP_DataFlow | 数据流向粒子 |

### 2. 材质和粒子

| 文档 | 内容 |
|------|------|
| [Materials_Spec.md](./Content/Materials/Materials_Spec.md) | 所有材质参数和网络结构 |
| [Niagara_Spec.md](./Content/Particles/Niagara_Spec.md) | 所有粒子系统配置 |

### 3. 场景搭建

| 文档 | 内容 |
|------|------|
| [Scene_Setup_Guide.md](./Content/Levels/Scene_Setup_Guide.md) | 完整场景搭建步骤 |
| [QUICK_START.md](./QUICK_START.md) | 快速启动指南 |

## 快速开始

### 1. 环境准备

```bash
# 确保后端服务运行
cd /home/ray/dev/linkong/planet
docker restart planet_backend_new
```

### 2. 启动 UE5

```
1. 打开 D:\games\Planet\unreal\Planet.uproject
2. 安装 Cesium for Unreal 插件
3. 配置 Cesium ion Token
4. 打开 Main.umap 场景
```

### 3. 创建蓝图

按照蓝图规格文档创建蓝图类:

```
Content/Blueprints/
├── BP_GlobeController.uasset      # 地球控制器
├── BP_DataPoint.uasset           # 数据点基类
├── BP_Supercomputer.uasset       # 超算标记 (继承自 BP_DataPoint)
├── BP_SubmarineCable.uasset      # 海缆可视化
└── BP_DataFlow.uasset           # 数据流向粒子
```

### 4. 配置材质

按照材质规格文档创建材质:

```
Content/Materials/
├── M_Globe.uasset                # 地球材质
├── M_DataPoint.uasset            # 数据点材质
├── M_Supercomputer.uasset        # 超算材质
├── M_Cable.uasset               # 海缆材质
├── M_DataFlow.uasset            # 数据流材质
└── M_Particle.uasset            # 粒子材质
```

### 5. 配置粒子系统

按照 Niagara 规格文档创建粒子:

```
Content/Particles/
├── NS_DataPoint_Glow.uasset     # 数据点光环
├── NS_Supercomputer_Glow.uasset # 超算光环
├── NS_DataFlow_Directional.uasset # 流向粒子
├── NS_Alarm_Flash.uasset       # 告警闪烁
└── NS_Ambient_Ambience.uasset  # 环境粒子
```

## 数据源支持

| 数据源 | 类型 | 蓝图 | 颜色 |
|--------|------|------|------|
| TOP500 | 超算 | BP_Supercomputer | 🔴 红色 |
| Epoch AI | GPU 集群 | BP_DataPoint | 🟠 橙色 |
| HuggingFace | 模型部署 | BP_DataPoint | 🔵 蓝色 |
| PeeringDB IXP | 交换中心 | BP_DataPoint | 🩵 青色 |
| PeeringDB Network | 网络 | BP_DataPoint | 🟣 紫色 |
| TeleGeography | 海缆 | BP_SubmarineCable | 🟡 黄色 |

## 后端 API

### HTTP API

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/v1/collected/summary` | GET | 获取数据统计 |
| `/api/v1/collected?source=top500` | GET | 获取 TOP500 数据 |
| `/api/v1/collected?source=telegeography_cables` | GET | 获取海缆数据 |
| `/api/v1/collected/export/json` | GET | 导出 JSON |
| `/api/v1/collected/export/csv` | GET | 导出 CSV |

### WebSocket

| 端点 | 说明 |
|------|------|
| `ws://localhost:8000/ws` | 实时数据推送 |

### 消息格式

**更新消息:**
```json
{
  "type": "update",
  "data": {
    "source": "top500",
    "action": "add/update/remove",
    "payload": {
      "id": "top500_1",
      "name": "Frontier",
      "location": {
        "latitude": 33.7756,
        "longitude": -84.3962
      },
      "performance": 1682.65
    }
  }
}
```

**告警消息:**
```json
{
  "type": "alarm",
  "data": {
    "severity": "high",
    "message": "数据采集失败",
    "source": "peeringdb_ixp"
  }
}
```

## 性能优化

### 渲染设置

```
├─ 分辨率: 4K (3840×2160)
├─ FPS 目标: 60
├─ 光照质量: 高
├─ 阴影质量: 高
└─ 后处理: 中
```

### LOD 设置

```
├─ 数据点:
│   ├─ LOD0: < 10000 cm
│   ├─ LOD1: < 50000 cm
│   └─ LOD2: > 50000 cm (禁用粒子)
│
├─ 海缆:
│   ├─ LOD0: < 10000 cm
│   ├─ LOD1: < 50000 cm (简化网格)
│   └─ LOD2: > 50000 cm (禁用)
│
└─ 粒子:
    ├─ Max Particles: 1000
    ├─ Cull Distance: 50000 cm
    └─ GPU Simulation: true
```

## 常见问题

### Q1: Cesium 地形不显示

检查:
1. Cesium ion Token 是否正确配置
2. 网络连接是否正常
3. Cesium 插件是否启用

### Q2: WebSocket 连接失败

检查:
1. 后端服务是否运行
2. CORS 配置是否正确
3. URL 格式是否正确

### Q3: 性能不足

优化:
1. 降低分辨率
2. 减少粒子数量
3. 禁用不必要的特效
4. 使用 LOD

## 下一步

1. **完善蓝图** - 按照规格文档创建所有蓝图
2. **添加 UI** - 创建 W_MainHUD、W_DataInfo 等界面
3. **测试数据** - 验证所有数据源正常显示
4. **优化性能** - 根据实际运行调整参数
5. **打包发布** - 生成可执行文件

## 参考资源

- [Cesium for Unreal 文档](https://cesium.com/docs/)
- [Unreal Engine 文档](https://docs.unrealengine.com/)
- [Niagara 粒子系统](https://docs.unrealengine.com/niagara-in-unreal-engine/)