tei/pbf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
07d16c38a8f564137b3e4eb0231a6396ed1bc009
pbf/coastline/NavSea_Task_Japan_Coastline_Grid_codex6.md

17 KiB
Raw Blame History

NavSea 任务说明（codex6 / V11）

任务名称

日本全国海岸线硬阻塞栅格预处理（GSI 基盤地図情報版）

任务编号

NAVSEA-TASK-COASTLINE-GRID-JP-001

任务状态

待实现

任务目标

基于日本国土地理院（GSI）提供的基盤地図情報（FGD）海岸线数据，构建一套可离线预处理的日本全国海域200m × 200m 硬阻塞栅格底库，供 NavSea 路由系统直接使用。

本任务只解决以下问题：

  • 将日本陆地 / 海岸线转化为路由可直接查询的硬阻塞格网；
  • 为后续叠加浅滩、禁航区、桥梁净空、港内限制区等语义层提供统一栅格基底；
  • 避免运行时直接依赖 MapLibre 的 MVT/PBF 做判障。

本任务不解决以下问题：

  • 不生成可显示用的地图瓦片；
  • 不替代官方航海图或 ENC；
  • 不在本阶段判断“安全可航行水深”；
  • 不在本阶段实现潮汐相关动态可航行性；
  • 不在本阶段实现最终航线规划器。

业务背景

当前 NavSea 项目中的 PBF 为 MapLibre 使用的矢量瓦片 PBF（MVT），适合显示，不适合作为全国统一的分析型原始数据库直接做路径判障。

因此需要额外建立一套Routing Grid 预处理管线：

GSI 海岸线 / 其他航海语义数据
-> 几何清洗与统一投影
-> 障碍膨胀（buffer）
-> 200m fishnet 栅格化
-> 二进制 / 分块索引输出
-> NavSea 路由核心直接查询

本任务是该预处理体系中的第一阶段：

先用官方海岸线把“陆地绝对不可通行”这件事做对。

数据来源与现实约束

主数据源

日本国土地理院（GSI）基盤地図情報（FGD）中的海岸线数据。

已确认事实：

  • GSI 基盤地図情報站点明确列出“海岸線”为可下载项；
  • 下载服务需要用户注册并登录；
  • 海岸线属于基盤地図情報的法定基础项之一；
  • 精度说明为：城市区域约 1:2500 级别，其它区域约 1:25000 级别；
  • 下载服务提供 JPGIS（GML）形式；
  • 提供文件按区域网格切分，文件命名规则中 ss=02 对应海岸线。
  • 已经下载在目录里了。

备选/补充数据源

国土数值信息（KSJ）海岸线数据可作为补充属性源，但其页面说明：

  • 最新数据作成年度为 2006 年度；

使用约束

本任务默认目标是：

  • 在 NavSea 内部离线预处理使用；
  • 不在仓库中直接提交受许可限制的原始 GSI 数据；
  • 原始下载数据路径加入 .gitignore；

本任务的成功标准

完成后，系统应具备以下能力：

  1. 可以从本地 GSI 海岸线原始数据目录读取全国数据；
  2. 可以统一转换为 NavSea 内部标准几何坐标体系；
  3. 可以生成经过安全膨胀的硬阻塞面；
  4. 可以按固定 origin 生成 200m × 200m 的全国海域格网；
  5. 可以将与硬阻塞面相交的格子标记为 hardBlocked = true；
  6. 可以导出供运行时快速查询的二进制结果；
  7. 生成过程支持分块处理、断点重建、日志输出与结果校验；
  8. 不依赖 MapLibre 前端进行任何运行时几何判障。

范围定义

In Scope

  • GSI 海岸线数据下载后的本地导入与解析；
  • GML -> 内部几何数据转换；
  • 海岸线质量检查、闭合/拼接/拓扑清洗；
  • 海岸线转陆地硬阻塞面；
  • 陆地障碍安全 buffer；
  • 全国 200m 栅格生成；
  • 格子状态计算；
  • 分块导出二进制格网；
  • 校验工具与统计输出；
  • 针对东京湾 / 大阪湾 / 北海道沿岸的抽样验收。

Out of Scope

  • 水深区、浅滩、礁石、干出区、桥梁净空；
  • 港口规则、禁航区、养殖区；
  • 潮汐动态更新；
  • 路由算法本体；
  • UI 显示层改造；
  • 在线下载 GSI 数据功能。

输入与输出定义

输入

  1. GSI 基盤地図情報原始下载目录（本地，不入库）
  2. 配置文件：
    • 输入目录
    • 输出目录
    • 目标区域 bbox
    • 栅格尺寸（默认 200m）
    • 安全 buffer 距离
    • 投影方案
  3. 日本区域边界配置
  4. 船舶安全参数（本任务中仅使用岸线横向安全余量）

