pbf/NavSea_Semantic_Pipeline.md

NavSea 语义重建流水线说明

1. 流水线概览

NavSea 当前的数据库流水线可以分成两段：

1. 上游导入段
   将原始 PBF 拆入数据库，形成 features 与 properties 两张核心表。

2. 语义重建与校验段
   在不修改现有渲染逻辑、不修改 style.json、不修改原始 PBF 结构的前提下，建立语义叠加层与校验层。

当前真实的流水线可概括为：

原始 PBF
→ PBF 导入（外部前置步骤，结果进入 features / properties）
→ 属性展开（at_attributes）
→ 语义投影（feature_semantic）
→ 对象类型候选生成（object_type_candidates）
→ 审计与统计（object_catalog / object_type_stats / style_layers / tile_density）
→ 规范对象规则（canonical_object_rules / canonical_layer_rules）
→ 语义叠加层构建（pbf_relayer_candidates）
→ 检测目录与渲染兼容层（pbf_detection_catalog / pbf_render_compatibility）
→ 语义校验（classification / geometry / render / detection / spatial）
→ 最终 NavSea 语义数据集（数据库中的已校验语义叠加结果）

需要明确一点：当前仓库中的脚本并不直接生成“新的 NavSea 矢量瓦片文件”。当前系统产出的是一套可重建、可审计、可校验的数据库语义数据集；下游若要生成新的 NavSea 矢量瓦片，应以这些表为输入继续执行后续生产步骤。

2. 分步流水线

Step 00 - 原始 PBF 导入

目的
将原始 PBF 解析并导入数据库。

输入
原始 PBF 数据

输出
features
properties

说明
这一步是当前语义流水线的前置条件。当前仓库中没有提供这一步的导入脚本，但后续所有步骤都假定这两张表已存在。

Step 01 - 提取 at 属性

目的
把 properties 表中 k='at' 的 JSON 属性展开成结构化键值表。

输入表
properties

输出表
at_attributes

脚本
navsea_audit.py

Step 02 - 构建语义投影表

目的
把原始要素与已展开的属性汇总到单要素视角，形成后续语义分析使用的基础表。

输入表
features
at_attributes

输出表
feature_semantic

字段要点
feature_id、z/x/y、vt_layer、geom_type、class_name、shape_name、layer_name

脚本
navsea_audit.py

Step 03 - 构建对象目录

目的
从 feature_semantic 聚合出对象目录，用于观察每类对象在不同来源层和几何类型上的分布。

输入表
feature_semantic

输出表
object_catalog

脚本
navsea_audit.py

Step 04 - 生成对象类型候选

目的
为每个要素生成对象类型候选，优先级为：

class_name > shape_name > vt_layer

输入表
feature_semantic

输出表
object_type_candidates

脚本
navsea_audit.py

Step 05 - 构建对象类型统计

目的
统计每个对象类型与几何类型的分布，为规则生成和几何白名单提供依据。

输入表
object_type_candidates

输出表
object_type_stats

脚本
navsea_audit.py

Step 06 - 构建样式层分析

目的
从 style.json 中抽取现有渲染层信息，并与对象候选做交叉比对，确认渲染轨仍可复用。

输入
src/pbf/style.json
object_type_candidates

输出表
style_layers
style_mapping

脚本
navsea_audit.py

Step 07 - 构建密度与基础异常分析

目的
计算瓦片密度与审计阶段的几何异常，为后续语义校验提供分析输入。

输入表
features
feature_semantic

输出表
tile_density
tile_layer_density
tile_density_top100
anomaly_navigation_geom
anomaly_reef_geom
geometry_consistency_audit

说明
geometry_consistency_audit 是审计阶段保留下来的旧版几何分布快照，不是当前正式校验表。

脚本
navsea_audit.py

Step 08 - 构建来源层规则

目的
基于现有 source_layer、样式绑定关系和语义密度，判断每个来源层属于：

semantic_layer
container_layer
style_or_source_layer

输入表
feature_semantic
style_layers

