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

12 KiB
Raw Permalink Blame History

NavSea 任务说明（codex6）

任务名称

港湾区域叠加判定与分级栅格生成（日本全国）

任务编号

NAVSEA-TASK-PORT-AREA-OVERLAY-CLASSIFICATION-JP-001

任务类型

数据预处理 / 路由底库构建 / 港湾语义叠加

适用架构

  • NavSea Architecture V11
  • NavSea Codex System v6（codex6）

任务背景

上一阶段任务已确定：

  • 使用日本国土地理院（GSI）基盤地図情報中的海岸线数据，作为日本全国海陆边界与硬阻塞判定的基础真值源。
  • 该数据可区分部分海岸线形态，例如通常部、岩等接触部分、堤防等接触部分。

但仅靠海岸线数据，不能可靠区分：

  • 港口区域内岸线
  • 普通自然海岸线
  • 商港/渔港/人工港湾周边可航行与受限水域

因此本任务单独建立“港湾区域叠加判定”模块，用于在既有海岸线硬阻塞格网基础上，叠加港湾区域、港域边界、人工岸线邻接关系，并生成供路由系统使用的港湾语义标签与分级栅格。

本任务目标

构建一套日本全国统一的“港湾区域叠加判定”预处理流水线，实现：

  1. 将港湾区域数据导入并标准化。
  2. 与 GSI 海岸线数据进行空间叠加。
  3. 对海岸线附近及水域格子进行港湾语义分类。
  4. 输出可供 NavSea 路由层直接读取的分级格网标签。
  5. 支持不同区域精度策略：
    • 基础全国海域：200m × 200m
    • 港湾/近岸重点区：50m × 50m
    • 外海区域：50m × 50m（按用户当前要求执行）

注意：本任务不负责显示层渲染，不修改 MapLibre 显示瓦片，不直接修改现有海图展示流程。

用户要求（必须满足）

1. 语义要求

必须能区分至少以下类别：

  • 普通海岸线附近水域
  • 港湾区域内水域
  • 港湾区域内人工岸线邻近水域
  • 港湾边界邻近过渡水域
  • 无法判定区域

2. 精度要求

必须支持分级网格：

  • 日本全国基础层：200m x 200m
  • 港湾重点层：50m x 50m
  • 外海区域：50m x 50m

3. 架构要求

必须遵守 NavSea V11 与 codex6 协作规则：

  • 不破坏既有架构边界
  • 不把显示层 MVT/PBF 直接当作路由真值源
  • 新增能力应作为独立预处理模块接入
  • 输出独立路由底库，不污染显示数据

数据来源

A. 主海岸线真值源

GSI 基盤地図情報（海岸線）

  • C09-06.zip 和 C02-08.zip 港湾和渔港

用途：

  • 海陆边界
  • 海岸线类型辅助判定
  • 人工岸线/自然岸线邻接判断

B. 港湾语义源

国土数值信息（KSJ）港湾データ

用途：

  • 港湾区域
  • 港域边界线
  • 港湾名
  • 港湾种别
  • 管理属性（若可用）

C. 可选补充源

仅在后续验证确有需要时引入：

  • 渔港数据
  • 河口・運河相关数据
  • 港内限制区/航路数据
  • NavSea 现有矢量瓦片中的 harbour / pier / breakwater / seawall 图层

原则：GSI/KSJ 优先作为判定真值，MapLibre MVT 仅作补充，不反客为主。

最终输出目标

输出一套供 NavSea 路由模块使用的“港湾区域叠加语义格网”。

目标输出一：统一分类格网

每个格子至少要包含以下字段：

export type PortOverlayCell = {
  gridLevel: 50 | 200;
  cellId: string;
  bbox: [number, number, number, number];
  insidePortArea: boolean;
  nearPortBoundary: boolean;
  nearArtificialCoast: boolean;
  nearGeneralCoast: boolean;
  classification:
    | "PORT_WATER"
    | "PORT_COAST"
    | "GENERAL_COAST"
    | "PORT_TRANSITION"
    | "OPEN_WATER"
    | "UNKNOWN";
  sourceMask: number;
  confidence: number;
};

目标输出二：供路由使用的轻量索引

建议生成：

  • routing-port-overlay-japan-v1.bin
  • routing-port-overlay-japan-v1.index.json
  • 或按区域分块的二进制 tile/chunk 文件

