406 lines
10 KiB
Markdown
406 lines
10 KiB
Markdown
# 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 结论
|
||
|
||
渲染描述体系完全可以重构，而且值得重构。
|
||
|
||
正确的方向，不是立刻抛弃旧海图字段，而是在“原始海图属性”和“最终样式”之间，增加一层专门的“渲染语义层”。
|
||
|
||
这层语义应当提供稳定、明确、可维护的海图渲染含义，同时在必要时保留与旧海图表达方式的兼容能力。
|