48 lines
5.9 KiB
Markdown
48 lines
5.9 KiB
Markdown
# STEP-055 Android 真实 WeatherV2 风场综合可视化
|
||
|
||
状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION
|
||
|
||
Starting HEAD：`da71c8784ec20ed830f5d23880718647d666cf2f`
|
||
|
||
## 目标与数据边界
|
||
|
||
本阶段只复用 STEP-054 已生成的真实 WeatherV2 canonical 资产：`integration/particle-weatherv2/ecmwf-hres-wind-20260807/` 下的 2026080700、0706、0712、0718。数据保持原始 513×769 网格、`interleaved-uv/float32-le`、U=eastward、V=northward、单位 m/s 和原始 validTime；未重新生成、重采样、裁剪或伪造数据。
|
||
|
||
## 实现
|
||
|
||
- 新增独立 `weather-color` Style/Render Layer。其仅从现有 `RasterArraySource` 的 canonical T0/T1 snapshot 读字段，拥有独立的颜色 GPU texture/draw pass；不合并到 `RasterParticleLayer`。
|
||
- 颜色 shader 对同一位置的 T0/T1 先还原 canonical U/V、按 Core mix 插值，再计算 `hypot(U,V)`；色带固定为 0–30 m/s，不做自动拉伸。
|
||
- 字段 texture 以每个 snapshot 的显式 signed velocity scale 编码/还原，避免真实 m/s 数据被旧 `[-1,1]` 编码截断。
|
||
- 粒子 GPU 字段采样改为 metadata bounds 的 Web Mercator UV。字段区域外保持 fail-closed；State 初始 seed 和越界恢复均使用字段 bounds，因此真实日本区域不再被当作全球 UV。
|
||
- Android MORE 新增 `REAL WEATHER`：一次 style 初始化后，经既有 STEP-053 Host Submission Contract 依次提交真实 T0–T3；样式层级为 OSM 无 Key raster basemap → `weather-color` → `raster-particle` → Android HUD，并按 metadata bounds 自动 fit camera。
|
||
- `REAL WEATHER` 状态随 Activity 保存/恢复。重建后自动再次以相同 metadata、payload 与 validTime 提交，不要求用户按按钮恢复；粒子 Trail FBO 仍由既有 viewport resize 路径重建。
|
||
|
||
## 所有权与冻结边界
|
||
|
||
Core 仍拥有 Timeline、Playback 和 Runtime Field Window。颜色层不 tick Timeline，`RasterParticleLayer` 仍是唯一的 playback tick 消费者。未修改 Adapter contract、Snapshot、Window A/B→B/C→C/D、Duplicate NOOP、Invalid/Gap fail-closed、Renderer provider/network 边界或 WeatherColorLayer/RasterParticleLayer 分离。
|
||
|
||
正常连续边界继续依赖既有 `OLD_T1 → NEW_T0 reuse` 与 `only NEW_T1 upload`；颜色层相同地复用其旧 T1 texture，仅为新的 T1 建立新 texture。正常 playback 的粒子 `simulationRebuild=false`、`trailCleared=false` 语义不变。
|
||
|
||
## 可观察性
|
||
|
||
新增低频日志：`REAL_WEATHER_DATASET_LOAD`、`REAL_WEATHER_INITIAL_WINDOW_READY`、`WEATHER_COLOR_FIELD_READY`、`REAL_WEATHER_COMPOSITE_READY`。现有 Host submit、Timeline、Window Boundary、FIELD_REUSE、FIELD_UPLOAD 和 ParticleRender 日志继续可用。没有新增每帧 Android JNI 或 UI timer。
|
||
|
||
## 验证与待验收
|
||
|
||
Codex 未执行 Android Gradle、APK build/install、ADB、App 启动、设备/模拟器测试或 Jest。Linux/OpenGL 受影响 translation unit 精确编译与相关定向测试结果见完成报告。
|
||
|
||
Android 仍需用户一次性手工综合验收，步骤见 `docs/60_测试/STEP-055_Android真实WeatherV2风场综合可视化_人工验收指令_v1.md`。已知 Validation UI 的 MIX 文本滞后以及 WAITING/INVALID 可见性仍为 NON-BLOCKING，不在本阶段单独修复。
|
||
|
||
## 首轮 Android 视觉修复（仍待复验）
|
||
|
||
首轮实机确认真实 WeatherV2 T0–T3 Host submission、513×769 canonical Field、WeatherColorLayer 与 REAL WEATHER composite 均可工作；本轮只修复 Validation 显示与粒子物理位移表达。
|
||
|
||
- REAL WEATHER 的 raster basemap 从 OSM 换为 GSI 标准地图：`https://cyberjapandata.gsi.go.jp/xyz/std/{z}/{x}/{y}.png`。该 source 与 weather/particle source 独立，GSI tile 不可用时仍为 fail-soft；`REAL_WEATHER_COMPOSITE_READY` 明确记录 `basemap=GSI failSoft=true`。
|
||
- 底部入口变为 `TIME | VIS | COUNT | MAP | REAL WEATHER | MORE`。REAL WEATHER 不再位于 MORE：首次点击使用既有 Host Submission 提交真实 T0–T3、fit bounds、开启专属低频 `PARTICLE TUNING` 菜单；已激活时再次点击只显示/关闭菜单，不 reload Style、Dataset、Field 或 Timeline。激活状态以按钮 selected/yellow 显示。
|
||
- REAL WEATHER 专属默认值为 P=2048、W=0.75、L=0.0040、O=0.75、T=0.55、F=0.88；合成场景退出时恢复进入前的旧 validation visual state，故未改变 synthetic 场景默认值。HUD 与调参菜单读取同一实际 runtime state，二级菜单关闭后 HUD 仍显示。
|
||
- Tuning 用低频离散 `-/+` 操作覆盖 particleCount、lineWidth、streakLength、particleOpacity、trailOpacity、trailFade，并提供 RESET DEFAULT。非 particleCount 参数仅通过既有 layer property 更新；不 Style reload、不重新 submit Field、不 reset Timeline/Window。particleCount 允许仅重建 State/draw resources。
|
||
- 为支持任务规定的 2048/512/8192 档，Core 明确接受这些 validation presets，State texture 使用 `ceil(sqrt(count))`，只为实际 count 建 particle vertices；并将 visual property 下限扩到 lineWidth=0.25、streakLength=0.0005。
|
||
- 旧 shader 用无单位 `velocity * frame * 0.00004`，使真实 m/s 没有可审计的 geography conversion。现改为 U/V m/s → Web Mercator world displacement：`dx=U*dt/40075016.6856`、`dy=-V*dt/(40075016.6856*cos(latitude))`。`dt` 是稳定 wall delta（1/240–0.05s）乘 6000 simulation-seconds/real-second 的 Validation visual clock；它不改 canonical U/V、validTime、Timeline mix 或 Playback ownership，只使日本 zoom 下真实 m/s 有可见流线速度。低频 `ParticleMotion` 日志记录 sampleU/V、dt、visualSpeedScale、估算 world delta 和 simulationFrame，无 GPU readback。
|
||
|
||
本轮未修改 STEP-054 assets、Adapter、Host canonical contract、Timeline、Runtime Field Window、Renderer provider/network 边界或 WeatherColorLayer 数据链。状态继续为 **IMPLEMENTED / WAITING_ANDROID_VALIDATION**；新人工验收见 `docs/60_测试/STEP-055_Android真实WeatherV2风场综合可视化_人工验收指令_v2.md`。
|