目标输出三：验证样本

至少输出以下区域的可视化验证结果：

  • 东京湾
  • 大阪湾
  • 濑户内海重点港区
  • 北海道沿岸样本区

核心判定模型

一、基础分类目标

必须至少实现以下 6 类：

PORT_WATER        港湾区域内一般水域
PORT_COAST        港湾区域内且邻近人工岸线/码头/护岸的水域或格子
GENERAL_COAST     非港湾区域、邻近普通海岸线的水域或格子
PORT_TRANSITION   港湾边界附近过渡水域
OPEN_WATER        不属于港湾、也不邻近海岸线的开放水域
UNKNOWN           数据缺失或冲突无法可靠判定

二、建议判定逻辑

1. 若格子与港湾区域面相交：
   -> insidePortArea = true

2. 若格子落入港湾边界线缓冲区：
   -> nearPortBoundary = true

3. 若格子与 GSI 海岸线相邻，且岸线类型为“堤防等接触部分”或其他人工岸线代理：
   -> nearArtificialCoast = true

4. 若格子与 GSI 海岸线相邻，且岸线类型为通常部/岩等接触部分：
   -> nearGeneralCoast = true

三、建议分类优先级

if insidePortArea && nearArtificialCoast:
    classification = PORT_COAST
elif insidePortArea:
    classification = PORT_WATER
elif nearPortBoundary:
    classification = PORT_TRANSITION
elif nearGeneralCoast:
    classification = GENERAL_COAST
elif not nearGeneralCoast && not insidePortArea:
    classification = OPEN_WATER
else:
    classification = UNKNOWN

分级栅格策略（必须执行）

本任务必须采用分级网格，不允许全国只用单一粒度。

Level 1：全国基础层

  • 网格尺寸：200m x 200m
  • 用途：全国范围初步港湾语义覆盖
  • 主要服务：大范围路由预筛选、低成本索引

Level 2：重点精细层

  • 网格尺寸：50m x 50m
  • 必须覆盖：
    • 港湾区域
    • 港湾边界缓冲区
    • 海岸线缓冲区
    • 外海区域（按当前用户要求）

精细层触发规则

建议任一满足即进入 50m 层：

  • 进入港湾区域
  • 距离港湾边界小于设定阈值
  • 距离海岸线小于设定阈值
  • 属于外海区域

注意

外海区域 50m × 50m 将显著增加数据量和预处理成本。 因此实现上必须支持：

  • 分块构建
  • 分块存储
  • 区域化加载
  • 不能假设全部一次性常驻内存

空间处理建议

1. 投影要求

不得直接在经纬度下用固定度数近似米网格。 必须先转换到米制投影后生成格网。

建议方案：

  • 统一米制投影方案
  • 或按区域分带处理后落格

2. 缓冲区建议

建议至少配置以下缓冲：

  • 港湾边界缓冲区
  • 海岸线邻接缓冲区
  • 人工岸线增强缓冲区

缓冲值不要写死在代码中，必须参数化。

3. 判定方式

不允许只使用“格子中心点落入关系”完成判定。 必须支持至少一种更稳妥方法：

  • 面积相交比例
  • 最短距离
  • 缓冲后相交

建议组合：

  • 面相交用于区域类判断
  • 距离判断用于边界/邻接类判断

输出标记建议

A. 供规则引擎读取的主分类

export type PortOverlayClass =
  | "PORT_WATER"
  | "PORT_COAST"
  | "GENERAL_COAST"
  | "PORT_TRANSITION"
  | "OPEN_WATER"
  | "UNKNOWN";

B. 供路由代价层使用的附加标签

export type PortOverlayFlags = {
  insidePortArea: boolean;
  nearPortBoundary: boolean;
  nearArtificialCoast: boolean;
  nearGeneralCoast: boolean;
  highConfidence: boolean;
};

C. 供代价映射使用的建议

PORT_COAST      -> 高代价或半禁行
PORT_WATER      -> 中高代价
PORT_TRANSITION -> 中代价
GENERAL_COAST   -> 中高代价
OPEN_WATER      -> 低代价
UNKNOWN         -> 高代价或待人工确认

本任务只负责语义输出，不在此任务中写死最终寻路代价函数。

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

