fix: keep particle density stable across zoom
Some checks failed
validate-scripts / validate-scripts (push) Has been cancelled

This commit is contained in:
OpenAI Codex
2026-09-05 12:23:15 +08:00
parent d9a9c8ed57
commit f8e715d080
8 changed files with 178 additions and 6 deletions

View File

@@ -0,0 +1,28 @@
# STEP-055 Android 真实 WeatherV2 风场综合可视化 v7
状态:**IMPLEMENTED / WAITING_ANDROID_VALIDATION**
Starting HEAD:`d9a9c8ed57605abca86893ba7fb3b5265db3c0dc`
## Zoom 下 Viewport 粒子密度调整
- `configured particleCount` 不随 zoom 改变,仍由既有用户设置控制;本次没有按 zoom 重建 State slot,也没有新增均匀网格铺点。
- C++ 使用当前 viewport 四角的 unwrapped Web Mercator AABB,水平和垂直各扩展 15%,再与 canonical Field bounds 取交集,作为稳定相机时的 `respawnBounds`。
- shader 保留 `u_field_bounds` 作为唯一 Field 采样/UV 映射范围;新增独立 `u_respawn_bounds` 和 `viewportDensityActive`(`u_field_scale.z`),防止把可视范围误作数据有效范围。
- camera moving 期间 `viewportDensityActive=false`,普通 invalid/age 生命周期仍在 full Field 复生,State 不 reset、Field 不重提、Timeline 不重置。稳定至少 150ms 后才启用 viewport domain。
- stable 后,位于 expanded viewport 外的 slot 成为额外 respawn 条件;新出生 slot `age=0`、alpha=0,因此不会产生跨屏 segment。viewport 内的正常粒子不被统一重置。
- 若四角 AABB 无效、交集为空或 extent 过小,安全回退 full Field bounds;日志为 `ParticleDensity mode=FIELD_FALLBACK fallback=true`,不会产生 NaN/inverted bounds。
## 保持的边界
State A/B=Float、Trail A/B=UnsignedByte、previousPosition→currentPosition、zoom-aware visual speed、wall-time lifecycle、time-based fade 与 camera Trail invalidate/stable resume 保持。canonical U/V=m/s、WeatherV2 assets、Host Submission、Timeline、Runtime Field 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:未执行。
下一步由用户按人工验收 v7 检查 z2–3/z5/z8–9 密度、相机稳定后的补充行为和 Timeline boundary 回归。

View File

@@ -0,0 +1,22 @@
# STEP-055 Android 真实 WeatherV2 风场综合可视化人工验收指令 v7
环境:Windows 11;设备 `192.168.1.146`。Android 构建、安装与设备操作由用户手工执行;Codex 未执行这些步骤。
```powershell
cd platform\android
$env:RENDERER='opengl'; $env:BUILDTYPE='Debug'; make apackage --console=plain
adb -s 192.168.1.146 install -r <APK路径>
adb -s 192.168.1.146 logcat -c
adb -s 192.168.1.146 logcat | Select-String 'Particle(Density|Motion|Lifecycle|Trail|Timeline|GPU|StateTarget)'
```
1. `REAL WEATHER` 自动 fit(z≈2–3):粒子持续可见、运动且自然分布;不得回到固定 world-length 粗短棍,也不应呈规则均匀点阵。
2. z≈5:停止相机操作至少 150ms。确认 `ParticleTrail: event=CAMERA_STABLE_RESUME` 后出现一条 `ParticleDensity mode=VIEWPORT_RESPAWN cameraStable=true margin=0.15`;粒子密度应比 v8 明显改善。
3. z≈8–9:不提高 `particleCount` 仍有足够可见粒子;不得有整批 reseed、大面积闪烁或高频越界 respawn。`ParticleDensity` 的 `respawnBounds` 必须位于 `fieldBounds` 内。
4. 连续 pinch zoom/pan/rotate:交互期间 State 继续,`ParticleTrail` 只一次 `CAMERA_INVALIDATE`,不反复重建 texture;稳定后 resume 并启用 viewport respawn。不得出现 `SIMULATION_RESET`、Field resubmit 或 `PARTICLE_COUNT_CHANGE`。
5. Timeline Pause:forecast cursor/mix 冻结,但 Particle simulation 和 wall-time lifecycle 继续;生命周期仍为 12 real seconds、hash jitter 9–15 seconds。
6. `TIME → PLAY` 至 T3:继续确认 `OLD_T1 → NEW_T0` reuse、only NEW_T1 upload、`simulationRebuild=false`、`trailCleared=false`。正常 forecast boundary 不得因 density 逻辑清 Trail。
若 `ParticleDensity` 显示 `FIELD_FALLBACK`,保留完整日志和相机状态;这是空/无效/过小交集的 fail-safe,不得通过提高 particleCount 或改回固定 streak 绕过。
所有 ADB 命令必须显式使用 `adb -s 192.168.1.146 ...`。