# 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 预处理管线**： ```text 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 调试输出（仅调试用途） --- ## 栅格语义定义 本任务只定义第一版最小语义： ```text CellState: 0 = UNKNOWN 1 = NAVIGABLE_CANDIDATE 2 = HARD_BLOCKED ``` 说明： - `UNKNOWN`：未纳入当前处理范围或缺少足够信息； - `NAVIGABLE_CANDIDATE`：当前阶段未发现岸线硬阻塞，仅表示“未被岸线阻塞”，不代表安全可航行； - `HARD_BLOCKED`：与陆地 / 经膨胀后的海岸硬阻塞面相交，禁止通行。 ### 最低字段设计 建议每个格子最终至少具备以下字段： ```text 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：格子阻塞判定 目标：将海岸线障碍面落入格网。 推荐规则： ```text 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) 查询。 建议： - 按分块导出二进制； - 使用轻量索引文件记录块范围； - 运行时只加载当前位置邻近块。 --- ## 推荐目录结构（建议，不强制） ```text 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 初始化规则。 --- ## 配置建议 ### 配置文件建议字段 ```yaml 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 依赖，必须先说明必要性、体积和运行影响。 --- ## 建议的首批交付文件（示意，不代表固定路径） ```text /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、完整替换文件等协作规则。