输出

  1. routing-grid-jp-coast-v1.bin
  2. routing-grid-jp-coast-v1.index.json
  3. routing-grid-jp-coast-v1.meta.json
  4. 校验报告：
    • 总格子数
    • 被阻塞格子数
    • 未知格子数
    • 各分块统计
  5. 抽样 PNG / GeoJSON 调试输出（仅调试用途）

栅格语义定义

本任务只定义第一版最小语义：

CellState:
0 = UNKNOWN
1 = NAVIGABLE_CANDIDATE
2 = HARD_BLOCKED

说明：

  • UNKNOWN：未纳入当前处理范围或缺少足够信息；
  • NAVIGABLE_CANDIDATE：当前阶段未发现岸线硬阻塞，仅表示“未被岸线阻塞”，不代表安全可航行；
  • HARD_BLOCKED：与陆地 / 经膨胀后的海岸硬阻塞面相交，禁止通行。

最低字段设计

建议每个格子最终至少具备以下字段：

struct CoastGridCellV1 {
  uint8 state;              // 0 unknown, 1 candidate, 2 hard_blocked
  uint8 sourceMask;         // bit mask，当前阶段至少标记 GSI_COASTLINE
  uint16 blockedPermille;   // 0..1000，表示障碍覆盖率千分比
}

备注：

  • 本阶段不要过早把格式做复杂；
  • 允许后续升级到 GridCellV2/V3 增加 depth / clearance / risk；
  • V11 阶段不得破坏已有读取接口，后续升级采用 wrapper 或版本扩展。

技术设计原则

1. 显示层与路由层分离

  • MapLibre 的 MVT/PBF 继续只服务于显示；
  • 路由判障只读取预处理后的 routing grid；
  • 不允许运行时对 MVT 做空间判障。

2. 先建立官方岸线“硬真值基底”

  • 以 GSI 海岸线为陆地硬阻塞基线；
  • MapLibre 中显示出来的岸线不得反向覆盖 routing 真值；
  • 后续其他语义层只能在该基底上叠加，不得削弱陆地阻塞语义。

3. 所有距离计算使用米制坐标

  • 不允许直接在经纬度下用近似角度长度做 200m 格网；
  • 统一先转换到米制坐标后再生成 fishnet；
  • 投影方案允许一期先用单一米制投影跑通，后续再按日本区域分带优化。

4. 禁止中心点判障

  • 不允许只用格子中心点判断是否阻塞；
  • 必须按面积相交比例判断；
  • 必须支持陆地障碍 buffer 后再相交。

5. 支持分块处理

  • 日本全国数据不得要求一次性整体载入内存；
  • 必须支持按区域块 / tile / mesh 批处理；
  • 必须允许断点续跑。

6. 原始数据不入库

  • 仓库中仅保留导入脚本、格式说明、配置模板；
  • 不提交 GSI 原始下载文件；
  • 若需要示例数据，仅保留极小匿名/脱敏调试切片（如许可允许）。

推荐处理流程

阶段 A：原始数据导入

目标：把 GSI 原始 GML 数据转成统一内部几何集合。

步骤：

  1. 扫描输入目录，识别海岸线数据文件；
  2. 解析文件名与区域标识；
  3. 读取 GML 几何与属性；
  4. 写入中间层（如 GeoPackage / FlatGeobuf / 临时二进制几何块）。

产出：

  • 标准化海岸线线要素集合；
  • 区域索引；
  • 导入日志。

阶段 B：几何清洗与陆地阻塞面构造

目标：把原始海岸线转换为可用于判障的封闭障碍面。

步骤：

  1. 统一坐标系；
  2. 去除明显坏几何；
  3. 线拼接与拓扑清洗；
  4. 构造陆地区域面或沿岸阻塞面；
  5. 对陆地边界做安全膨胀（buffer）。

注意：

  • 如果无法全国一次性可靠构造完整陆地面，可采用“海岸线 + 陆地方向约定 + 沿岸膨胀面”作为一期方案；
  • 二期再升级为完整 seam-less land polygon。

阶段 C：生成 200m fishnet

目标：生成路由统一栅格索引。

步骤：

  1. 确定全国处理范围 bbox；
  2. 确定固定 grid origin；
  3. 生成 200m × 200m 分块格网；
  4. 给每格分配全局 cellId 或 (gx, gy)。

要求：

  • origin 固定，保证不同批次重建结果完全一致；
  • 必须能按区域分块增量重算。

阶段 D：格子阻塞判定

目标：将海岸线障碍面落入格网。

推荐规则：

if blockedOverlapRatio > 0:
    state = HARD_BLOCKED
else if insideCoverageArea:
    state = NAVIGABLE_CANDIDATE
else:
    state = UNKNOWN

