pbf/coastline/navgrid_v2/NavSea_v2_使用说明.md

NavSea v2 使用说明

本文只说明 coastline/navgrid_v2/ 下的新一版脚本与对应验证页。

1. 目录说明

v2 脚本目录：

• coastline/navgrid_v2/

v2 验证页：

• src/pbf/navsea-coastline-fukuoka-saga-200m-v2.html
• src/pbf/navsea-fish-port-debug-v2.html
• src/pbf/navsea-fish-port-prc50-test-v2.html
• src/pbf/navsea-coast-wall-z12-viewer.html

v2 静态资产目录：

• src/pbf/coastline-mysql-v2/

v2 规则：

• 三类数据分表保存
• cell 记录明确保存来源字段
• 不使用迁移脚本
• 直接用 v2 Python 从源数据重建
• coastline 这条链路的最终目标是导出阻断墙 bin
• 来源字段的目标不只是可追溯，也要方便检查、删除指定来源数据、以及按来源做 resume / 复跑

2. v2 表结构

2.1 沿岸数据

• 表前缀：navsea_coast_
• 主要表：
  • navsea_coast_grid_cell
  • navsea_coast_grid_layer_meta
  • navsea_coast_grid_package_stat

cell 级来源字段：

• source_code
• source_path
• source_name

2.2 渔港 20m

• 表前缀：navsea_fish_port_
• 主要表：
  • navsea_fish_port_grid_cell
  • navsea_fish_port_grid_layer_meta
  • navsea_fish_port_grid_package_stat

2.3 海上障碍 50m

• 表前缀：navsea_hazard_
• 主要表：
  • navsea_hazard_grid_cell
  • navsea_hazard_grid_layer_meta
  • navsea_hazard_grid_package_stat

海上障碍这组走轻量记录：

• navsea_hazard_grid_layer_meta.source_desc 仍然保留整体来源说明
• navsea_hazard_grid_cell.source_name 直接记录 fid
• navsea_hazard_grid_cell 额外带有 (layer_name, source_name) 索引，方便按 fid 查删和复跑
• 也就是说，单个 cell 不再追完整来源链，只保留一个代表性的 fid

3. 生成顺序

建议顺序：

1. 先生成沿岸数据
2. 再生成渔港 20m
3. 再生成海上障碍 50m
4. 再导出静态资产
5. 再生成阻断墙二进制 bin
6. 最后看验证页

4. 三个导入脚本的参数说明

这三个脚本是 v2 里最重要的“入库脚本”：

• 沿岸数据：build_coast_grid_mysql.py
• 渔港 20m：build_fish_port_20m_mysql_resume.py
• 海上障碍 50m：build_hazard_50m_mysql.py

下面把常用参数和开关说明清楚。先记一个总原则：

• build_coast_grid_mysql.py 偏“沿岸重建”
• build_fish_port_20m_mysql_resume.py 偏“续跑 + 选择性重算”
• build_hazard_50m_mysql.py 偏“全量重建，参数少”

4.1 沿岸数据：build_coast_grid_mysql.py

脚本：

• build_coast_grid_mysql.py

默认执行：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/navgrid_v2/build_coast_grid_mysql.py

常用参数：

• --input：指定海岸线 zip，支持重复传入；不传时自动扫描 coastline/C23-06_*_GML.zip
• --db-name：MySQL 数据库名
• --out-dir：GeoJSON 和元数据输出目录
• --cell-size-m：格网大小，默认 200
• --layer-name：目标层名；不传时按格网大小自动生成，例如 coast_200m、coast_50m
• --buffer-m：海岸线缓冲距离
• --margin-cells：输出范围外扩的格子数
• --write-geojson：同时导出 GeoJSON
• --resume：续跑，不清理当前 layer，保留已入库格子
• --start-code：只处理指定 source_code 及之后的包，例如 13 或 C23-06_13
• --progress-every-cells：每扫描多少个候选格打印一次进度
• --progress-every-seconds：最迟每隔多少秒打印一次进度
• --coarse-factor：粗筛倍率，值越大越省细扫，但粗框会更大

