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

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

Starting HEAD / remote：d9a9c8ed57605abca86893ba7fb3b5265db3c0dc，origin/particle/main。

本任务只调整 zoom 后的 viewport particle density；未修改功能范围外的数据链或 UI。

实现

RenderRasterParticleLayer 以当前 TransformState 的 viewport 四角取得 unwrapped Web Mercator AABB，按宽高各扩展 15%，然后与 canonical fieldBounds 求交。交集有效且 camera stable（沿用 150ms Trail debounce）时，该交集作为独立 respawnBounds。交集为空、无效或 extent 过小时，回退 full field bounds。

新增 UBO respawnBounds，并以 fieldScale.z 传递 viewportDensityActive。Field sampling、UV grid 映射和 U/V decode 始终使用 fieldBounds；viewport bounds 不参与 Field 采样。State shader 在 existing invalid/out-of-field/age-expired 条件外，仅于 viewportDensityActive 时将 expanded viewport 外 slot 标记为 respawn candidate。复生仍复用既有 hash、三次有效 Field sample、age=0 和首帧 alpha=0；没有 CPU readback、全体 reseed、均匀网格或 zoom-based particleCount。

camera moving 时，viewportDensityActive=false 且 respawn domain 固定为 full field，避免交互期间强制 viewport respawn。相机稳定后启用 viewport domain；ParticleDensity 低频日志输出 zoom、mode、margin、respawnBounds、fieldBounds、fallback 与 configuredSlots。resize 与普通 camera transform 的 Trail 语义保持 v8：只有 resize 重分配 Trail target。

修改文件

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

未修改 State A/B Float、Trail A/B UnsignedByte、previous→current segment、zoom-aware speed、wall-time lifecycle、canonical Field、WeatherV2 assets、Host Submission、Timeline、Runtime Window、WeatherColorLayer 或 REAL WEATHER UI。

验证

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

功能提交：f8e715d080d69db779fe37ea7a5aa37c0f7c42c4（fix: keep particle density stable across zoom），已成功 push 至 origin/particle/main。本报告随后以独立文档提交记录，不改变功能实现。

最终状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION。