MapLibreParticleLab/docs/报告/STEP-055_Android真实WeatherV2风场综合可视化_Codex完成报告_v4.md

STEP-055 Android 真实 WeatherV2 风场综合可视化 Codex 完成报告 v4

Starting HEAD / remote：97aa019f6ff07d1b91e17c46ad0e6e6c0cd339d5，origin/particle/main。

根因与修复

当前代码确认：State RGBA Float 已工作，但 State 在越界/无效时回固定 seed，导致重复集中；B 是未充分使用的 age。particle vertex 又按 position ± normalizedVelocity * streakLength 生成固定 world 短线；Trail A/B 是 viewport-sized UByte texture，却由全球 world 坐标写入/按地图 world quad 采样。上述组合解释了密度衰减、边缘集中、缩放时粗短棍与闪烁。

State A/B 仍为 Float，Trail A/B 仍为 UnsignedByte。正式 State pass 现在以 B 保存 simulation age，以 A 保存“本帧 segment 是否可连接”标记；越界、invalid、near-zero velocity 或 age≥3600 simulation seconds 时，使用 particle UV 与旧位置的 GPU hash 在 Field bounds 内至多三次采样有效位置。重生帧 A=0，因此 draw 丢弃 oldPosition → newPosition；下一次正常 advection 后才画 segment。

Particle draw 现绑定 StateRead 与 StateWrite，直接画 previousPosition → currentPosition，并用当前 MapLibre matrixForTile() 投影到 Trail framebuffer。streakLength 保留公开 UI/API 兼容，但在正式真实天气路径不再主导 segment 长度。正式 Composite 改为单次 fullscreen view-space Trail 合成；相机 transform 改变时仅重建 Trail，记录 CAMERA_RESET，保留 State、Field、Timeline 与 Runtime Window。

旧 fade 是每 render frame trail *= trailFade。新公式是 fadeFactor = pow(trailFade, wallDeltaSeconds * 60)：UI 值保持“60 FPS 单帧保留率”，而 30/60/120 FPS 都按相同 wall-time 指数衰减。Timeline Pause 不影响该 wall-time fade。

visual clock 从 6000 降为 1200 simulation seconds/real second；典型 60 FPS 为 20 simulation seconds/frame。5 m/s 约 100 m/frame，在 z9 约 0.65 px；30 m/s 约 3.9 px，降低高风速跨帧跳跃与频繁越界风险，未改变 canonical m/s。

架构影响

未修改 canonical Field、WeatherV2 assets、Host submission、Timeline、Runtime Field Window 或 WeatherColorLayer。正常 forecast boundary 的 reuse、NEW_T1-only upload、simulationRebuild=false、trailCleared=false 保持；camera Trail reset 与 forecast boundary 的 Trail 语义明确分离。

修改文件：

• src/mbgl/renderer/layers/render_particle_validation_layer.cpp
• shaders/particle_gpu_validation.vertex.glsl
• shaders/particle_gpu_validation.fragment.glsl
• include/mbgl/shaders/gl/particle_gpu_validation.hpp（generator 输出）

验证

• node shaders/generate_shader_code.mjs：PASS。
• Linux OpenGL CMake 精确编译 render_particle_validation_layer.cpp：PASS。
• 既有非 Jest style_layer.test.cpp 精确编译：PASS。
• git diff --check：PASS。
• Android Gradle/APK/ADB/设备：未执行。
• Jest：未执行。

Git 与状态

功能提交：4c84a791229aa9f11808460c5dbfcf96327fb780（fix: stabilize particle lifecycle and view-space trails），已成功 push 至 origin/particle/main。本报告将以独立文档提交补充；用户已有未跟踪文件未修改、未 stage。

最终状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION。