# NavSea 渲染语义重构报告

## 1 目标

本报告提出一套更清晰的 NavSea PBF 交付渲染描述体系。

这次重构的目标，不是立刻移除旧的海图渲染体系，而是把下面三件事情拆开：

- 对象本身的语义
- 海图渲染意图
- 最终样式实现

这样 NavSea 才能同时支持：

- 兼容旧海图风格的渲染
- 更清晰、可维护的样式逻辑
- 碰撞检测、检索与语义分析
- 逐步摆脱对原始旧海图编码的强依赖

## 2 当前问题

当前渲染栈把多种职责混在了一起。

### 2.1 当前渲染依赖的输入

旧版渲染主要依赖这些字段：

- `分類番号`
- `形状分類番号`
- `表示用番号`
- `灯色`
- `灯略記`
- `明弧/分孤`
- `表示位置`
- `名称`
- 展开的 `at` 属性

这些字段当然有用，但它们的问题也很明显：它们直接承载的是“海图怎么画”的细节编码，而不是清晰、稳定的渲染语义，因此维护成本高、理解成本高、迁移成本也高。

### 2.2 当前已经叠加的新语义

新 `pbf` 已经增加了这些语义字段：

- `canonical_object_type`
- `canonical_family`
- `semantic_key`
- `detection_key`
- `render_layer`

这些字段已经能很好地服务于检测和分类，但还不足以完整替代海图渲染所需的细粒度表达。

### 2.3 当前的核心缺口

现在的数据层同时存在两套东西：

- 面向海图绘制细节的旧编码
- 面向系统理解的语义分类

但缺少一层专门回答“应该怎么画”的渲染语义层。也就是目前还没有一套稳定字段，明确回答这些问题：

- 该使用哪一类符号族
- 该按点、线、面还是文字渲染
- 该显示什么文本
- 渲染优先级是什么
- 应该选用哪一种线型、面型或符号变体

## 3 建议的三层模型

NavSea 的渲染体系建议拆成三层。

### 3.1 A 层：对象语义层

这一层回答“这是什么对象”。

代表字段：

- `canonical_object_type`
- `canonical_family`
- `detection_key`

示例：

- `暗岩`
- `魚礁`
- `港湾灯台`
- `港則法による境界`

### 3.2 B 层：渲染语义层

这一层回答“这个对象在海图上应该怎么画”。

这是本报告建议新增的核心层。

代表字段：

- `chart_render_type`
- `chart_symbol_family`
- `chart_symbol_code`
- `chart_line_style`
- `chart_fill_style`
- `chart_label_text`
- `chart_label_subtext`
- `chart_label_anchor`
- `chart_priority`

### 3.3 C 层：样式层

MapLibre 样式层尽量只消费“渲染语义层”以及少量保留的原始字段。

这样可以让样式规则明显缩短，也更容易维护和演进。

## 4 建议新增的渲染字段

建议在新的交付 `pbf` 中补充如下字段。

### 4.1 核心渲染字段

| 字段 | 类型 | 用途 |
| --- | --- | --- |
| `chart_render_type` | string | 主渲染类型：`symbol`、`line`、`fill`、`label`、`none` |
| `chart_symbol_family` | string | 符号族，例如 `navigation_light`、`buoy`、`beacon`、`hazard`、`facility`、`depth_mark` |
| `chart_symbol_code` | string | 稳定的符号编码，例如 `lighthouse`、`rock_awash`、`anchorage_mark` |
| `chart_line_style` | string | 稳定的线型预设，例如 `boundary_dashed`、`contour_minor`、`subsea_cable` |
| `chart_fill_style` | string | 稳定的填充预设，例如 `depth_zone_0_5`、`fishery_area`、`hazard_area` |
| `chart_priority` | integer | 绘制优先级，用于排序和碰撞决策 |
| `chart_visibility_min` | integer | 最小显示缩放级别 |
| `chart_visibility_max` | integer | 最大显示缩放级别 |

### 4.2 标注字段

| 字段 | 类型 | 用途 |
| --- | --- | --- |
| `chart_label_text` | string | 主标注文本 |
| `chart_label_subtext` | string | 次级标注，例如辅助说明或灯略记 |
| `chart_label_anchor` | string | 标准化锚点，例如 `top`、`bottom`、`left`、`right`、`center` |
| `chart_label_dx` | number | 文本 X 方向偏移 |
| `chart_label_dy` | number | 文本 Y 方向偏移 |
| `chart_text_style` | string | 文字样式预设，例如 `place_name`、`light_name`、`depth_text` |

### 4.3 灯标专项字段

| 字段 | 类型 | 用途 |
| --- | --- | --- |
| `light_color_code` | string | 归一化后的灯色，例如 `white`、`red`、`green`、`yellow`、`mixed` |
| `light_character_code` | string | 归一化后的灯质，例如 `Fl`、`Oc`、`Iso`、`F`、`V-AIS` |
| `light_arc_code` | string | 可选的灯弧编码，用于需要时表达分区差异 |
| `light_sector_mode` | string | `sector`、`omni`、`none` |

### 4.4 危险物 / 区域专项字段

| 字段 | 类型 | 用途 |
| --- | --- | --- |
| `hazard_class` | string | `rock`、`wreck`、`obstruction`、`reef`、`shoal`、`current` 等 |
| `hazard_severity` | string | `critical`、`major`、`minor`、`context` |
| `area_usage_class` | string | `anchorage`、`route`、`fishery`、`restricted`、`facility`、`land`、`water` |

## 5 建议的映射策略

新的渲染语义层，应该同时从以下两类输入推导得到：

