pbf/tasks/pbf/NavSea_tile_generation_pipeline_v2.md

NavSea Tile Generation Pipeline v2

版本：v2 Draft
用途：定义 NavSea 从原始海图数据到交付 Vector Tile 的生产流程和质量要求。

1 目标

v2 pipeline 不是简单“改字段名”，而是把交付链路明确拆成：

原始数据 -> 语义分类 -> 渲染语义 -> 字段物化 -> PBF 交付 -> 样式渲染

同时满足：

• 旧内容兼容
• 新样式迁移
• 检索和碰撞可用
• 工程可验证

2 输入

2.1 原始输入

• 原始 Vector Tile：/home/wwwroot/newpec/exported_auto/tile.mapple-on.jp__newpec-mvt-20260106__z___x___y_.pbf/tiles
• 原始要素属性：包括 fid、分類番号、形状分類番号、表示用番号、名称、灯色 等

2.2 数据库输入

当前数据库中已具备或部分具备：

• taxonomy 归类结果
• render_layer 归并结果
• detection 分类结果

现有 builder 查询表：

• pbf_relayer_candidates
• properties

3 输出类型

建议把输出分成两类：

3.1 delivery tiles

用途：

• 正式渲染
• 检索
• 碰撞检测

要求：

• 保留关键旧字段
• 输出稳定 taxonomy 字段
• 输出新的 render_semantics 字段
• 不包含过量调试字段

3.2 engineering tiles

用途：

• 抽样校验
• 问题定位
• 新旧比对

要求：

• 可保留更完整的原始字段
• 可保留更多校验字段

4 v2 标准流程

步骤 1：读取原始瓦片

按 z/x/y 读取原始 .pbf，解码所有 source layer。

要求：

• 保留每个 source layer 的原始 extent
• 不改变 feature geometry

步骤 2：按 fid/source_layer/geom_type 关联数据库记录

建议匹配键：

• fid
• source_layer
• geom_type

目的：

• 将原始 feature 与数据库里的 taxonomy / detection / render_layer 结果稳定关联

步骤 3：taxonomy 物化

输出：

• canonical_family
• canonical_object_type
• detection_key
• semantic_key（可选）

要求：

• 未命中 taxonomy 的对象要进入 fallback 分类
• 不允许静默输出空语义

步骤 4：render mapping 物化

依据：

• canonical_object_type
• 几何类型
• 必要旧字段

输出：

• chart_render_type
• chart_symbol_family
• chart_symbol_code
• chart_line_style
• chart_fill_style
• chart_text_style
• chart_priority
• chart_visibility_min
• chart_visibility_max

步骤 5：label / light / numeric 归一化

输出：

• chart_label_text
• chart_label_subtext
• light_color_code
• light_character_code
• depth_value_m
• clearance_height_m
• least_depth_m
• bearing_deg

要求：

• 同类对象统一字段命名
• 尽量避免样式和检索继续直接解析原始文本字段

步骤 6：决定输出 layer

建议优先级：

1. 使用数据库已确定的 render_layer
2. 若无 render_layer，按渲染语义计算默认层
3. 再不行才回退原 source_layer

说明：

• v2 的长期方向是减少直接依赖旧 source layer 命名
• 但过渡期允许回退，保证旧 style 不崩

步骤 7：编码输出 PBF

要求：

• 保持原 feature geometry 不变
• 保持原 layer extent 不变
• 输出写入目标目录 /home/wwwroot/pbf/{z}/{x}/{y}.pbf

5 质量门禁

v2 pipeline 必须增加明确的 QA 检查。

5.1 文件层检查

• 新旧目标区域 z/x/y.pbf 文件名集合一致
• 瓦片数一致
• 输出层级目录完整

5.2 几何层检查

• 抽样瓦片 extent 一致
• 抽样 feature 数量不异常缩水
• 几何类型不发生意外变化

5.3 属性层检查

• fid 保留
• taxonomy 字段不为空
• 核心 render 字段存在
• 关键旧字段未被错误清洗

5.4 渲染层检查

至少验证以下对象在新样式或兼容样式中可正常显示：

• 灯标体系
• 危险物体系
• 鱼礁/鱼业区
• 水深区和等深线
• 基本线 / 危险界 / 航路境界
• 海上地名 / 陆上地名

6 与当前实现的差距

当前 navsea_tile_builder.py 已经完成：

• 原始瓦片读取
• 数据库关联
• taxonomy 字段叠加
• render_layer 重分层
• 原始 extent 保持

当前还缺：

• 统一的 render mapping 物化
• label/light/numeric 归一化
• delivery 与 engineering 两种输出口径
• 更系统的 QA 报告

7 v2 推荐实施顺序

阶段 1：不破坏现有交付

• 保持当前 builder 可用
• 在 builder 中新增 chart_* 字段，不删旧字段

阶段 2：构建混合样式

• 新样式优先读取 chart_*
• 旧字段仅用于灯标细节、危险物图案和少数特例

阶段 3：建立 QA 报表

• 每次构建输出 coverage / feature count / extent 抽样报告
• 对 taxonomy 未命中项输出清单

阶段 4：精简交付字段

• 在新样式和检索稳定后，逐步减少无用旧字段
• 但保留 fid、taxonomy 和关键兼容字段

8 v2 验收标准

一版合格的 v2 delivery tiles 至少应满足：

• 与原始目标区域瓦片文件集合一致
• 抽样瓦片 extent 正确
• 主要对象类型 taxonomy 完整
• chart_* 核心字段可用于新样式
• 旧兼容样式仍可显示关键对象
• 检索和碰撞可通过 fid + taxonomy + normalized_numeric 使用