docs: add architecture refactor and webgl instancing plans

2026-03-20 13:53:36 +08:00
parent 4f922f13d1
commit 3e3090d72a
2 changed files with 458 additions and 0 deletions
--- a/.sisyphus/plans/webgl-instancing-satellites.md
+++ b/.sisyphus/plans/webgl-instancing-satellites.md
@@ -0,0 +1,293 @@
+# WebGL Instancing 卫星渲染优化计划
+
+## 背景
+
+当前 `satellites.js` 使用 `THREE.Points` 渲染卫星，受限于 WebGL 点渲染性能，只能显示 ~500-1000 颗卫星。
+需要迁移到真正的 WebGL Instancing 以支持 5000+ 卫星流畅渲染。
+
+## 技术选型
+
+| 方案 | 性能 | 改动量 | 维护性 | 推荐 |
+|------|------|--------|--------|------|
+| THREE.Points (现状) | ★★☆ | - | - | 基准 |
+| THREE.InstancedMesh | ★★★ | 中 | 高 | 不适合点 |
+| InstancedBufferGeometry + 自定义Shader | ★★★★ | 中高 | 中 | ✅ 推荐 |
+| 迁移到 TWGL.js / Raw WebGL | ★★★★★ | 高 | 低 | 未来UE |
+
+**推荐方案**: InstancedBufferGeometry + 自定义 Shader
+- 保持 Three.js 架构
+- 复用 satellite.js 数据层
+- 性能接近原生 WebGL
+
+---
+
+## Phase 1: 调研与原型
+
+### 1.1 分析现有架构
+
+**现状 (satellites.js)**:
+```javascript
+// 创建点云
+const pointsGeometry = new THREE.BufferGeometry();
+pointsGeometry.setAttribute('position', new THREE.BufferAttribute(positions, 3));
+pointsGeometry.setAttribute('color', new THREE.BufferAttribute(colors, 3));
+
+const pointsMaterial = new THREE.PointsMaterial({
+  size: 2,
+  vertexColors: true,
+  transparent: true,
+  opacity: 0.8,
+  sizeAttenuation: true
+});
+
+satellitePoints = new THREE.Points(pointsGeometry, pointsMaterial);
+```
+
+**问题**: 每个卫星作为一个顶点，GPU 需要处理 ~500 个 draw calls (取决于视锥体裁剪)
+
+### 1.2 Instanced Rendering 原理
+
+```javascript
+// 目标：单次 draw call 渲染所有卫星
+// 每个卫星属性:
+// - position (vec3): 位置
+// - color (vec3): 颜色
+// - size (float): 大小 (可选)
+// - selected (float): 是否选中 (0/1)
+
+// 使用 InstancedBufferGeometry
+const geometry = new THREE.InstancedBufferGeometry();
+geometry.index = originalGeometry.index;
+geometry.attributes.position = originalGeometry.attributes.position;
+geometry.attributes.uv = originalGeometry.attributes.uv;
+
+// 实例数据
+const instancePositions = new Float32Array(satelliteCount * 3);
+const instanceColors = new Float32Array(satelliteCount * 3);
+
+geometry.setAttribute('instancePosition', 
+  new THREE.InstancedBufferAttribute(instancePositions, 3));
+geometry.setAttribute('instanceColor', 
+  new THREE.InstancedBufferAttribute(instanceColors, 3));
+
+// 自定义 Shader
+const material = new THREE.ShaderMaterial({
+  vertexShader: `
+    attribute vec3 instancePosition;
+    attribute vec3 instanceColor;
+    varying vec3 vColor;
+    
+    void main() {
+      vColor = instanceColor;
+      vec3 transformed = position + instancePosition;
+      gl_Position = projectionMatrix * modelViewMatrix * vec4(transformed, 1.0);
+    }
+  `,
+  fragmentShader: `
+    varying vec3 vColor;
+    void main() {
+      gl_FragColor = vec4(vColor, 0.8);
+    }
+  `
+});
+```
+
+---
+
+## Phase 2: 实现
+
+### 2.1 创建 instanced-satellites.js
+
+```javascript
+// instanced-satellites.js - Instanced rendering for satellites
+
+import * as THREE from 'three';
+import { SATELLITE_CONFIG } from './constants.js';
+
+let instancedMesh = null;
+let satelliteData = [];
+let instancePositions = null;
+let instanceColors = null;
+let satelliteCount = 0;
+
+const SATELLITE_VERTEX_SHADER = `
+  attribute vec3 instancePosition;
+  attribute vec3 instanceColor;
+  attribute float instanceSize;
+  
+  varying vec3 vColor;
+  
+  void main() {
+    vColor = instanceColor;
+    vec3 transformed = position * instanceSize + instancePosition;
+    gl_Position = projectionMatrix * modelViewMatrix * vec4(transformed, 1.0);
+  }
+`;
+
+const SATELLITE_FRAGMENT_SHADER = `
+  varying vec3 vColor;
+  
+  void main() {
+    gl_FragColor = vec4(vColor, 0.9);
+  }
+`;
+
+export function createInstancedSatellites(scene, earthObj) {
+  // 基础球体几何 (每个卫星是一个小圆点)
+  const baseGeometry = new THREE.CircleGeometry(1, 8);
+  
+  // 创建 InstancedBufferGeometry
+  const geometry = new THREE.InstancedBufferGeometry();
+  geometry.index = baseGeometry.index;
+  geometry.attributes.position = baseGeometry.attributes.position;
+  geometry.attributes.uv = baseGeometry.attributes.uv;
+  
+  // 初始化实例数据数组 (稍后填充)
+  instancePositions = new Float32Array(MAX_SATELLITES * 3);
+  instanceColors = new Float32Array(MAX_SATELLITES * 3);
+  const instanceSizes = new Float32Array(MAX_SATELLITES);
+  
+  geometry.setAttribute('instancePosition', 
+    new THREE.InstancedBufferAttribute(instancePositions, 3));
+  geometry.setAttribute('instanceColor', 
+    new THREE.InstancedBufferAttribute(instanceColors, 3));
+  geometry.setAttribute('instanceSize', 
+    new THREE.InstancedBufferAttribute(instanceSizes, 1));
+  
+  const material = new THREE.ShaderMaterial({
+    vertexShader: SATELLITE_VERTEX_SHADER,
+    fragmentShader: SATELLITE_FRAGMENT_SHADER,
+    transparent: true,
+    side: THREE.DoubleSide
+  });
+  
+  instancedMesh = new THREE.Mesh(geometry, material);
+  instancedMesh.frustumCulled = false; // 我们自己处理裁剪
+  scene.add(instancedMesh);
+  
+  return instancedMesh;
+}
+
+export function updateInstancedSatellites(satellitePositions) {
+  // satellitePositions: Array of { position: Vector3, color: Color }
+  const count = Math.min(satellitePositions.length, MAX_SATELLITES);
+  
+  for (let i = 0; i < count; i++) {
+    const sat = satellitePositions[i];
+    instancePositions[i * 3] = sat.position.x;
+    instancePositions[i * 3 + 1] = sat.position.y;
+    instancePositions[i * 3 + 2] = sat.position.z;
+    
+    instanceColors[i * 3] = sat.color.r;
+    instanceColors[i * 3 + 1] = sat.color.g;
+    instanceColors[i * 3 + 2] = sat.color.b;
+  }
+  
+  instancedMesh.geometry.attributes.instancePosition.needsUpdate = true;
+  instancedMesh.geometry.attributes.instanceColor.needsUpdate = true;
+  instancedMesh.geometry.setDrawRange(0, count);
+}
+```
+
+### 2.2 修改现有 satellites.js
+
+保持数据层不变，添加新渲染模式：
+
+```javascript
+// 添加配置
+export const SATELLITE_CONFIG = {
+  USE_INSTANCING: true,  // 切换渲染模式
+  MAX_SATELLITES: 5000,
+  SATELLITE_SIZE: 0.5,
+  // ...
+};
+```
+
+### 2.3 性能优化点
+
+1. **GPU 实例化**: 单次 draw call 渲染所有卫星
+2. **批量更新**: 所有位置/颜色一次更新
+3. **视锥体裁剪**: 自定义裁剪逻辑，避免 CPU 端逐卫星检测
+4. **LOD (可选)**: 远处卫星简化显示
+
+---
+
+## Phase 3: 与现有系统集成
+
+### 3.1 悬停/选中处理
+
+当前通过 `selectSatellite()` 设置选中状态，Instanced 模式下需要：
+
+```javascript
+// 在 shader 中通过 instanceId 判断是否选中
+// 或者使用单独的 InstancedBufferAttribute 存储选中状态
+const instanceSelected = new Float32Array(MAX_SATELLITES);
+geometry.setAttribute('instanceSelected', 
+  new THREE.InstancedBufferAttribute(instanceSelected, 1));
+```
+
+### 3.2 轨迹线
+
+轨迹线仍然使用 `THREE.Line` 或 `THREE.LineSegments`，但可以类似地 Instanced 化：
+
+```javascript
+// Instanced LineSegments for trails
+const trailGeometry = new THREE.InstancedBufferGeometry();
+trailGeometry.setAttribute('position', trailPositions);
+trailGeometry.setAttribute('instanceStart', ...);
+trailGeometry.setAttribute('instanceEnd', ...);
+```
+
+---
+
+## Phase 4: 验证与调优
+
+### 4.1 性能测试
+
+| 卫星数量 | Points 模式 | Instanced 模式 |
+|----------|-------------|----------------|
+| 500 | ✅ 60fps | ✅ 60fps |
+| 2000 | ⚠️ 30fps | ✅ 60fps |
+| 5000 | ❌ 10fps | ✅ 45fps |
+| 10000 | ❌ 卡顿 | ⚠️ 30fps |
+
+### 4.2 可能遇到的问题
+
+1. **Shader 编译错误**: 需要调试 GLSL
+2. **实例数量限制**: GPU 最大实例数 (通常 65535)
+3. **大小不一**: 需要 per-instance size 属性
+4. **透明度排序**: Instanced 渲染透明度处理复杂
+
+---
+
+## 文件变更清单
+
+| 文件 | 变更 |
+|------|------|
+| `constants.js` | 新增 `SATELLITE_CONFIG` |
+| `satellites.js` | 添加 Instanced 模式支持 |
+| `instanced-satellites.js` | 新文件 - Instanced 渲染核心 |
+| `main.js` | 集成新渲染模块 |
+
+---
+
+## 时间估算
+
+| Phase | 工作量 | 难度 |
+|-------|--------|------|
+| Phase 1 | 1-2 天 | 低 |
+| Phase 2 | 2-3 天 | 中 |
+| Phase 3 | 1-2 天 | 中 |
+| Phase 4 | 1 天 | 低 |
+| **总计** | **5-8 天** | - |
+
+---
+
+## 替代方案考虑
+
+如果 Phase 2 实施困难，可以考虑：
+
+1. **使用 Three.js InstancedMesh**: 适合渲染小型 3D 模型替代点
+2. **使用 pointcloud2 格式**: 类似 LiDAR 点云渲染
+3. **Web Workers**: 将轨道计算移到 Worker 线程
+4. **迁移到 Cesium**: Cesium 原生支持 Instancing，且是 UE 迁移的中间步骤