# NavSea PBF v1 渲染语义契约草案

版本：Draft v1  
用途：用于 NavSea PBF 重构讨论与 Codex 实现参考

---

# 1 重构目标

NavSea 当前 PBF 渲染依赖大量旧海图编码字段，例如：

- 分類番号
- 形状分類番号
- 表示用番号
- 灯色
- 灯略記
- 明弧 / 分孤
- 表示位置

这些字段本质上是 **旧海图绘制编码**，而不是稳定的语义描述。

当前系统同时存在两种表达：

1. 旧海图渲染编码
2. 新的语义分类字段

但缺少一层专门表达 **“海图上应该如何表达该对象”** 的语义层。

因此本重构目标是建立：

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 不应继续依赖旧海图编码作为核心渲染逻辑。

正确方向是：

在 **原始属性** 与 **样式实现** 之间建立稳定的 **渲染语义层**。

该层应：

- 表达稳定语义
- 不锁定具体视觉样式
- 支持新旧样式共存
- 为检测、检索、渲染提供统一数据面