# NavSea coast_wall_z12.bin 生成说明

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

生成脚本：

- [`coastline/build_coast_wall_z12_bin.py`](/root/sourceserver/pbf/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 用于快速查询：

```text
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. 九州测试生成

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

```bash
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`

当前九州样例统计：

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

## 4. 小范围 smoke test

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

```bash
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`

当前验证结果：

```text
query lon=130.4 lat=33.6 blocked=True
```

## 5. 全国生成

全国生成命令：

```bash
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，可以追加：

```bash
  --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` 可关闭

查看帮助：

```bash
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()` 查询

已验证命令：

```bash
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
```