786 lines
21 KiB
Markdown
786 lines
21 KiB
Markdown
# Style Visual Object Tool
|
||
|
||
## 目标
|
||
|
||
本工具只做一件事：
|
||
|
||
> 从一份 Style JSON 以及它使用的 Sprite / Glyph 中，独立提取和生成 Visual Object。
|
||
|
||
工具输出的是匿名、可比较、可审计的 Visual Object，不负责给 Visual Object 赋予 NavSea 标准 Layer 名称，也不负责解释 Provider 的业务字段。
|
||
|
||
---
|
||
|
||
## 最重要原则：先生成 Visual Object，再做语义和 Layer 对齐
|
||
|
||
本工具必须严格遵守以下顺序：
|
||
|
||
```text
|
||
任意 Provider Style + Sprite / Glyph
|
||
↓
|
||
Style Visual Object Tool
|
||
↓
|
||
Anonymous Visual Object Catalog
|
||
↓
|
||
与 Standard Visual Object Catalog 比较
|
||
↓
|
||
MATCH / PARTIAL / UNKNOWN
|
||
↓
|
||
最后才允许赋予标准 Layer 名称或 Semantic
|
||
```
|
||
|
||
### 禁止走捷径
|
||
|
||
在 Visual Object 生成阶段，以下信息即使存在，也只能作为 provenance / audit 信息保存，**不得用于决定 Visual Object 属于哪个标准 Layer 或 Semantic**：
|
||
|
||
- `source-layer` 名称
|
||
- Style Layer `id`
|
||
- Provider 名称
|
||
- `canonical_object_type`
|
||
- S-52 / CM95 对象类名称
|
||
- S-52 symbol code 的文字含义
|
||
- 任何看起来与 NavSea 标准 Layer 同名或相似的字段
|
||
- 任何 Provider 私有业务字段名称
|
||
|
||
例如，某个 Provider 的 Style 中即使存在：
|
||
|
||
```text
|
||
source-layer = navigation_marks
|
||
```
|
||
|
||
本工具也不得因此把该 Visual Object 定义为 NavSea 的 `navigation_marks`。
|
||
|
||
它只能记录：
|
||
|
||
```text
|
||
provenance.source_layer = navigation_marks
|
||
```
|
||
|
||
真正的 Layer 名称必须在 Visual Object 生成完成后，通过与标准 Visual Object 的比较结果确定。
|
||
|
||
---
|
||
|
||
## Provider-neutral
|
||
|
||
本工具必须完全独立于具体 Provider。
|
||
|
||
同一套代码应能够处理：
|
||
|
||
- NavSea Style
|
||
- CM95 Style
|
||
- 未来 Provider B / C / D
|
||
- 任意符合支持范围的 MapLibre Style
|
||
|
||
主逻辑中禁止出现类似：
|
||
|
||
```text
|
||
if provider == "cm95"
|
||
if source_layer == "navigation_marks"
|
||
if symbol_code == "BOYCAN63" then ...
|
||
```
|
||
|
||
这类 Provider-specific Semantic 判断。
|
||
|
||
Provider-specific 名称可以进入 provenance，但不能进入 Visual Object 分类逻辑。
|
||
|
||
---
|
||
|
||
## 输入
|
||
|
||
第一阶段输入仅包括：
|
||
|
||
```text
|
||
Style JSON
|
||
Sprite JSON + PNG
|
||
Glyph（Style 使用时）
|
||
```
|
||
|
||
Visual Object 提取本身不要求读取 PBF。
|
||
|
||
如果 Style 中使用数据驱动表达式，例如：
|
||
|
||
```json
|
||
["get", "chart_icon_image"]
|
||
```
|
||
|
||
或：
|
||
|
||
```json
|
||
["get", "s52_symbol_code"]
|
||
```
|
||
|
||
工具必须保留为动态视觉参数，不得为了得到具体值去读取 PBF、猜测字段含义或套用 Provider 规则。
|
||
|
||
---
|
||
|
||
## 输出
|
||
|
||
建议至少生成：
|
||
|
||
```text
|
||
catalog.json
|
||
catalog.html
|
||
previews/
|
||
audit.json
|
||
```
|
||
|
||
其中每个 Visual Object 至少记录：
|
||
|
||
- 匿名 Visual Object ID
|
||
- geometry role
|
||
- Style Layer 原始顺序 / z-order
|
||
- 参与组成的 Render Components
|
||
- icon / line / fill / pattern / circle / text
|
||
- Sprite 实际视觉资源
|
||
- 动态视觉参数
|
||
- 出现条件 / Style filter
|
||
- 组件数量与组合关系
|
||
- Preview
|
||
- provenance
|
||
- 无法解析或无法确定的部分
|
||
|
||
---
|
||
|
||
## Visual Signature
|
||
|
||
用于后续跨 Provider 比较的核心是 Visual Signature，而不是 Provider 字段名称。
|
||
|
||
Visual Signature 应主要表达：
|
||
|
||
```text
|
||
geometry role
|
||
+
|
||
ordered render components
|
||
+
|
||
sprite visual
|
||
+
|
||
fill
|
||
+
|
||
line
|
||
+
|
||
pattern
|
||
+
|
||
text role
|
||
+
|
||
component multiplicity
|
||
+
|
||
component composition
|
||
+
|
||
style order
|
||
+
|
||
visual conditions / variants
|
||
```
|
||
|
||
后续 Visual Matcher 应基于这些视觉结构进行比较。
|
||
|
||
Provider 原始字段只作为辅助审计证据，不作为主要匹配依据。
|
||
|
||
---
|
||
|
||
## source-layer 的地位
|
||
|
||
`source-layer` 在本工具中只具有两个作用：
|
||
|
||
1. 帮助确定 Style Layer 的数据来源和可组合范围；
|
||
2. 作为 provenance / debug / audit 信息输出。
|
||
|
||
它**不是 Semantic，也不是最终 Layer 分类结果**。
|
||
|
||
不得执行：
|
||
|
||
```text
|
||
source-layer 名称
|
||
→ 直接得到 NavSea 标准 Layer
|
||
```
|
||
|
||
正确流程必须是：
|
||
|
||
```text
|
||
Style + Sprite
|
||
→ Visual Object
|
||
→ Visual Match
|
||
→ 标准 Layer / Semantic
|
||
```
|
||
|
||
---
|
||
|
||
## Standard Visual Object
|
||
|
||
NavSea 当前 Style 也必须使用同一套 Style Visual Object Tool 生成 Visual Object。
|
||
|
||
不得在 Tool 内置 NavSea Layer 规则。
|
||
|
||
NavSea 之所以成为 Standard，不是因为 Tool 对 NavSea 使用特殊逻辑，而是在 Tool 生成 Visual Object 之后，由独立的标准定义/人工确认把这些 Visual Object 与 NavSea 标准 Layer 关联起来。
|
||
|
||
因此：
|
||
|
||
```text
|
||
NavSea Style
|
||
→ Anonymous Visual Object Catalog
|
||
→ 标准确认
|
||
→ Standard Visual Object Catalog
|
||
```
|
||
|
||
其他 Provider：
|
||
|
||
```text
|
||
Provider Style
|
||
→ Anonymous Visual Object Catalog
|
||
→ 与 Standard Visual Object Catalog 比较
|
||
→ 标准 Layer
|
||
```
|
||
|
||
---
|
||
|
||
## 不属于本工具的职责
|
||
|
||
本工具不负责：
|
||
|
||
- PBF 数据读取和 Feature 实例化
|
||
- Provider 字段翻译
|
||
- CM95 专用判断
|
||
- NavSea 专用判断
|
||
- Semantic 命名
|
||
- 标准 Layer 命名
|
||
- Feature grouping
|
||
- 危险性判断
|
||
- 船舶吃水相关 Planning / Danger 判断
|
||
- 跨 Provider 的最终匹配决策
|
||
|
||
这些属于后续独立阶段或独立 Tool。
|
||
|
||
---
|
||
|
||
## 实现约束
|
||
|
||
后续实现必须满足：
|
||
|
||
- 未知 Style expression 必须显式标记 UNKNOWN / UNSUPPORTED，不得静默忽略；
|
||
- 必须保留 Style 原始顺序；
|
||
- 必须保留组件 multiplicity，不能用 set 去重破坏组合；
|
||
- 必须保留动态表达式，不得伪造成确定值；
|
||
- Sprite 必须根据 atlas metadata 提取真实视觉资源；
|
||
- 不得通过坐标接近、名字相似或 Provider 字段名自动拼接/分类 Visual Object；
|
||
- 不得因为某个 source-layer 与 NavSea 标准 Layer 同名就直接判定 MATCH；
|
||
- Visual Object 的生成和 Visual Object 的标准匹配必须是两个独立阶段。
|
||
|
||
---
|
||
|
||
## 一句话验收标准
|
||
|
||
> 给工具任意一套 Style + Sprite，即使它完全不知道这是什么 Provider、也没有任何 PBF 数据，仍然能够独立生成匿名 Visual Object Catalog；只有在该 Catalog 生成完成后，才允许进入与 NavSea Standard Visual Object Catalog 的比较和 Layer 命名阶段。
|
||
|
||
---
|
||
|
||
## NavSea Standard Visual Object Catalog 冻结规则
|
||
|
||
NavSea 的 Visual Object 与标准 Layer 名在首次完成生成、确认和命名后，应视为 Standard Visual Object Catalog 的冻结基线。
|
||
|
||
正常情况下：
|
||
|
||
```text
|
||
NavSea Anonymous Visual Object
|
||
↓
|
||
人工/标准确认 Layer 名
|
||
↓
|
||
Standard Visual Object Catalog
|
||
↓
|
||
冻结
|
||
```
|
||
|
||
冻结后，后续 CM95、Provider B、Provider C 等只能使用该 Standard Visual Object Catalog 进行 Visual Object 匹配和 Layer 命名。
|
||
|
||
除非用户明确要求重建、重新生成、修订标准或升级 Standard Catalog 版本，否则禁止：
|
||
|
||
- 每次处理新 Provider 时重新生成 NavSea Visual Object；
|
||
- 自动重新计算或改变 NavSea Visual Object ID；
|
||
- 自动改变已经确认的标准 Layer 名；
|
||
- 因 CM95 或其他 Provider 的数据特点反向修改 NavSea Standard Catalog；
|
||
- 用新的 Provider 匹配结果覆盖现有标准基线。
|
||
|
||
如果确实需要修改 Standard Visual Object Catalog，必须作为显式的标准升级处理，并保留旧版本，不得静默覆盖。
|
||
|
||
因此正常跨 Provider 工作流固定为：
|
||
|
||
```text
|
||
已冻结的 NavSea Standard Visual Object Catalog
|
||
│
|
||
│ 作为只读标准
|
||
▼
|
||
Provider Anonymous Visual Object
|
||
│
|
||
▼
|
||
Visual Matcher
|
||
│
|
||
▼
|
||
标准 Layer 命名结果
|
||
```
|
||
|
||
一句话原则：
|
||
|
||
> NavSea Standard Visual Object Catalog 是标准输入，不是每次 Provider 解析时重新生成的临时产物。
|
||
|
||
---
|
||
|
||
## Visual Object Layer Assignment 的补充硬规则
|
||
|
||
### 1. Sprite 存在不等于 Style 会绘制
|
||
|
||
Sprite atlas 中存在某个资源，只能说明资源可用，不能说明当前 Style 会实际引用它。
|
||
|
||
Anonymous Visual Object Catalog 只能从 Style 的正向可达规则生成：
|
||
|
||
```text
|
||
Style 明确允许的资源
|
||
→ 进入 Anonymous Visual Object Catalog
|
||
|
||
仅存在于 Sprite、但当前 Style 没有正向可达路径的资源
|
||
→ 不进入 Catalog
|
||
```
|
||
|
||
尤其不得把 `!match`、`!=` 等排除条件中的值误当成候选 Visual Object。
|
||
|
||
### 2. 同一视觉类可能对应多个标准 Layer
|
||
|
||
如果 NavSea Standard Visual Object Catalog 中同一实际视觉图形被多个标准 Layer 复用，则 Visual Matcher 不能仅凭图形强行选一个 Layer。
|
||
|
||
必须输出：
|
||
|
||
```text
|
||
AMBIGUOUS
|
||
candidateStandardLayers:
|
||
- layer_a
|
||
- layer_b
|
||
```
|
||
|
||
例如危险物公共符号可以同时被多个标准 Layer 使用；这种歧义是 Standard Catalog 自身的事实，不应由 Matcher 擅自消除。
|
||
|
||
### 3. 禁止整个匿名 group 继承单一 Layer
|
||
|
||
Style 的一个匿名 group 可能允许多个不同视觉家族，尤其是通用 S-52 Style。
|
||
|
||
因此禁止：
|
||
|
||
```text
|
||
group 命中一个视觉锚点
|
||
→ 整个 group 继承该 Layer
|
||
```
|
||
|
||
Layer Assignment 必须以单个 Visual Object / Visual Resource 为基本单位。
|
||
|
||
Group 只用于：
|
||
|
||
- 组合范围审计；
|
||
- Style provenance；
|
||
- 结果分布检查。
|
||
|
||
### 4. Layer Assignment 状态
|
||
|
||
正式状态固定为：
|
||
|
||
```text
|
||
MATCH
|
||
PARTIAL
|
||
AMBIGUOUS
|
||
COMPONENT
|
||
UNKNOWN
|
||
```
|
||
|
||
含义：
|
||
|
||
- `MATCH`：实际图形基本一致，可以直接作为标准 Layer 锚点；
|
||
- `PARTIAL`：不是同一完整图形，但视觉家族或组件关系足以支持唯一标准 Layer；
|
||
- `AMBIGUOUS`：视觉证据只能得到多个标准 Layer 候选，禁止强行选一个；
|
||
- `COMPONENT`：明确只是完整 Visual Object 的组成部分，不单独分配 Layer；可选记录组件类型；
|
||
- `UNKNOWN`：当前证据不足，不命名。
|
||
|
||
未知和歧义都是合法结果，禁止为了提高覆盖率而静默猜测。
|
||
|
||
---
|
||
|
||
## 人工确认 UI：CM95 Visual Object Reviewer
|
||
|
||
最终 Layer Assignment 必须允许人工确认。项目内提供独立 Web Reviewer：
|
||
|
||
```text
|
||
tools/style-visual-object/reviewer/
|
||
├── review_server.py
|
||
└── web/
|
||
├── index.html
|
||
├── app.js
|
||
└── style.css
|
||
```
|
||
|
||
默认启动：
|
||
|
||
```text
|
||
python3 tools/style-visual-object/reviewer/review_server.py --host 0.0.0.0 --port 18083
|
||
```
|
||
|
||
### 人工确认单位
|
||
|
||
Reviewer 以 **CM95 当前 Style 正向可达的唯一 Visual Resource** 为确认单位。
|
||
|
||
当前基线为 150 个资源。一个人工决定会应用到该视觉资源在 Anonymous Catalog 中的所有 occurrence，但不会修改 Anonymous Catalog 本身。
|
||
|
||
### 主审查界面必须隐藏 Provider 语义信息
|
||
|
||
为了避免人工被字段名或已有 source-layer 名称带偏，主审查界面默认只能看到：
|
||
|
||
- 匿名 Visual Object ID；
|
||
- 实际图形；
|
||
- component role；
|
||
- geometry role；
|
||
- occurrence 数；
|
||
- NavSea Standard Visual Object 候选；
|
||
- 标准 Layer；
|
||
- 当前人工决定。
|
||
|
||
以下 CM95 原始信息默认隐藏：
|
||
|
||
- resource key；
|
||
- source-layer；
|
||
- Style Layer id；
|
||
- Provider provenance。
|
||
|
||
只有用户主动展开“审计信息”后才能读取这些内容。
|
||
|
||
### 人工状态
|
||
|
||
人工决定固定使用：
|
||
|
||
```text
|
||
MATCH
|
||
PARTIAL
|
||
AMBIGUOUS
|
||
COMPONENT
|
||
UNKNOWN
|
||
```
|
||
|
||
规则：
|
||
|
||
- MATCH / PARTIAL：必须选择且只能选择一个标准 Layer；
|
||
- AMBIGUOUS：必须选择至少两个候选标准 Layer；
|
||
- COMPONENT：不选择标准 Layer、不绑定 Standard Visual Object；可选记录顶标、浮标主体、立标主体、灯光、附加标记、面填充图案、线型图案、文字或其他组件；
|
||
- UNKNOWN：不选择标准 Layer；
|
||
- Standard Visual Object 可以选择，也可以不选择；
|
||
- 人工确认优先于机器建议；
|
||
- 未人工确认的项目在最终人工导出时保持 UNKNOWN，不自动继承机器建议。
|
||
|
||
### 人工结果保存
|
||
|
||
增量人工决定保存到：
|
||
|
||
```text
|
||
tools/style-visual-object/output/cm95-manual-review/manual-review-v1.json
|
||
```
|
||
|
||
点击“生成当前人工确认结果”后生成：
|
||
|
||
```text
|
||
tools/style-visual-object/output/cm95-manual-review/
|
||
├── reviewed-anchors-manual-v1.json
|
||
└── assignment/
|
||
├── cm95-layer-assignment-v1.json
|
||
├── cm95-layer-assignment-v1.csv
|
||
└── cm95-layer-assignment-v1.html
|
||
```
|
||
|
||
人工确认过程不得覆盖：
|
||
|
||
- `navsea-standard/standard-catalog.json`；
|
||
- `cm95-anonymous/anonymous-catalog.json`；
|
||
- 既有自动/辅助建议文件。
|
||
|
||
NavSea Standard Catalog 继续保持 FROZEN，只作为只读标准库使用。
|
||
|
||
---
|
||
|
||
## Reviewer 中文名称显示规则
|
||
|
||
人工 Reviewer 中，CM95 与 NavSea Standard Visual Object 均应优先显示中文名称，帮助人工理解和确认。
|
||
|
||
中文名称来源分两类：
|
||
|
||
1. CM95：
|
||
- 优先读取当前 CM95 仓库中的 S-52 symbol / line / area-pattern metadata；
|
||
- 保留 S-52 原始英文 `description`；
|
||
- 生成独立的中文显示译名；
|
||
- 中文译名属于工程 UI enrichment，不冒充 IHO 官方中文译名。
|
||
|
||
2. NavSea Standard：
|
||
- 依据冻结 Standard Visual Object 的语义资源键和标准 Layer 生成中文显示名；
|
||
- 标准 Layer 同时显示中文名和原始 Layer ID。
|
||
|
||
名称补充表：
|
||
|
||
```text
|
||
tools/style-visual-object/output/reference-name-enrichment-v1.json
|
||
```
|
||
|
||
固定原则：
|
||
|
||
> 中文名、英文说明、S-52 code 只用于 UI 显示和人工理解，不得参与 Visual Matcher、自动聚类或 Layer Assignment。
|
||
|
||
Reviewer 主界面显示优先级：
|
||
|
||
```text
|
||
中文名称
|
||
→ 实际图形
|
||
→ 中文标准 Layer
|
||
→ 原始 code / 英文说明（辅助）
|
||
```
|
||
|
||
已有机器建议也必须显示：
|
||
|
||
```text
|
||
标准对象中文名
|
||
+
|
||
标准 Layer 中文名
|
||
+
|
||
MATCH / PARTIAL / AMBIGUOUS / COMPONENT / UNKNOWN
|
||
```
|
||
|
||
不得只显示资源 key 或 Layer ID 让用户自行猜测。
|
||
|
||
---
|
||
|
||
## Reviewer 宽屏固定确认布局
|
||
|
||
Reviewer 在宽屏下采用固定三栏工作区：
|
||
|
||
```text
|
||
左：CM95 当前 Visual Object
|
||
中：NavSea Standard 候选（竖排、内部滚动）
|
||
右：人工判断（固定可见）
|
||
```
|
||
|
||
固定要求：
|
||
|
||
- 主页面不得为了点击 MATCH / PARTIAL / AMBIGUOUS / COMPONENT / UNKNOWN 或保存结果而要求纵向滚动；
|
||
- NavSea Standard 候选采用竖排列表，并在候选区域内部滚动；
|
||
- 标准 Layer 列表在人工判断面板内部滚动；
|
||
- `保存并下一个 / 仅保存 / 撤销` 始终保持在右侧人工判断区可见；
|
||
- 左侧 CM95 队列独立滚动；
|
||
- 审计信息默认折叠，不抢占主要确认空间；
|
||
- 窄屏才允许退回上下布局。
|
||
|
||
---
|
||
|
||
## Standard Visual Object 缺失时的 Layer-only 人工命名
|
||
|
||
外部 Provider（例如 CM95 / S-52）的视觉内容可能多于当前 NavSea Standard Visual Object Catalog。
|
||
因此：
|
||
|
||
> 找不到对应的 NavSea Standard Visual Object，不等于无法确定标准 Layer。
|
||
|
||
人工 Reviewer 必须支持两种最终确认路径：
|
||
|
||
```text
|
||
A. 有对应标准图标
|
||
Provider Visual Object
|
||
→ Standard Visual Object
|
||
→ Standard Layer
|
||
assignment_mode = VISUAL_OBJECT_MATCH
|
||
|
||
B. 没有对应标准图标，但所属 Layer 可以人工确定
|
||
Provider Visual Object
|
||
→ Standard Layer
|
||
assignment_mode = LAYER_ONLY
|
||
standard_resource_key = null
|
||
```
|
||
|
||
Layer-only 的要求：
|
||
|
||
- 必须由人工明确选择标准 Layer；
|
||
- 不得伪造一个不存在的 Standard Visual Object；
|
||
- 不得因为没有对应图标就强制设为 UNKNOWN；
|
||
- 中文名称、S-52 官方英文说明和实际视觉可以作为人工理解证据；
|
||
- 这些名称仍不进入自动 Visual Matcher；
|
||
- 当前 Reviewer 中，点击“没有对应标准图标，只确认所属 Layer”会清除 Standard Visual Object 绑定，并保留唯一 Layer。
|
||
|
||
状态建议：
|
||
|
||
- 有明确对应完整图形时可使用 MATCH；
|
||
- 无对应标准图标但 Layer 明确时使用 PARTIAL + LAYER_ONLY；
|
||
- 只能确定多个可能 Layer 时使用 AMBIGUOUS；
|
||
- 连 Layer 也无法确定时才使用 UNKNOWN。
|
||
|
||
---
|
||
|
||
## COMPONENT：只作为完整 Visual Object 的组成部分
|
||
|
||
当当前显示的 S-52 / CM95 图形只是一个主体、顶标、灯光或其他附加组件时，不应强迫用户给它最终 Layer。
|
||
Reviewer 必须允许：
|
||
|
||
```text
|
||
status = COMPONENT
|
||
assignment_mode = COMPONENT_ONLY
|
||
standard_layer = null
|
||
standard_resource_key = null
|
||
```
|
||
|
||
可选 `component_kind`：
|
||
|
||
```text
|
||
topmark 顶标
|
||
buoy_body 浮标主体
|
||
beacon_body 立标主体
|
||
light 灯光
|
||
auxiliary_mark 附加标记
|
||
fill_pattern 面填充图案
|
||
line_pattern 线型图案
|
||
text 文字
|
||
other 其他组件
|
||
```
|
||
|
||
`COMPONENT` 与 `UNKNOWN` 必须区分：
|
||
|
||
- `COMPONENT`：已经知道它只是完整对象的一部分；
|
||
- `UNKNOWN`：当前连它的作用/归属关系也无法可靠判断。
|
||
|
||
后续 Composite Visual Object 阶段再把 COMPONENT 与其他组件组合，最终 Layer 应尽量由完整 Visual Object 确认。
|
||
|
||
---
|
||
|
||
## Reviewer 最可能候选提示
|
||
|
||
Reviewer 的 NavSea Standard 候选可以提供一个 **UI-only 的“最可能”提示**，帮助人工快速判断。
|
||
|
||
综合参考只用于界面提示，来源包括：
|
||
|
||
- Visual Matcher 的实际图形相似度；
|
||
- CM95 中文显示名与 NavSea Standard 中文显示名的文字相似度；
|
||
- 已有 reviewed visual suggestion 是否支持同一标准对象或同一 Layer。
|
||
|
||
界面规则：
|
||
|
||
- 综合排序第一的候选中文名称标红；
|
||
- 显示“最可能”标签；
|
||
- 同时显示“视觉 xx% / 综合 xx%”；
|
||
- 即使是第一名，综合分较低时也必须保留低分，不能隐藏不确定性；
|
||
- 红色提示不得自动选择 Standard Visual Object；
|
||
- 不得自动写入人工决定；
|
||
- 不参与最终 Layer Assignment。
|
||
|
||
一句话：
|
||
|
||
> 红色“最可能”只是人工审查提示，不是系统确认结果。
|
||
|
||
宽屏布局同时调整为：当前 CM95 对象区域更窄，NavSea Standard 视觉候选区域更宽，右侧人工判断继续固定显示。
|
||
|
||
---
|
||
|
||
## Provider Layer Classifier：当前工作的最终目标
|
||
|
||
当前多源 PBF 对应工作的目标不是寻找“外部 Provider 图标等于 NavSea 哪个图标”，而是：
|
||
|
||
> 把外部 Provider 的对象正确分类到现有 NavSea Standard Layer。
|
||
|
||
因此正式流程分成两层：
|
||
|
||
```text
|
||
第一层：Provider-neutral Style Visual Object Tool
|
||
Style + Sprite
|
||
→ Anonymous Visual Object
|
||
|
||
第二层：Provider Layer Classifier
|
||
Anonymous Visual Object
|
||
+ Provider 官方语义资料
|
||
+ 实际视觉证据
|
||
+ 可选 Standard Visual Object 参考
|
||
→ NavSea Standard Layer
|
||
→ 人工确认
|
||
```
|
||
|
||
关键规则：
|
||
|
||
1. `Style Visual Object Tool` 仍然不知道 NavSea Layer、CM95 语义或 Provider 私有分类，继续保持 Provider-neutral。
|
||
2. `Provider Layer Classifier` 可以使用 Provider 自己的官方语义资料。CM95 当前使用 S-52 metadata 的官方英文 `description`，再提供中文显示译名。
|
||
3. Provider 的 `source-layer` 仍不得作为分类依据，只保留 provenance/audit。
|
||
4. Standard Visual Object 一一对应不是最终目标，也不是 Layer 命名的强制前提。
|
||
5. 没有对应 NavSea 图标，但 Provider 语义足以确定 Layer 时，允许直接 `LAYER_ONLY`。
|
||
6. 当前图形只是顶标、灯光、主体、pattern 等组件时使用 `COMPONENT`，不单独分配最终 Layer。
|
||
7. 只有连 Layer 都无法可靠判断时才使用 `UNKNOWN`。
|
||
|
||
### CM95 语义 Layer 规则
|
||
|
||
当前 CM95 分类规则独立保存：
|
||
|
||
```text
|
||
tools/style-visual-object/cm95_semantic_layer_rules_v1.json
|
||
```
|
||
|
||
规则使用 S-52 官方 description 和资源类型进行声明式分类，例如：
|
||
|
||
```text
|
||
tower, black/white, full-chart and simplified
|
||
→ 对象大类：陆上塔状构筑物
|
||
→ onshore_structure_point
|
||
|
||
beacon tower, red, full-chart
|
||
→ 对象大类：航标塔体
|
||
→ navigation_marks
|
||
|
||
topmark for buoys ...
|
||
→ COMPONENT / topmark
|
||
```
|
||
|
||
这些规则属于 Provider Layer Classifier，不得回写进通用 Style Visual Object extraction。
|
||
|
||
### Reviewer 中间区域
|
||
|
||
Reviewer 中间主要区域现在显示 `NavSea Layer 建议`，综合参考：
|
||
|
||
- S-52 官方语义；
|
||
- 实际视觉相似度；
|
||
- 已有 reviewed visual suggestion。
|
||
|
||
语义证据优先于“长得像”。例如普通 `tower` 即使视觉上很像 beacon，也应优先按 S-52 的 tower 语义归到 `onshore_structure_point`。
|
||
|
||
Standard Visual Object 图标被降为折叠的辅助参考区，不再作为主要任务。
|
||
|
||
---
|
||
|
||
## Git 冻结基线与固定校验命令
|
||
|
||
CM95 v1 人工分类完成后，以下内容属于应进入 Git 的冻结基线：
|
||
|
||
- 工具实现：`style_vo_tool.py`、`visual_anchor_matcher.py`、`build_reference_names.py`、`apply_reviewed_layer_assignment.py`；
|
||
- Provider 分类规则：`cm95_semantic_layer_rules_v1.json`；
|
||
- 人工 Reviewer：`reviewer/`；
|
||
- 固定校验逻辑：`validate_cm95_classification.py`；
|
||
- NavSea Frozen Standard Catalog 与 CM95 Anonymous Catalog；
|
||
- S-52 中文名称 enrichment、视觉辅助结果；
|
||
- 150 项人工确认；
|
||
- 最终 occurrence 级 Layer Assignment；
|
||
- 固定校验报告和最终中文报告。
|
||
|
||
固定校验命令：
|
||
|
||
```bash
|
||
python3 tools/style-visual-object/validate_cm95_classification.py
|
||
```
|
||
|
||
提交前必须满足：
|
||
|
||
```text
|
||
RESULT: PASS
|
||
```
|
||
|
||
`WARN` 允许存在，但只能表示“人工结果与后续语义建议不同，需要时复核”；不得自动覆盖人工结果。
|
||
|
||
当前权威结果路径：
|
||
|
||
```text
|
||
tools/style-visual-object/output/cm95-manual-review/manual-review-v1.json
|
||
tools/style-visual-object/output/cm95-manual-review/reviewed-anchors-manual-v1.json
|
||
tools/style-visual-object/output/cm95-manual-review/assignment/cm95-layer-assignment-v1.json
|
||
tools/style-visual-object/output/cm95-manual-review/validation-report-v1.json
|
||
```
|
||
|
||
当前最终报告：
|
||
|
||
```text
|
||
tools/style-visual-object/output/CM95_Visual_Object_Layer命名报告_v2.md
|
||
```
|