输出表
canonical_layer_rules

脚本
navsea_relayer.py

Step 09 - 构建规范对象规则

目的
为每个 canonical_object_type 固化规范对象规则，包括：

• canonical_family
• classification_basis
• source_layer_scope
• allowed_geom_types
• preferred_geom_type

输入表
object_catalog
object_type_stats

输出表
canonical_object_rules

补充输出表
object_geometry_allowlist

脚本
navsea_relayer.py

Step 10 - 构建语义叠加层

目的
在保留现有渲染轨的前提下，为每个要素附加：

• 规范对象类型
• 规范对象族
• 检测键
• 语义键
• 渲染兼容层

输入表
feature_semantic
object_type_candidates
canonical_layer_rules
canonical_object_rules

输出表
pbf_relayer_candidates

脚本
navsea_relayer.py

Step 11 - 构建语义统计与检测目录

目的
从语义叠加层生成两个下游核心视图：

1. 渲染兼容统计
   用于确认 render_layer 与原有 source_layer 的数量关系

2. 检测目录
   用于安全检测、对象检测和规则匹配

输入表
pbf_relayer_candidates

输出表
pbf_source_object_stats
pbf_render_compatibility
pbf_detection_catalog

脚本
navsea_relayer.py

Step 12 - 运行分类校验

目的
确认每个 canonical_object_type 的映射是否稳定，是否存在未知对象、歧义映射或规则冲突。

输入表
pbf_source_object_stats
canonical_object_rules

输出表
classification_validation

脚本
navsea_semantic_validation.py

Step 13 - 运行几何一致性校验

目的
确认每个规范对象的几何类型是否符合白名单与规则定义。

输入表
pbf_detection_catalog
object_geometry_allowlist

输出表
geometry_consistency

脚本
navsea_semantic_validation.py

Step 14 - 运行渲染等价校验

目的
确认语义叠加层没有破坏现有 style 渲染轨。

输入表
style_layers
features
pbf_render_compatibility

输出表
style_render_equivalence

脚本
navsea_semantic_validation.py

Step 15 - 运行检测目录完整性校验

目的
确认 detection_key 对象目录稳定且几何一致。

输入表
pbf_detection_catalog
geometry_consistency

输出表
detection_catalog_integrity

脚本
navsea_semantic_validation.py

Step 16 - 运行空间密度诊断

目的
基于 features 直接计算的瓦片密度和分 zoom 阈值，识别空间热点瓦片。

输入表
tile_density
tile_layer_density
features
pbf_relayer_candidates

输出表
spatial_anomalies

规则要点

• tile_density 只允许来自 features
• 每个 zoom 单独计算阈值
• 跳过 z=0
• 支持 DENSITY_STATISTICS_ERROR
• 每个异常 tile 单独落一行

脚本
navsea_semantic_validation.py

Step 17 - 生成总体验证结论

目的
把分类、几何、渲染、检测目录和空间诊断汇总成一条总状态。

输入表
classification_validation
geometry_consistency
style_render_equivalence
detection_catalog_integrity
spatial_anomalies

输出表
semantic_validation_summary

脚本
navsea_semantic_validation.py

3. 表依赖图

3.1 主干数据血缘

原始 PBF
  ↓
features + properties
  ↓
at_attributes
  ↓
feature_semantic
  ├─→ object_catalog
  ├─→ object_type_candidates
  │     ↓
  │   object_type_stats
  │
  └─→ style_layers ← style.json

object_catalog + object_type_stats
  ↓
canonical_object_rules
  ↓
object_geometry_allowlist

feature_semantic + style_layers
  ↓
canonical_layer_rules

feature_semantic + object_type_candidates + canonical_layer_rules + canonical_object_rules
  ↓
pbf_relayer_candidates
  ↓
pbf_source_object_stats
  ├─→ pbf_render_compatibility
  └─→ pbf_detection_catalog

3.2 并行校验血缘

pbf_source_object_stats + canonical_object_rules
  ↓
classification_validation