更稳妥的建议：

  • 同时记录 blockedPermille；
  • 若后续发现边缘误判过多，可升级阈值为：
    • > 20‰ 即 hard block；
    • 或与 buffer 配合后采用更保守规则。

阶段 E：导出运行时格式

目标：让 NavSea 在运行时做到 O(1) 或近 O(1) 查询。

建议：

  • 按分块导出二进制；
  • 使用轻量索引文件记录块范围；
  • 运行时只加载当前位置邻近块。

推荐目录结构（建议，不强制）

navsea/
  tools/
    chart-grid-builder/
      src/
        ingest/
        normalize/
        rasterize/
        export/
        validate/
      config/
      scripts/
      README.md
  data/
    generated/
      routing-grid/
  docs/
    tasks/
      NAVSEA-TASK-COASTLINE-GRID-JP-001.md

说明：

  • 原始 GSI 数据目录不放入仓库；
  • 通过环境变量或本地配置指定；
  • 所有新 .ts/.tsx 文件必须遵守 NavSea 的 logger 初始化规则。

配置建议

配置文件建议字段

jobName: jp-coast-grid-v1
input:
  gsiCoastRoot: /local/path/to/gsi/coast
output:
  root: /local/path/to/output
region:
  bbox:
    minLon: 122.0
    minLat: 20.0
    maxLon: 154.0
    maxLat: 46.5
projection:
  mode: metric_projected
grid:
  cellSizeMeters: 200
  originX: 0
  originY: 0
obstacle:
  coastBufferMeters: 50
processing:
  chunkSizeMeters: 20000
  resume: true
validation:
  sampleAreas:
    - tokyo_bay
    - osaka_bay
    - hokkaido_coast

备注：

  • coastBufferMeters 需结合你的船长、定位误差、岸边保守量再定；
  • 一期可先用固定值，二期再改成基于船型配置。

关键实现要求

1. 导入器要求

  • 能处理批量 GML；
  • 能输出导入统计；
  • 能跳过坏文件并记录错误；
  • 支持断点续跑。

2. 几何模块要求

  • 能统一投影；
  • 能做拓扑清洗；
  • 能做 buffer；
  • 能输出调试几何。

3. 栅格模块要求

  • 使用固定 grid origin；
  • 支持按 chunk 生成；
  • 可根据 bbox 仅重建局部区域；
  • 输出 deterministic 结果。

4. 导出模块要求

  • 文件格式需带版本号；
  • 必须包含元数据文件；
  • 元数据至少包含：
    • 版本
    • 生成时间
    • 输入数据摘要
    • cellSize
    • bbox
    • 分块信息
    • 统计信息

5. 验证模块要求

  • 生成统计摘要；
  • 支持抽样区域导出 GeoJSON/PNG 调试图；
  • 支持人工核查岸线附近格子是否被正确封堵。

验收标准

功能验收

  1. 可从本地 GSI 数据生成至少一个样例区域的 200m 栅格；
  2. 东京湾样例中，陆地区域相邻格子被正确标记为 HARD_BLOCKED；
  3. 非陆地区域不会被大面积误封；
  4. 相同输入重复运行结果一致；
  5. 局部重建不会改变未涉及分块结果；
  6. 运行时查询不依赖 GSI 原始数据与 MVT。

数据验收

  1. 输出包含版本与元数据；
  2. 统计报告完整；
  3. 至少完成三个区域的人工抽样检查：
    • 东京湾
    • 大阪湾 / 濑户内海入口
    • 北海道沿岸

工程验收

  1. 原始下载数据不进入 git；
  2. 代码结构符合 V11；
  3. 新增 .ts/.tsx 文件遵守 logger 初始化规则；
  4. 不引入未知依赖；
  5. 对外接口保持后续可扩展。

风险与应对

风险 1：海岸线无法直接构造成稳定陆地面

应对：

  • 一期先实现“海岸线 + buffer”阻塞带；
  • 二期再升级为完整 land polygon。

风险 2：全国数据量导致内存占用过高

应对：

  • 强制 chunk 化处理；
  • 中间结果写盘；
  • 禁止一次性全量几何载入。

风险 3：投影方案导致边缘区域误差不一致

应对：

  • 一期先统一米制投影跑通；
  • 二期再评估按区域分带；
  • 元数据中记录投影方案版本。

风险 4：岸线细节不足导致近岸误判

应对：

  • 记录样例区域误差；
  • 后续叠加港口高精层或局部更高精数据；
  • 不将 NAVIGABLE_CANDIDATE 误解为真实安全通航。

风险 5：许可边界不清

应对：

  • 明确原始数据不入库；
  • 在 docs 中记录数据来源与许可审查待办；
  • 若未来要发布生成结果，单独评估。

分阶段实施计划

Phase 1：最小可运行样例

目标：跑通单一区域。

