MapLibreParticleLab/tools/weatherv2_wind_canonical/README.md

WeatherV2 风场转 MapLibre canonical 测试数据工具

此工具只用于开发期离线转换：将 WeatherV2 的完整 wind_vectors.bin（WVECBIN1）转成 STEP-053 已冻结的 maplibre-particle-field/v1，不属于 MapLibre Runtime，也不访问网络、不扫描下载目录、更不修改 WeatherV2 原始数据。

输入

输入为一个 WeatherV2 reference/run 目录及其中一个 YYYYMMDDHH valid time：

<run-dir>/<valid-time>/wind_vectors.bin
<run-dir>/<valid-time>/wind_vectors.bin.header.json

当前已核对的 WVECBIN1 布局为：magic(8)、little-endian uint32 headerLength、UTF-8 JSON header、row-major u float32-le 平面、v float32-le 平面、speed float32-le 平面、valid uint8 平面。WeatherV2 bin_export.py 将同一 decode_wind() U/V grid 写出；QBIN 和 NSFT 也从同一 decoder U/V 生成。QBIN metadata 明确其 U/V 单位为 m/s，因此本工具保持 m/s，不进行 kt 换算。

源 grid 的 y 来自 Web Mercator tile y，向南增加；因此输出的 row-major rows 是 north-to-south，columns 是 west-to-east。U=eastward-positive，V=northward-positive。

输出

每个输出目录包含：

• metadata.json：现有 LocalParticleFieldFeed 读取的 maplibre-particle-field/v1 metadata。
• field.f32：float32-le interleaved-uv，顺序为 U0,V0,U1,V1,...。
• conversion_summary.json：源/输出 bounds、尺寸、统计值、valid/noData 计数、抽样一致性与 SHA-256。

本工具不重采样。每个源 valid=0 或非有限 U/V 的 cell 会写为既有 canonical noData=-9999.0 的 U/V 对；不会错误变成静风 (0,0)。有效样本按 float32 bit-exact 复制。

命令示例

python3 tools/weatherv2_wind_canonical/convert_weatherv2_wind.py \
  --run-dir /root/sourceserver/weatherV2/src/dev/_runtime/dev_pipeline_data/datasets/ecmwf-hres/wind/2026080600 \
  --valid-time 2026080700 \
  --output platform/android/MapLibreAndroidTestApp/src/main/assets/integration/particle-weatherv2/ecmwf-hres-wind-20260807/2026080700

相同输入会产生相同 payload SHA-256。错误会输出明确消息并以非零状态退出。