230 lines
11 KiB
Markdown
230 lines
11 KiB
Markdown
# NavSea CM95 接入规范
|
||
|
||
版本：`v1`
|
||
状态：首版实施规范
|
||
用途：定义将具备合法使用授权的 CM95 海图数据转换为 PBF，并直接接入现有 NavSea Full semantic style 的数据契约、实施顺序和验收门禁。
|
||
|
||
## 1. 结论
|
||
|
||
CM95 必须向 NavSea 的既有 PBF 契约靠齐；不为 CM95 重写一套海图 style，也不允许把 CM95 原始对象类别直接暴露给前端 style。
|
||
|
||
当前接入基线为：
|
||
|
||
- style：[`src/pbf/style.navsea-delivery-full-semantic-unified-20260808.json`](/root/sourceserver/pbf/src/pbf/style.navsea-delivery-full-semantic-unified-20260808.json)
|
||
- sprite：`http://192.168.200.184/newpec/sprite-semantic-unified-20260808/sprite`
|
||
- glyphs：`http://192.168.200.184/newpec/fonts/{fontstack}/{range}.pbf`
|
||
|
||
CM95 转换产物必须满足该 style 的 `source-layer`、字段和值域要求。满足后，新 style 只需复制基线文件并修改 `sources.navsea_delivery.tiles` 的瓦片地址。
|
||
|
||
## 2. 边界与前提
|
||
|
||
- 仅处理已获授权解码、转换、缓存和部署的 CM95 数据。
|
||
- CM95 解码器不属于本仓库交付物；本规范的输入是已经合法导出的矢量要素及其属性。
|
||
- 转换过程不得篡改海图几何、深度、净空、航标与危险物的原始业务含义。
|
||
- 所有要素必须有稳定的上游对象身份；若 CM95 未提供全局稳定 ID，必须由“数据集版本 + 原始 cell/record ID + 几何类型”生成可复现的 `source_id`。
|
||
- 第一版只追求“复用当前 style 并可审计”，不以压缩字段或全国一次性全量生产为目标。
|
||
|
||
## 3. 目标架构
|
||
|
||
```text
|
||
CM95 合法导出数据
|
||
-> CM95 解析与原始对象归档
|
||
-> CM95→NavSea 语义/渲染映射
|
||
-> NavSea 兼容要素集
|
||
-> Web Mercator MVT/PBF
|
||
-> 现有 NavSea Full semantic style
|
||
```
|
||
|
||
其中“CM95→NavSea 语义/渲染映射”是唯一允许理解 CM95 原始类别与属性差异的层。MVT 和 style 只消费 NavSea 的标准图层与字段。
|
||
|
||
## 4. 固定图层契约
|
||
|
||
第一版 PBF 的图层名称必须与当前 style 完全一致。不得随意以 CM95 对象名作为图层名。
|
||
|
||
| 业务类别 | 目标 `source-layer` |
|
||
| --- | --- |
|
||
| 海域底色、水深区 | `baseline_area`、`depth_zone_739`、`depth_zone_741` |
|
||
| 海岸、陆地与岸线 | `land_area`、`baseline_line`、`baseline_outline` |
|
||
| 等深线与测深文字 | `depth_contour`、`bathymetry_line`、`seabed_text_point` |
|
||
| 航标、灯塔、浮标、灯弧 | `navigation_marks` |
|
||
| 航行危险物 | `navigation_hazard_point`、`navigation_hazard_area`、`navigation_hazard_outline` |
|
||
| 锚泊及锚泊注意 | `anchorage_point`、`anchorage_area`、`anchorage_outline`、`anchor_caution_hazard_point`、`anchor_caution_hazard_area`、`anchor_caution_hazard_outline` |
|
||
| 渔具与渔业禁限 | `fixed_fishing_gear_area` |
|
||
| 设施、桥梁、净空 | `facility_boundary_point`、`facility_boundary_area`、`facility_boundary_outline`、`bridge_structure`、`clearance_limit_point`、`clearance_limit_line` |
|
||
| 地名和陆上设施 | `place_label_sea`、`place_label_land`、`onshore_structure_point`、`onshore_structure_line`、`onshore_structure_area` |
|
||
| 其他已由 style 消费的图层 | `pilot_station_point`、`seabed_line`、`submerged_reef_area`、`hazard_boundary_outline`、`hole_area`、`clip_outline_754` |
|
||
|
||
未能映射到上述图层的 CM95 对象不得静默丢弃：应写入工程版的 `cm95_unmapped` 隔离层并生成映射缺口报告；该隔离层不进入正式 style。
|
||
|
||
## 5. 字段契约
|
||
|
||
### 5.1 每个已交付要素必须有的字段
|
||
|
||
| 字段 | 要求 |
|
||
| --- | --- |
|
||
| `fid` | NavSea 稳定、可复现的对象标识；不能使用每次构建都会变化的临时序号。 |
|
||
| `canonical_family` | NavSea 大类语义。 |
|
||
| `canonical_object_type` | NavSea 细粒度对象类型。 |
|
||
| `render_layer` | 与实际 `source-layer` 相同的目标渲染层。 |
|
||
| `chart_render_type` | `fill`、`line`、`symbol`、`label` 或 `none`。 |
|
||
| `chart_priority` | 绘制/碰撞优先级。 |
|
||
| `source_id` | 可回查 CM95 上游对象的稳定标识；工程版必留，交付版建议保留。 |
|
||
| `source_dataset_id` | CM95 数据集、cell 或版本标识；工程版必留。 |
|
||
|
||
### 5.2 当前 style 的直接渲染字段
|
||
|
||
按对象类型填写以下字段，未适用字段可缺省，但不得以伪造值替代：
|
||
|
||
| 对象类别 | 必要或高优先级字段 |
|
||
| --- | --- |
|
||
| 面与水深区 | `chart_fill_style`、`chart_fill_pattern` |
|
||
| 线 | `chart_line_color`、`chart_line_width`、`chart_line_pattern` |
|
||
| 图标 | `chart_icon_image`、`chart_symbol_code`、`class_code`、`display_code`、`shape_class_code` |
|
||
| 文字 | `chart_label_text`、`chart_label_subtext`、`chart_text_style`、`chart_text_color`、`chart_label_position_code` |
|
||
| 灯标 | `light_color_code`、`chart_label_subtext`；有弧段时还需 `arc_id` 与可追溯的原始弧段编码。 |
|
||
|
||
`chart_icon_image`、`chart_fill_pattern` 和 `arc_id` 的取值必须是当前 semantic sprite 中真实存在的键。不得写入旧 `symbol-daytime-*`、`fill-daytime-*` 或未经 sprite 审计的新键。
|
||
|
||
### 5.3 CM95 原始属性保留
|
||
|
||
CM95 的原始属性不得直接成为 style 的长期依赖，但工程版必须保留以下可追溯信息：
|
||
|
||
- CM95 对象类别/OBJL；
|
||
- 原始对象 ID、cell/数据集 ID、更新时间或版本；
|
||
- 原始属性全集或其不可逆裁剪前的外部 trace；
|
||
- 原始几何类型；
|
||
- 映射规则 ID 与映射版本。
|
||
|
||
交付版可裁掉详细 trace，但必须能凭 `fid` 在工程索引中回查到上述信息。
|
||
|
||
## 6. CM95 映射实施方式
|
||
|
||
建立一个版本化映射表，例如 `tasks/pbf/mappings/cm95_to_navsea_v1.yaml`。每条规则至少包含：
|
||
|
||
- `cm95_object_class`：CM95 原始对象类别；
|
||
- `geometry_type`：点、线、面；
|
||
- `condition`：属性条件；
|
||
- `target_source_layer`：本规范第 4 节中的目标层；
|
||
- `canonical_family`、`canonical_object_type`；
|
||
- `style_fields`：需物化的 `chart_*`、灯标、文字或数值字段；
|
||
- `rule_id`、`mapping_version`；
|
||
- `safety_class`：`hard_gate`、`important` 或 `normal`。
|
||
|
||
映射优先级如下：
|
||
|
||
1. 航标、灯火、浮标、灯弧；
|
||
2. 暗礁、沉船、障碍物、浅水、干出与露出对象；
|
||
3. 水深区、等深线、测深与净空；
|
||
4. 海陆边界、陆地、航道、锚地、限制区、渔具；
|
||
5. 设施、地名和一般说明。
|
||
|
||
同一 CM95 类别因属性不同而表现不同，必须拆成多条显式规则；不能只按对象类别做一对一映射。
|
||
|
||
## 7. PBF 生成规则
|
||
|
||
- 统一投影为 EPSG:3857，使用 XYZ `z/x/y` 切片。
|
||
- MVT extent 固定为 `4096`，同一目标图层内保持一致。
|
||
- 首版目标 zoom 为 `0–12`；小范围试产可先产出覆盖 AOI 的 `z8–12`。
|
||
- 面、线裁切须带足够 buffer，避免瓦片边缘断裂；点不得因边界判断被重复删除。
|
||
- 保持原始几何类型；不得将面危险物降级为点，或把线界线误转为面。
|
||
- 同一 `fid` 在不同 zoom/tile 的实例可重复出现，但其身份和核心语义必须一致。
|
||
- 构建时输出工程版 PBF、交付版 PBF、映射缺口 JSON/Markdown 和 `fid -> source_id` 审计索引。
|
||
|
||
## 8. Style 接入方式
|
||
|
||
以当前基线 style 复制一个 CM95 部署版本。首版只允许修改以下内容：
|
||
|
||
```json
|
||
{
|
||
"name": "NavSea CM95 <区域> <版本>",
|
||
"sources": {
|
||
"navsea_delivery": {
|
||
"tiles": ["https://<host>/pbf-cm95-<区域>-<版本>/{z}/{x}/{y}.pbf"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
保持不变：
|
||
|
||
- 全部 layer ID、顺序、filter 和 paint/layout；
|
||
- semantic sprite URL；
|
||
- glyph URL；
|
||
- 外部 tide 与底图 source。
|
||
|
||
若某一类 CM95 数据无法命中现有 style，优先补充映射字段或 sprite 映射；只有确认现有 style 无法表达且完成专项审计后，才允许新增 style layer。
|
||
|
||
## 9. 分阶段交付
|
||
|
||
### 阶段 A：单 AOI 可视化样本
|
||
|
||
- 选择一个含陆地、水深、航标和危险物的港口或近岸 AOI。
|
||
- 导出 CM95 原始对象清单及 `source_id`。
|
||
- 完成第 6 节映射表的最小覆盖。
|
||
- 生成 z8–12 PBF，使用只改 tile URL 的 style 打开。
|
||
|
||
通过条件：底图、水深、等深线、陆地、主要航标和危险物均可显示，且无大面积空白或错误覆盖。
|
||
|
||
### 阶段 B：安全对象闭环
|
||
|
||
- 补齐所有 `hard_gate` 对象的分类、图层和符号字段。
|
||
- 灯火必须同时验证灯色、略记和灯弧（如原始数据提供）。
|
||
- 危险物必须验证水上/水下/露出/干出语义不会画反。
|
||
|
||
通过条件：对象保全审计的安全对象缺失数为 `0`，关键图标/文字/symbol sprite 缺失数为 `0`。
|
||
|
||
### 阶段 C：区域扩展与发布
|
||
|
||
- 扩展至完整目标海域及 z0–12。
|
||
- 收敛未映射对象；剩余对象须有明确的隔离理由和风险结论。
|
||
- 生成正式交付版及可回查工程索引。
|
||
|
||
## 10. 必须执行的审计顺序
|
||
|
||
按项目正式口径执行，不能以视觉相似替代对象保全：
|
||
|
||
1. **对象保全审计**：以 `source_id + source_dataset_id + geometry_type` 回对 CM95 原始导出与 PBF；检查缺失、错误重分层、错误合并、身份丢失。
|
||
2. **渲染审计**：扫描 PBF 字段、style 命中和 sprite 资源；检查关键对象是否获得有效 fill、line、icon、text。
|
||
3. **AOI 视觉审计**：在固定中心点和 zoom 检查叠压、边缘裁切、标签、海陆关系与安全感知。
|
||
|
||
CM95 没有“旧 NavSea PBF”可作为对象基准时，CM95 原始导出数据就是第一层审计的基准；不可跳过这一层。
|
||
|
||
## 11. 硬门禁
|
||
|
||
以下任一项不通过，CM95 PBF 不得切换到正式 URL：
|
||
|
||
- `hard_gate` 对象存在缺失、身份不可回查或错误图层；
|
||
- `chart_icon_image`、`chart_fill_pattern`、`arc_id` 引用不存在的 sprite 键；
|
||
- 深度、净空、危险物或灯火发生单位错误、正负号错误或水上/水下语义反转；
|
||
- PBF 投影、extent、坐标轴或 tile y 方向错误；
|
||
- style 实际加载的 tile URL 不是候选 CM95 PBF；
|
||
- 映射缺口被静默丢弃；
|
||
- 未完成针对目标 AOI 的人工视觉复核。
|
||
|
||
## 12. 首次实施的输入与产出
|
||
|
||
开始实施前需要提供：
|
||
|
||
- 一个合法导出的 CM95 AOI 样本；
|
||
- 导出格式和字段/对象类别字典；
|
||
- 数据集版本、坐标参考和深度/高度单位说明；
|
||
- 目标海域、目标 zoom、部署 PBF URL；
|
||
- 至少一个包含航标、危险物、水深区和陆地的验收 AOI。
|
||
|
||
首次实施完成时必须交付：
|
||
|
||
- `cm95_to_navsea_v1.yaml` 映射表；
|
||
- CM95→NavSea 转换脚本；
|
||
- 工程版与交付版 PBF；
|
||
- 映射缺口报告、对象保全报告、sprite 闭合报告和 AOI 审计报告；
|
||
- 仅替换瓦片 URL 的 CM95 style 文件。
|
||
|
||
## 13. 与既有文档的关系
|
||
|
||
- 本规范定义 CM95 作为新上游数据源时如何接入；
|
||
- [NavSea PBF Schema v2](tasks/pbf/NavSea_PBF_schema_v2.md) 定义通用 PBF 字段方向；
|
||
- [NavSea Tile Generation Pipeline v2](tasks/pbf/NavSea_tile_generation_pipeline_v2.md) 定义既有原始 PBF→交付 PBF 流程；
|
||
- [NavSea 交付前审计规范](NavSea_Delivery_Preflight_Audit_Spec.md) 定义正式交付审计门禁。
|
||
|
||
出现冲突时，以安全对象不丢失、可回查和当前 style 实际字段契约为最高优先级。
|