常用场景：

• 重新生成整套沿岸数据：直接运行默认命令
• 只从 C23-06_13 继续：加 --resume --start-code 13
• 做更细分辨率：加 --cell-size-m 50 --layer-name coast_50m
• 想批量重跑一段包：--resume 保留已入库结果，再配合 --start-code 从某个包号往后接着算

50m 续跑示例：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/navgrid_v2/build_coast_grid_mysql.py \
  --cell-size-m 50 \
  --layer-name coast_50m \
  --out-dir out/coastline/japan_coast_grid_mysql_v2 \
  --resume \
  --start-code 13

4.2 渔港 20m：build_fish_port_20m_mysql_resume.py

脚本：

• build_fish_port_20m_mysql_resume.py

默认执行：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/navgrid_v2/build_fish_port_20m_mysql_resume.py --resume

这支脚本的重点是“续跑”和“跳过控制”。

常用参数：

• --resume：按数据库里的断点继续，默认开启
• --no-resume：忽略数据库断点，从头规划但不清表
• --reset-layer：先清空 fish_port_20m 旧数据并删除断点
• --prc：只处理指定 PRC；传入后会按该 PRC 完整重建，并忽略 resume 断点
• --fpc：只处理指定 FPC；会先反查所在 PRC，再只重算该港口
• --cluster-gap-m：聚类连通判定的间隔
• --cell-size-m：格网大小，默认 20
• --coast-buffer-m：海岸缓冲距离
• --fish-buffer-m：渔港几何外扩缓冲，当前保留兼容
• --commit-every：每累计多少条 cell 写一次数据库
• --scan-tile-m：格网扫描分块大小
• --coast-coarse-margin-m：coast_200m 粗筛底座外扩缓冲
• --allow-unbounded-fallback：没有 coast_200m 小窗时，允许回退扫描原始 part
• --skip-missing-coarse：没有有效 coast_200m 交集时直接跳过该 part
• --max-scan-cells：单次允许估算的最大 20m 格数，超过就中止；0 表示不限制

这几个开关最值得记：

• 想继续上次中断：--resume
• 想重跑但不清表：--no-resume
• 想只重算某个港口：--fpc 4320050
• 想只重算某个 PRC：--prc 50
• 想遇到无有效粗筛时直接跳过：--skip-missing-coarse
• 想允许老式整片扫描兜底：--allow-unbounded-fallback

这里要特别注意：

• --resume 主要用于全国批量续跑，脚本会按数据库断点接着处理尚未完成的 PRC
• 一旦你显式指定 --prc 或 --fpc，脚本会进入“指定区域完整重算”模式，这时会忽略原来的 resume 断点
• 所以它支持“批量 resume”，也支持“指定区域重算”，但这两种模式不是同时叠加的

示例：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/navgrid_v2/build_fish_port_20m_mysql_resume.py \
  --resume \
  --skip-missing-coarse

4.3 海上障碍 50m：build_hazard_50m_mysql.py

脚本：

• build_hazard_50m_mysql.py

默认执行：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/navgrid_v2/build_hazard_50m_mysql.py

常用参数：

• --db-name：MySQL 数据库名
• --tile-root：全国 PBF 根目录
• --zoom：PBF 瓦片 zoom，默认 12
• --out-dir：GeoJSON 输出目录
• --source-desc：写入元数据的来源说明

这个脚本参数最少，基本就是全量重建。

5. v2 沿岸导出

脚本：

• export_coast_grid_mysql_assets.py

默认执行：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/navgrid_v2/export_coast_grid_mysql_assets.py

6. v2 调试导出

脚本：

• export_fish_port_debug_assets.py
• export_prc20_test_assets.py

示例：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/navgrid_v2/export_fish_port_debug_assets.py --fpc 4320050 --coast-buffer-m 20
./.venv/bin/python coastline/navgrid_v2/export_prc20_test_assets.py --prc 50

7. v2 共用导出

脚本：

• export_navgrid_mysql_assets.py