pbf_detection_catalog + object_geometry_allowlist
  ↓
geometry_consistency

style_layers + features + pbf_render_compatibility
  ↓
style_render_equivalence

pbf_detection_catalog + geometry_consistency
  ↓
detection_catalog_integrity

features
  ↓
tile_density + tile_layer_density
  ↓
spatial_anomalies

classification_validation
geometry_consistency
style_render_equivalence
detection_catalog_integrity
spatial_anomalies
  ↓
semantic_validation_summary

4. 表分类

下表按照当前数据库中的实际表进行分类。

表名	分类	说明
features	CORE TABLE	原始要素主表，保存 id、z/x/y、vt_layer、geom_type
properties	CORE TABLE	原始属性键值表
at_attributes	SEMANTIC TABLE	properties.k='at' 的展开结果
feature_semantic	SEMANTIC TABLE	单要素语义投影表
object_type_candidates	SEMANTIC TABLE	对象类型候选表
object_catalog	ANALYSIS TABLE	对象目录与分布分析
object_type_stats	ANALYSIS TABLE	对象类型与几何统计
style_layers	ANALYSIS TABLE	从 style.json 提取的渲染层信息
style_mapping	ANALYSIS TABLE	样式层与对象候选的交叉映射
canonical_layer_rules	SEMANTIC TABLE	来源层规则表
canonical_object_rules	SEMANTIC TABLE	规范对象规则表
object_geometry_allowlist	SEMANTIC TABLE	对象几何白名单
pbf_relayer_candidates	SEMANTIC TABLE	语义叠加主表
pbf_source_object_stats	ANALYSIS TABLE	语义叠加聚合统计表
pbf_render_compatibility	ANALYSIS TABLE	渲染兼容统计表
pbf_detection_catalog	SEMANTIC TABLE	安全检测目录表
classification_validation	VALIDATION TABLE	分类稳定性校验表
geometry_consistency	VALIDATION TABLE	当前正式几何一致性校验表
geometry_consistency_audit	ANALYSIS TABLE	审计阶段保留的旧版几何快照
style_render_equivalence	VALIDATION TABLE	渲染等价校验表
detection_catalog_integrity	VALIDATION TABLE	检测目录完整性校验表
spatial_anomalies	VALIDATION TABLE	空间密度异常表
semantic_validation_summary	VALIDATION TABLE	整体验证摘要
tile_density	ANALYSIS TABLE	每瓦片 feature 数量
tile_layer_density	ANALYSIS TABLE	每瓦片、每来源层 feature 数量
tile_density_top100	ANALYSIS TABLE	最高密度瓦片 Top100
anomaly_navigation_geom	ANALYSIS TABLE	航标类几何异常审计
anomaly_reef_geom	ANALYSIS TABLE	鱼礁类几何异常审计
feature_flat	TEMP TABLE	当前数据库中的遗留/临时表，不在现行语义脚本主路径上

5. 官方执行顺序

当前建议的正式执行顺序如下：

1. 导入原始 PBF，生成 features 和 properties
2. 运行 navsea_audit.py，构建基础语义表、分析表和密度表
3. 运行 navsea_relayer.py，生成规范规则与语义叠加层
4. 运行 navsea_semantic_validation.py，生成分类、几何、渲染、检测目录和空间校验结果
5. 读取 semantic_validation_summary 确认总体状态
6. 以 pbf_relayer_candidates 为主表，结合 features、properties、at_attributes 产出下游 NavSea 数据集或矢量瓦片生产输入

6. 执行命令

6.1 构建基础语义与分析表

.venv/bin/python navsea_audit.py

作用
从 features / properties 出发，构建：

• at_attributes
• feature_semantic
• object_catalog
• geometry_consistency_audit
• object_type_candidates
• object_type_stats
• style_layers
• style_mapping
• tile_density
• tile_layer_density
• tile_density_top100
• 审计异常表

6.2 构建语义叠加层

.venv/bin/python navsea_relayer.py

作用
生成：

