5.1 KiB
NavSea PBF v1 渲染语义契约草案
版本：Draft v1
用途：用于 NavSea PBF 重构讨论与 Codex 实现参考
1 重构目标
NavSea 当前 PBF 渲染依赖大量旧海图编码字段，例如：
- 分類番号
- 形状分類番号
- 表示用番号
- 灯色
- 灯略記
- 明弧 / 分孤
- 表示位置
这些字段本质上是 旧海图绘制编码，而不是稳定的语义描述。
当前系统同时存在两种表达：
- 旧海图渲染编码
- 新的语义分类字段
但缺少一层专门表达 “海图上应该如何表达该对象” 的语义层。
因此本重构目标是建立：
NavSea PBF 的稳定 渲染语义契约层。
2 三层模型
NavSea 渲染体系应拆分为三层：
A 层：对象语义层
回答：
这个对象是什么
示例字段：
- canonical_object_type
- canonical_family
- detection_key
示例值：
- 港湾灯台
- 暗岩
- 魚礁
- 港則法境界
B 层：渲染语义层
回答：
在海图上应该如何表达
示例字段：
- chart_render_type
- chart_symbol_family
- chart_symbol_code
- chart_priority
- chart_visibility_min
- chart_visibility_max
C 层：样式实现层
由 MapLibre Style 决定：
- 颜色
- 线型
- 图标
- 填充
- 文字样式
样式层应尽量只依赖：
- chart_* 渲染语义字段
- 少量 legacy 字段
3 建议的核心渲染字段
3.1 主渲染字段
| 字段 | 类型 | 说明 |
|---|---|---|
| chart_render_type | string | symbol / line / fill / label / none |
| chart_symbol_family | string | 符号族 |
| chart_symbol_code | string | 符号代码 |
| chart_priority | integer | 渲染优先级 |
| chart_visibility_min | integer | 最小显示 zoom |
| chart_visibility_max | integer | 最大显示 zoom |
3.2 标签字段
| 字段 | 类型 |
|---|---|
| chart_label_text | string |
| chart_label_subtext | string |
| chart_label_anchor | string |
| chart_label_dx | number |
| chart_label_dy | number |
3.3 灯标字段
| 字段 | 类型 |
|---|---|
| light_color_code | string |
| light_character_code | string |
| light_sector_mode | string |
| light_arc_code | string |
示例： light_color_code = white light_character_code = Fl light_sector_mode = sector
3.4 危险物字段
| 字段 | 类型 |
|---|---|
| hazard_class | string |
| hazard_severity | string |
hazard_class 示例：
- rock
- reef
- wreck
- obstruction
- shoal
hazard_severity 示例：
- critical
- major
- minor
- context
3.5 区域字段
| 字段 | 类型 |
|---|---|
| area_usage_class | string |
示例：
- anchorage
- route
- fishery
- restricted
- facility
- land
- water
4 不建议直接写入 PBF 的字段
以下字段如果直接写入 PBF，可能会锁死样式：
- chart_line_style
- chart_fill_style
- chart_text_style
原因：
这些字段已经接近 样式预设名称，而不是语义。
例如： depth_zone_0_5 boundary_dashed place_name
未来若更换视觉风格，会产生耦合。
因此建议 PBF 只表达：
- line semantic
- fill semantic
- label role
具体视觉样式交由 Style 决定。
5 建议保留的 legacy 字段
为了兼容旧样式与历史数据，建议继续保留： 分類番号 形状分類番号 表示用番号 灯色 灯略記 明弧 分孤 表示位置 名称 名称補助 日本語地名 英文字地名
用途：
- 样式兜底
- 检索
- 历史兼容
6 Feature 示例
灯台
{ "fid": 12345678, "canonical_object_type": "港湾灯台", "canonical_family": "navigation_aid", "detection_key": "symbol:港湾灯台",
"chart_render_type": "symbol", "chart_symbol_family": "navigation_light", "chart_symbol_code": "lighthouse",
"chart_priority": 900, "chart_visibility_min": 7,
"chart_label_text": "鷹島灯台", "chart_label_subtext": "Fl W 5s",
"light_color_code": "white", "light_character_code": "Fl" }## 鱼礁危险区 { "fid": 23456789, "canonical_object_type": "魚礁", "canonical_family": "hazard", "detection_key": "mixed:魚礁",
"chart_render_type": "fill", "chart_symbol_family": "hazard", "chart_symbol_code": "reef_area",
"hazard_class": "reef", "hazard_severity": "major",
"chart_priority": 850 }
7 建议的实现顺序
阶段 1：
出瓦片流程新增 chart_* 字段。
阶段 2：
PBF 同时包含：
- 新 taxonomy 字段
- 新 chart semantics
- legacy 字段
阶段 3：
样式优先读取： chart_render_type chart_symbol_family chart_symbol_code
缺失时回退 legacy 字段。
阶段 4：
逐步减少样式对 legacy 编码依赖。
8 第一阶段优先实现对象
建议优先完成四类对象：
1 灯标 / 航标
2 危险点对象
3 危险面对象（鱼礁 / 礁盘 / 障碍区）
4 边界对象
原因：
这些对象最依赖旧编码，也是最复杂的渲染类型。
9 结论
NavSea PBF 不应继续依赖旧海图编码作为核心渲染逻辑。
正确方向是：
在 原始属性 与 样式实现 之间建立稳定的 渲染语义层。
该层应：
- 表达稳定语义
- 不锁定具体视觉样式
- 支持新旧样式共存
- 为检测、检索、渲染提供统一数据面