默认执行：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/navgrid_v2/export_navgrid_mysql_assets.py

8. 阻断墙二进制

脚本：

• build_coast_wall_z12_bin.py

默认执行：

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

默认输出文件名会自动带上当前三层单位，例如：

• out/navmask/coast_wall_z12_200_50_20.bin
• out/navmask/coast_wall_z12_100_50_20.bin
• out/navmask/coast_wall_z12_50_50_20.bin

当输出墙参数不是默认 z12 + 40x40 时，文件名会改用实际墙参数，不再沿用默认 out 里的 z12，例如：

• out/navmask/coast_wall_z14_g80_10_50.bin

这一步就是 coastline 链路的最终落点：

• 上游把三类格网数据重建出来
• 导出静态资产用于检查和发布
• 最后由这里把沿岸相关结果汇总成阻断墙 bin

如果前面的表结构、导出目录或验证页发生变化，最终都要回到这一步确认 bin 产物仍然可用。

这支脚本现在有两组“格子大小”参数，要分清：

• --coast-cell-size-m：输入海岸线层的格网大小，例如读取 coast_200m、coast_100m、coast_50m
• --zoom + --grid-size：最终阻断墙自身的输出格子大小；同一个 zoom 下 grid-size 越大，tile 内切得越细，墙 cell 越小

还有一条自动规则：

• 当 --coast-cell-size-m < 20 时，脚本会跳过 fish_port_20m
• 这是因为输入海岸线层已经比渔港 20m 更细，继续叠加渔港 20m 反而会把更粗的格子混进阻断墙
• 此时实际融合顺序会变成：
  • hazard_50m
  • 指定的 coast_*m，例如 coast_10m
• 生成的 .meta.json 会记录 include_fish_port_20m=false

默认的 bin 组合顺序是：

• fish_port_20m
• hazard_50m
• coast_200m

如果你要把海岸线层切成更细的版本，可以直接改参数：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/navgrid_v2/build_coast_wall_z12_bin.py --coast-cell-size-m 100
./.venv/bin/python coastline/navgrid_v2/build_coast_wall_z12_bin.py --coast-cell-size-m 50

如果要调整最终墙的 cell 大小，可以改 zoom 和 grid-size：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/navgrid_v2/build_coast_wall_z12_bin.py \
  --zoom 11 \
  --grid-size 80

如果输入海岸线层已经做到 10m，可以这样生成更细的墙；这时会自动不使用渔港 20m：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/navgrid_v2/build_coast_wall_z12_bin.py \
  --zoom 14 \
  --grid-size 80 \
  --coast-cell-size-m 10

这个命令的默认输出会是：

• out/navmask/coast_wall_z14_g80_10_50.bin

常用理解：

• 默认 --zoom 12 --grid-size 40，墙 cell 约 244.6m
• --zoom 12 --grid-size 80，墙 cell 约 122.3m
• --zoom 13 --grid-size 40，墙 cell 约 122.3m
• --zoom 13 --grid-size 80，墙 cell 约 61.1m

如果横向和纵向要分别调，可以使用：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/navgrid_v2/build_coast_wall_z12_bin.py \
  --zoom 12 \
  --grid-w 80 \
  --grid-h 80

如果海岸线表名不跟着默认规则走，也可以直接指定：

cd /root/sourceserver/pbf
./.venv/bin/python coastline/navgrid_v2/build_coast_wall_z12_bin.py \
  --coast-layer-name coast_100m \
  --coast-cell-size-m 100

如果想直接看 bin 的效果，可以打开：

• src/pbf/navsea-coast-wall-z12-viewer.html

在页面里选择生成好的 coast_wall_*.bin，可选再选择同名 .meta.json，就能直接看最终阻断墙的铺面效果。查看页会按 bin header 自动识别 zoom 和 grid。

9. 验证页

• http://192.168.200.184/newpec/navsea-coastline-fukuoka-saga-200m-v2.html
• http://192.168.200.184/newpec/navsea-fish-port-debug-v2.html
• http://192.168.200.184/newpec/navsea-fish-port-prc50-test-v2.html