pbf/coastline/NavSea_Task_Japan_Coastline_Grid_codex6.md

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、完整替换文件等协作规则。