pbf/NavSea_coast_wall_z12_bin_生成说明.md

NavSea coast_wall_z12.bin 生成说明

本文说明如何从当前 MySQL 三层格子生成 coast_wall_z12.bin。

生成脚本：

• coastline/build_coast_wall_z12_bin.py

当前输入数据库：

• navsea_japan_coast_grid

当前输入表：

• navsea_grid_cell

1. 设计口径

这个 bin 文件不是重新从原始海岸线矢量或 PBF 几何开始栅格化。

当前口径是：

1. 先使用数据库里已经生成好的三层格子
2. 再按 density_overview_grid 的密度优先级融合
3. 最后编码成 z12 / 40x40 的 blocked wall 二进制文件

三层输入：

• fish_port_20m
• hazard_50m
• coast_200m

融合规则：

• 20x20 永远保留
• 50x50 如果和已保留的 20x20 重叠，则跳过
• 200x200 如果和已保留的 20x20 或已保留的 50x50 重叠，则跳过

这和 density_overview_grid.geojson 的规则一致：同一区域优先使用更高密度格子，避免重复表达同一片阻断区域。

2. bin 格式

输出 bin 用于快速查询：

isBlocked(lon, lat) -> bool

空间划分：

• zoom：z12
• 每个 z12 tile 切成 40 x 40
• 每个 tile 最多 1600 个 cell

tile 内编码：

• blocked cell 数量 <= 96：使用 sparse uint16[]
• blocked cell 数量 > 96：使用 bitset uint32[50]

文件结构：

• Header
• BlockDirectory
• TileDirectory
• DataBlob

这个结构的目的主要是节约物理存储空间，同时让运行时可以按 block / tile 做快速查询。

3. 九州测试生成

推荐先生成九州范围样例：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/build_coast_wall_z12_bin.py \
  --preset kyushu \
  --out out/navmask/coast_wall_z12_kyushu.bin \
  --debug-geojson out/navmask/coast_wall_z12_kyushu.debug.geojson \
  --debug-limit 2000

输出文件：

• out/navmask/coast_wall_z12_kyushu.bin
• out/navmask/coast_wall_z12_kyushu.bin.meta.json
• out/navmask/coast_wall_z12_kyushu.debug.geojson

当前九州样例统计：

tiles=813
cells=148453
sparse=351
bitset=462
blocks=7
size=122625 bytes

4. 小范围 smoke test

可以用福冈附近小范围做快速验证：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/build_coast_wall_z12_bin.py \
  --self-test \
  --bbox 130,33,131,34.5 \
  --out out/navmask/coast_wall_z12_fukuoka_smoke.bin \
  --query 130.4,33.6 \
  --progress-every 0

这个命令会：

• 跑内置编码自测
• 生成小范围 bin
• 用内置 reader 查询 130.4,33.6

当前验证结果：

query lon=130.4 lat=33.6 blocked=True

5. 全国生成

全国生成命令：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/build_coast_wall_z12_bin.py \
  --preset all \
  --out out/navmask/coast_wall_z12.bin

如果需要 debug GeoJSON，可以追加：

  --debug-geojson out/navmask/coast_wall_z12.debug.geojson \
  --debug-limit 5000

全国生成会扫描完整三层数据库，耗时和内存都会高于九州样例。

6. 参数说明

常用参数：

• --preset kyushu：生成九州范围样例，默认值
• --preset all：生成全国范围
• --bbox min_lon,min_lat,max_lon,max_lat：自定义经纬度范围，优先于 --preset
• --out PATH：输出 bin 路径
• --meta-json PATH：输出 meta JSON；不指定时默认写到 <out>.meta.json
• --debug-geojson PATH：输出抽样 blocked cell GeoJSON
• --debug-limit N：debug GeoJSON 最多输出多少个 cell
• --query lon,lat：生成后用内置 reader 查询一个点
• --self-test：执行基础编码自测
• --progress-every N：每读取 N 行打印一次进度，设为 0 可关闭

查看帮助：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/build_coast_wall_z12_bin.py --help

7. 输出 meta

生成器会写出 meta JSON，包含：

• 生成时间
• 数据库名
• bbox / preset
• z12 cell 大小
• density 融合规则
• 三层源数据行数
• 三层去重后数量
• 三层保留 / 跳过统计
• bin 文件大小
• block / tile / sparse / bitset 统计
• 可选 query 查询结果

示例：

• out/navmask/coast_wall_z12_kyushu.bin.meta.json

8. 当前验证项

脚本内已包含：

• tileId pack / unpack
• cellId pack
• blockId pack
• sparse encode
• bitset encode
• writer / reader 抽样 roundtrip
• is_blocked_lonlat() 查询

已验证命令：

cd /root/sourceserver/pbf
./.venv/bin/python -m py_compile coastline/build_coast_wall_z12_bin.py
./.venv/bin/python coastline/build_coast_wall_z12_bin.py --help
./.venv/bin/python coastline/build_coast_wall_z12_bin.py --self-test --bbox 130,33,131,34.5 --out out/navmask/coast_wall_z12_fukuoka_smoke.bin --query 130.4,33.6 --progress-every 0