navsea/
  tools/
    port-overlay-grid-builder/
      README.md
      src/
        loaders/
        normalizers/
        classifiers/
        grid/
        exporters/
      config/
      samples/
  data/
    source/
      gsi/
      ksj/
    derived/
      routing-grids/
      validation/

模块边界

本任务负责

  • 港湾数据读取
  • 港湾区域标准化
  • 与海岸线叠加
  • 分级格网生成
  • 分类输出
  • 验证样本输出

本任务不负责

  • MapLibre 地图显示改造
  • 实时路径搜索算法本体
  • UI 呈现
  • 航道/水深/桥净空等其他语义融合

开发阶段拆分

Phase 1：数据审计与标准化

目标：确认 GSI + KSJ 的字段结构与可用于判定的关键属性。

交付物：

  • 数据字段审计报告
  • 统一内部字段映射表
  • 样本区域导入脚本

Phase 2：空间叠加与分类规则实现

目标：实现港湾区域、港湾边界、海岸线邻接的空间判定。

交付物：

  • 叠加模块
  • 分类模块
  • 样本区验证输出

Phase 3：分级格网与导出

目标：生成 200m/50m 双层格网输出，并提供路由可读索引。

交付物：

  • 二进制或分块索引输出
  • 校验脚本
  • 抽样验证报告

Phase 4：NavSea 接入准备

目标：定义与现有 routing 模块的接入边界。

交付物：

  • 接口约定文档
  • 数据版本规则
  • 后续融合任务建议

验收标准

必须通过

  1. 能正确导入并读取 GSI 海岸线与 KSJ 港湾数据。
  2. 能完成港湾区域与海岸线的空间叠加。
  3. 能输出六类基础分类结果。
  4. 能生成 200m 与 50m 两级格网。
  5. 能在东京湾与大阪湾样本区输出可人工核查结果。
  6. 输出结构可被后续路由模块直接消费。

不通过条件

以下任一成立则视为未完成：

  • 仅使用中心点判定
  • 未支持 50m 精细层
  • 未把港湾区域与普通海岸语义分开
  • 结果仍依赖 MapLibre MVT 在线查询
  • 输出格式不能稳定复现

风险与注意事项

1. 港湾数据边界语义可能与显示地图不完全一致

必须以预处理真值源为准，不以显示层瓦片视觉效果为准。

2. 50m 全覆盖数据量会很大

必须分块，不得设计为一次性全量内存方案。

3. 人工岸线识别可能并不完全等于码头语义

本任务先实现“人工岸线邻近”判定，不夸大为“所有码头设施已识别”。

4. UNKNOWN 不能被默认为 OPEN_WATER

对无法确定区域，默认应保守处理。

与已有任务关系

本任务是以下任务的扩展任务：

  • 日本全国海岸线硬阻塞栅格生成任务

关系说明：

  • 前任务解决“海陆边界与硬阻塞真值”
  • 本任务解决“港湾区域语义与海岸线语义叠加”
  • 后续可继续扩展到：
    • 水深层
    • 航道层
    • 港内限制区
    • 桥净空层
    • 养殖区层

Codex 执行要求

必须遵守

  1. 所有新文件必须符合 NavSea V11 / codex6 规范。
  2. 新建 .ts/.tsx 文件时，必须包含项目约定的 logger 初始化。
  3. 不允许臆测未知项目结构。
  4. 新文件由 AI 提供文件路径和完整代码。
  5. 修改旧文件前，必须先由用户提供原文件内容，再返回完整替换版本。
  6. 不引入未知依赖，不擅自改变既有模块边界。

输出要求

后续进入编码阶段时，AI 必须：

  • 明确文件路径
  • 提供完整替换内容
  • 在文件头加入清晰版本标注
  • 保持可直接复制使用

建议后续子任务

  1. 港湾数据字段审计任务
  2. 海岸线类型归一化任务
  3. 50m/200m 分级格网生成器任务
  4. 港湾叠加分类器任务
  5. 港湾语义验证样本导出任务
  6. Routing 消费接口定义任务

一句话定义

本任务的目标不是“在地图上看起来像港口”，而是：

基于官方海岸线与港湾区域数据，为 NavSea 构建可用于路由判断的港湾语义分级格网。

Reference in New Issue View Git Blame Copy Permalink