交付：

  • GSI 海岸线导入器
  • 投影转换
  • 200m 栅格生成
  • hardBlocked 判定
  • 东京湾样例输出

Phase 2：全国化与分块化

目标：支持全国离线构建。

交付：

  • 分块处理
  • 断点续跑
  • 二进制导出
  • 索引文件
  • 统计报告

Phase 3：质量提升

目标：提高近岸判障质量。

交付：

  • 岸线拓扑清洗增强
  • 更稳妥的陆地面构造
  • 局部高风险区域人工校验工具

Phase 4：为后续航海语义层预留接口

目标：让后续浅滩/限制区/桥梁等数据可无缝叠加。

交付：

  • GridCellV2 设计草案
  • source mask 扩展规则
  • depth / clearance / risk 预留位设计

对 Codex 的具体执行要求

规则 1：遵守 NavSea V11 宪章

  • 不破坏现有架构；
  • 不在显示层混入路由判障逻辑；
  • 不直接修改 MapLibre 数据消费方式来偷跑此功能；
  • 以独立预处理模块实现。

规则 2：遵守现有协作流程

  • 新文件：由实现方直接给出文件路径和完整代码；
  • 旧文件：必须先读取用户提供的当前版本，再给完整替换版本；
  • 不只给片段补丁；
  • 不臆测未提供的项目结构。

规则 3：版本标识

  • 每个完整替换文件头部必须带明确版本注释；
  • 建议统一使用如 v11.x-coast-grid 标识。

规则 4：日志要求

  • 每个新增 .ts/.tsx 文件顶部必须加入 NavSea 规定的 logger 初始化；
  • 日志要覆盖：导入、分块处理、异常、统计输出。

规则 5：不要引入未知重依赖

  • 优先使用现有项目依赖与成熟轻量方案；
  • 若确需增加 geospatial 依赖，必须先说明必要性、体积和运行影响。

建议的首批交付文件（示意，不代表固定路径）

/tools/chart-grid-builder/src/config/CoastGridJobConfig.ts
/tools/chart-grid-builder/src/ingest/GsiCoastlineScanner.ts
/tools/chart-grid-builder/src/ingest/GsiCoastlineParser.ts
/tools/chart-grid-builder/src/normalize/CoastlineNormalizer.ts
/tools/chart-grid-builder/src/normalize/CoastObstacleBuilder.ts
/tools/chart-grid-builder/src/rasterize/FishnetGrid.ts
/tools/chart-grid-builder/src/rasterize/CoastGridRasterizer.ts
/tools/chart-grid-builder/src/export/CoastGridBinaryWriter.ts
/tools/chart-grid-builder/src/validate/CoastGridValidator.ts
/tools/chart-grid-builder/src/cli/buildJapanCoastGrid.ts
/docs/tasks/NAVSEA-TASK-COASTLINE-GRID-JP-001.md

非功能要求

  • 可重复构建；
  • 结果确定性；
  • 可追踪元数据；
  • 支持未来增量升级；
  • 输出格式稳定；
  • 允许未来按海区局部重建。

备注

  1. 本任务是“全国路由底库”的起点，不是最终航海安全判定系统；
  2. NAVIGABLE_CANDIDATE 只是“未被海岸线阻塞”，不是“确认可安全航行”；
  3. 后续必须叠加至少以下层才能形成更可靠的海上路由基础：
    • 浅水 / 水深层
    • 干出区
    • 礁石 / 危险物
    • 桥梁净空
    • 禁航区 / 受限区
    • 港内限制区
    • 养殖区 / 网具区

参考资料（供实现时核对）

  • GSI 基盤地図情報站点：明确基盤地図情報可下载，且需要注册登录。
  • GSI 基盤地図情報说明：海岸线属于法定基础项之一。
  • GSI 下载服务：海岸线为可选下载项。
  • GSI FAQ / Help：下载服务为注册制，基本项下载为 JPGIS（GML）形式。
  • GSI 文件命名规则：提供类编号 02 对应海岸线。
  • GSI 数值地图（国土基本信息）说明：城市区域约 1:2500，其它区域约 1:25000 级精度。
  • KSJ 海岸线数据页：可作补充参考，但年度老且页面标示非商用。

完成定义（Definition of Done）

当且仅当以下条件同时满足时，本任务可标记完成：

  1. 样例区域可以从 GSI 原始数据成功生成 200m 海岸硬阻塞格网；
  2. 全国构建流程可运行并支持分块；
  3. 输出带版本号、元数据与统计；
  4. 东京湾 / 大阪湾 / 北海道沿岸完成抽样验证；
  5. 运行时可仅依赖生成后的 grid 查询，不再读取 GSI 原始数据与 MVT 判障；
  6. 实现过程遵守 NavSea V11、codex6、logger、完整替换文件等协作规则。
Reference in New Issue View Git Blame Copy Permalink