582 lines
17 KiB
Markdown
582 lines
17 KiB
Markdown
# 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、完整替换文件等协作规则。
|
||
|