678 lines
16 KiB
Markdown
678 lines
16 KiB
Markdown
# 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 当前语义流水线的正式数据库输出。
|