- 新的语义分类字段
- 为保留海图细节而保留的部分旧字段

### 5.1 映射原则

对象身份和大类语义，优先使用新的 taxonomy 字段。

只有在确实需要保留海图细节表现时，才继续引用旧字段。

### 5.2 映射示例

#### 灯标 / 航标

输入字段：

- `canonical_object_type`
- `形状分類番号`
- `表示用番号`
- `灯色`
- `灯略記`
- `名称`

输出字段：

- `chart_render_type = symbol`
- `chart_symbol_family = navigation_light`
- `chart_symbol_code = lighthouse | light_beacon | buoy | beacon | vais`
- `light_color_code = ...`
- `light_character_code = ...`
- `chart_label_text = 名称`
- `chart_label_subtext = 灯略記`

#### 危险点状对象

输入字段：

- `canonical_object_type`
- `分類番号`

输出字段：

- `chart_render_type = symbol`
- `chart_symbol_family = hazard`
- `chart_symbol_code = rock_awash | isolated_danger | wreck | reef | obstruction`
- `hazard_class = rock | reef | wreck | obstruction`
- `hazard_severity = critical | major | minor`

#### 危险面 / 鱼礁区 / 礁盘区

输入字段：

- `canonical_object_type`
- `分類番号`
- geometry type

输出字段：

- `chart_render_type = fill`
- `chart_fill_style = hazard_area | reef_area | obstruction_area`
- `hazard_class = reef | obstruction | hazard_zone`

#### 水深分带

输入字段：

- `canonical_object_type`

输出字段：

- `chart_render_type = fill`
- `chart_fill_style = depth_zone_0_2 | depth_zone_0_5 | depth_zone_5_10 ...`
- `area_usage_class = water`

#### 边界类对象

输入字段：

- `canonical_object_type`

输出字段：

- `chart_render_type = line`
- `chart_line_style = regulatory_boundary | route_boundary | hazard_boundary`

## 6 建议继续保留的原始字段

即使完成重构，也不建议立刻把所有旧字段从交付 `pbf` 里删除。

### 6.1 为渲染保留

- `分類番号`
- `形状分類番号`
- `表示用番号`
- `灯色`
- `灯略記`
- `明弧/分孤`
- `表示位置`
- `名称`
- `名称補助`
- `日本語地名`
- `英文字地名`

### 6.2 为关联 / 检索保留

- `fid`
- `canonical_object_type`
- `canonical_family`
- `detection_key`

### 6.3 后续可评估移除

这些字段建议在新的渲染语义层稳定之后，再评估是否移除：

- `semantic_key`
- 大块原始 `at` 负载，前提是所需信息都已经物化为显式字段
- 不再被样式、检索或检测引用的旧字段

## 7 样式架构建议

### 7.1 当前样式模式

当前样式主要是直接对旧编码做分支判断。

例如：

- 如果 `分類番号 = 403`，就使用某一个图标
- 如果 `表示用番号 = 31135504`，就切换到另一个图标

这种方式精确，但维护难度很高。

### 7.2 建议中的新样式模式

未来样式应优先基于“渲染语义字段”分支。

例如：

- 如果 `chart_symbol_family = navigation_light`，就进入灯标符号体系
- 如果 `chart_fill_style = depth_zone_0_5`，就使用浅水区填充
- 如果 `chart_line_style = regulatory_boundary`，就使用监管边界线型

只有少量特殊情形，才继续回退到旧字段。

### 7.3 预期结果

这样做会带来以下收益：

- 样式文件更短
- 规则归属更清晰
- 后续迁移更容易
- 多产品之间更容易保持一致

## 8 迁移计划

### 阶段 1：混合交付

保留：

- 旧渲染关键字段
- 新的语义 taxonomy 字段

新增：

- 新的渲染语义字段

使用方式：

- 旧样式继续承担兼容渲染
- 混合样式用于逐步迁移

### 阶段 2：迁移到语义样式

构建一套新的样式，优先读取：

- `chart_render_type`
- `chart_symbol_family`
- `chart_symbol_code`
- `chart_fill_style`
- `chart_line_style`
- `chart_label_text`

旧字段只在少量细节场景下兜底。

### 阶段 3：稳定渲染字段体系

当渲染语义层经过验证后：

- 逐步减少样式对原始旧编码的直接依赖
- 只保留少量用于回退和兼容的旧字段

## 9 示例输出 Feature 模型

灯台示例：

```json
{
  "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"
}
```

鱼礁危险区示例：

```json
{
  "fid": 23456789,
  "canonical_object_type": "魚礁",
  "canonical_family": "hazard",
  "detection_key": "mixed:魚礁",
  "chart_render_type": "fill",
  "chart_symbol_family": "hazard",
  "chart_fill_style": "reef_area",
  "hazard_class": "reef",
  "hazard_severity": "major",
  "chart_priority": 850
}
```

## 10 建议的下一步

建议按下面的顺序推进实现：

1. 在出瓦片流程中定义新的渲染语义字段
2. 将这些字段物化到交付 `pbf`
3. 在过渡期继续保留旧的渲染关键字段
4. 构建一套优先读取新渲染语义字段的混合样式
5. 优先验证灯标体系、危险物体系、鱼业/鱼礁对象和边界对象，再推进更大范围清理

## 11 结论

渲染描述体系完全可以重构，而且值得重构。

正确的方向，不是立刻抛弃旧海图字段，而是在“原始海图属性”和“最终样式”之间，增加一层专门的“渲染语义层”。

这层语义应当提供稳定、明确、可维护的海图渲染含义，同时在必要时保留与旧海图表达方式的兼容能力。