Initial import of NavSea pbf project

2026-03-17 19:48:15 +08:00
commit 5f3f7409b3
84 changed files with 43889 additions and 0 deletions
--- a/NavSea_Semantic_Pipeline.md
+++ b/NavSea_Semantic_Pipeline.md
@@ -0,0 +1,677 @@
+# NavSea 语义重建流水线说明
+
+## 1. 流水线概览
+
+NavSea 当前的数据库流水线可以分成两段：
+
+1. 上游导入段  
+   将原始 PBF 拆入数据库，形成 `features` 与 `properties` 两张核心表。
+
+2. 语义重建与校验段  
+   在不修改现有渲染逻辑、不修改 `style.json`、不修改原始 PBF 结构的前提下，建立语义叠加层与校验层。
+
+当前真实的流水线可概括为：
+
+```text
+原始 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 - 生成对象类型候选
+
+目的  
+为每个要素生成对象类型候选，优先级为：
+
+```text
+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`、样式绑定关系和语义密度，判断每个来源层属于：
+
+```text
+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 主干数据血缘
+
+```text
+原始 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 并行校验血缘
+
+```text
+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 构建基础语义与分析表
+
+```bash
+.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 构建语义叠加层
+
+```bash
+.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 运行语义校验
+
+```bash
+.venv/bin/python navsea_semantic_validation.py
+```
+
+作用  
+生成：
+
+- `classification_validation`
+- `geometry_consistency`
+- `style_render_equivalence`
+- `detection_catalog_integrity`
+- `spatial_anomalies`
+- `semantic_validation_summary`
+
+### 6.4 仅重建密度表
+
+如果只需要更新空间密度与热点诊断，可以单独执行：
+
+```bash
+.venv/bin/python - <<'PY'
+from navsea_audit import NavSeaAudit, DbConfig
+NavSeaAudit(DbConfig()).build_tile_density()
+PY
+```
+
+随后再执行：
+
+```bash
+.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 最终语义数据集实际上是一个“主表 + 关联表”结构：
+
+```text
+主表：
+  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` 提取最终数据集
+
+### 推荐的重建命令顺序
+
+```bash
+.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`
+
+### 当前系统的审计终点
+
+当前系统的“可审计终点”不是一个新的矢量瓦片文件，而是：
+
+- 一套可复现的语义规则表
+- 一套可复现的语义叠加主表
+- 一套可重复执行的验证表
+
+即：
+
+```text
+canonical_layer_rules
+canonical_object_rules
+pbf_relayer_candidates
+pbf_detection_catalog
+semantic_validation_summary
+```
+
+这套终点定义了 NavSea 当前语义流水线的正式数据库输出。