# 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` 使用