• canonical_layer_rules
• canonical_object_rules
• object_geometry_allowlist
• pbf_relayer_candidates
• pbf_source_object_stats
• pbf_render_compatibility
• pbf_detection_catalog

6.3 运行语义校验

.venv/bin/python navsea_semantic_validation.py

作用
生成：

• classification_validation
• geometry_consistency
• style_render_equivalence
• detection_catalog_integrity
• spatial_anomalies
• semantic_validation_summary

6.4 仅重建密度表

如果只需要更新空间密度与热点诊断，可以单独执行：

.venv/bin/python - <<'PY'
from navsea_audit import NavSeaAudit, DbConfig
NavSeaAudit(DbConfig()).build_tile_density()
PY

随后再执行：

.venv/bin/python navsea_semantic_validation.py

7. 最终输出数据集

7.1 当前系统中的“最终语义数据集”

当前系统中，最接近“最终 NavSea 语义要素表”的主表是：

pbf_relayer_candidates

它保存了：

• feature_id
• z/x/y
• source_layer
• geom_type
• class_name
• shape_name
• layer_name
• object_type_source
• canonical_object_type
• semantic_granularity
• canonical_family
• classification_basis
• source_layer_scope
• semantic_key
• detection_key
• render_layer

7.2 原始属性与语义属性的对应关系

pbf_relayer_candidates 本身并不保存原始全部属性值，因此最终语义数据集应按下述方式理解：

• 原始要素主键与瓦片定位来自 features
• 原始属性全集来自 properties
• 展开的 at 属性来自 at_attributes
• 语义投影属性来自 feature_semantic
• 规范对象分类来自 pbf_relayer_candidates

也就是说，当前 NavSea 最终语义数据集实际上是一个“主表 + 关联表”结构：

主表：
  pbf_relayer_candidates

关联恢复：
  features        → 原始要素标识、瓦片坐标、几何类型
  properties      → 原始属性键值
  at_attributes   → 展开的 at 属性
  feature_semantic → class_name / shape_name / layer_name

7.3 关于 geometry 的说明

当前数据库 schema 中，features 表仅保存：

• id
• z/x/y
• vt_layer
• geom_type

它不保存完整坐标几何体字段。
因此，当前数据库中的“最终语义数据集”是面向语义重建、校验和下游生成的语义索引层，而不是一张带完整坐标几何的空间实体表。

7.4 下游生成 NavSea 数据的推荐入口

如果后续要生成 NavSea 下游数据或重新生成矢量瓦片，推荐以：

• pbf_relayer_candidates 作为语义主表
• features 作为原始要素锚点
• properties / at_attributes 作为原始属性源

共同构成生产输入。

8. 从零重建步骤

最小可复现步骤

1. 将原始 PBF 导入数据库，得到 features 与 properties
2. 执行 navsea_audit.py
3. 执行 navsea_relayer.py
4. 执行 navsea_semantic_validation.py
5. 检查 semantic_validation_summary
6. 若需要下游数据生产，则从 pbf_relayer_candidates 联合 features、properties、at_attributes 提取最终数据集

推荐的重建命令顺序

.venv/bin/python navsea_audit.py
.venv/bin/python navsea_relayer.py
.venv/bin/python navsea_semantic_validation.py

重建完成后的关键检查点

至少应检查以下表是否已刷新：

• feature_semantic
• object_type_candidates
• canonical_object_rules
• canonical_layer_rules
• pbf_relayer_candidates
• pbf_detection_catalog
• classification_validation
• geometry_consistency
• style_render_equivalence
• detection_catalog_integrity
• spatial_anomalies
• semantic_validation_summary

当前系统的审计终点

当前系统的“可审计终点”不是一个新的矢量瓦片文件，而是：

• 一套可复现的语义规则表
• 一套可复现的语义叠加主表
• 一套可重复执行的验证表

即：

canonical_layer_rules
canonical_object_rules
pbf_relayer_candidates
pbf_detection_catalog
semantic_validation_summary

这套终点定义了 NavSea 当前语义流水线的正式数据库输出。