HSAP/docs/LANE_LABELING_PLAN.md

HSAP 车道线标注接入计划

本文说明如何在 HSAP 平台接入车道线标注，与 DMS 检测/pose 共存。对齐 workspace/lane/DATASET 的 UFLD 训练规范。配套总路线图见 DEVELOPMENT_ROADMAP.md 阶段 D。

---

1. 目标与边界

目标：HSAP 画布标注车道线 → 导出 PNG 分割 mask + list/train_gt.txt → as.py build lane → UFLD 训练。

不做（本期）：CULane .lines.txt 折线画布（archive 历史格式保留，二期可选）。

Profile	编辑器	导出	现状
DMS	dms_detect.xml / dms_pose.xml	yolo / yolo_pose	已实现
lane_v1	lane_culane.xml（缺失）	lane_gt_txt	registry 占位

命名：registry 中 lane_culane.xml 为历史名；实现文件建议 lane_ufld_mask.xml（内容为 BrushLabels），并在 registry 更新。

flowchart TB
  subgraph canvas [HSAP 画布]
    XML["lane_ufld_mask.xml"]
    LSJSON["labels/ls_annotations/*.json"]
  end
  subgraph export [导出]
    Raster["export_ls_to_lane_gt.py"]
    PNG["annotations/.../*.png"]
    List["list/train_gt.txt"]
  end
  subgraph train [训练]
    Build["as.py build lane"]
    UFLD["UFLD train"]
  end
  XML --> LSJSON --> Raster --> PNG
  Raster --> List
  PNG --> Build
  List --> Build --> UFLD

---

2. 你们现有的 Lane 数据规范（背景）

实体数据：workspace/lane/（workspace/Lane/dataset 为软链入口）。

训练标准格式（UFLD）：

DATASET/
├── images/<src_...>/frame_xxxxx.jpg
├── annotations/<src_...>/frame_xxxxx.png    # 单通道 mask，像素值=车道 ID
└── list/train_gt.txt                          # 两列：图路径 + mask 路径

train_gt.txt 示例：

images/src_culane/.../frame_004140.jpg annotations/src_culane/.../frame_004140.png

像素编码（见 vis_random_sample.py）：

像素值	含义
0	背景
2～6	各条车道线

archive 里另有 JSON 折线、.lines.txt（CULane），由 build_ufld_dataset.py 转成 mask 包；平台标注应直接产出 mask，不再绕折线。

---

3. 阶段一：编辑器模板（画布层）

3.1 新增 XML

路径：HSAP/datasets/lane/configs/label_studio/lane_ufld_mask.xml

<View>
  <Image name="image" value="$image" zoom="true"/>
  <BrushLabels name="lanes" toName="image" strokeWidth="3">
    <Label value="lane_1" background="#00FF00"/>
    <Label value="lane_2" background="#0080FF"/>
    <Label value="lane_3" background="#FF0000"/>
    <Label value="lane_4" background="#FF00FF"/>
    <Label value="lane_5" background="#00FFFF"/>
  </BrushLabels>
</View>

标注员操作：选 lane 标签 → 画笔沿车道线涂抹（与离线 LabelMe/CVAT 涂 mask 一致）。

3.2 像素 manifest

路径：HSAP/datasets/lane/configs/lane_mask_encoding.yaml

background: 0
lanes:
  - {label: lane_1, pixel: 2}
  - {label: lane_2, pixel: 3}
  - {label: lane_3, pixel: 4}
  - {label: lane_4, pixel: 5}
  - {label: lane_5, pixel: 6}

3.3 修复模板路径

annotate.py 当前 LABEL_CONFIG_DIR 仅指向 DMS，Lane 读不到模板：

• dms → datasets/dms/configs/label_studio/
• lane → datasets/lane/configs/label_studio/

更新 labeling.registry.yaml：

lane__lane_v1:
  editor_template: lane_ufld_mask.xml
  export_default: lane_gt_txt

无需改 Label Studio 前端源码（Brush 为 Editor 内置）。

---

4. 阶段二：格式转换（核心）

新增：HSAP/datasets/lane/scripts/export_ls_to_lane_gt.py

4.1 输入

labels/ls_annotations/<task_id>.json，result[] 中 type: "brushlabels"（RLE / polygon）。

4.2 输出

产物	规则
PNG mask	annotations/<mirror_path>.png，单通道 uint8
list 行	list/train_gt.txt：images/...jpg annotations/...png
合并逻辑	多 brush region 按 label→pixel 合成一张 mask

4.3 与 offline 流程共存

路径	说明
HSAP 画布	ls_annotations → export → pack 内 images/annotations/list
外协 archive	继续 build_ufld_pack.py 整包入库
训练	两路经 merge_ufld_lists.py 去重合并

---

5. 阶段三：Campaign 与导出 Job

5.1 批次目录

datasets/lane/inbox/<batch>/
  images/...
  annotations/          # 导出生成
  list/train_gt.txt
  labels/ls_annotations/

或增量包 DATASET-AddBy-<工程师>-<日期>/（见 DATASETS_LAYOUT.md）。

5.2 runner

runner.py 增加：

export_default == lane_gt_txt
  → export_ls_to_lane_gt(batch_dir)
  → as.py build lane

与 DMS yolo / yolo_pose 分支共存。

5.3 batch_stage

扩展 batch_stage.py：list/train_gt.txt 非空且 PNG 存在 → stage=returned。

---

6. 阶段四：验证与文档

项	动作
单元测试	test_export_ls_to_lane_gt.py
可视化	workspace/lane/scripts/vis_random_sample.py 叠加
smoke	扩展 smoke_labeling_api.sh lane 分支
文档	LABELING_SOP §4.4、PHASE_ROLLOUT P2、BROWSER_QA_CHECKLIST

---

7. 风险与对策

#	风险	对策
1	Lane 模板读 DMS 目录	annotate 按 project 分目录
2	Brush RLE 解码失败	单测 + 参考 LS RLE 解码
3	像素值与历史 pack 不一致	manifest 固定；导出后 scan unique values
4	多线 overlap	按 lane 顺序合并；SOP 约定尽量不交叉涂
5	线宽不一致	strokeWidth=3，文档约定
6	list 路径错误	相对 pack 根；build 用 --prefix-from-pack
7	折线 vs mask 混淆	SOP：UFLD 只认 mask
8	workspace/lane 软链	setup_links.sh 保持 datasets/lane → workspace/lane

---

8. 排期建议

阶段	时间	内容
一	3～5 天	XML + encoding + annotate 路径
二	5～7 天	export 脚本 + 单测
三	2～3 天	runner + inbox 试点
四	2 天	文档 + 浏览器验收

建议：DMS 阶段 A（PHASE_ROLLOUT_DMS.md）基本通过后再启动 Lane，避免 E2E 并行分散。

---

9. 验收标准

• Lane Campaign 画布：Brush 五车道工具
• 保存 JSON 含 brushlabels
• 导出 PNG 像素值符合 manifest
• list/train_gt.txt 两列正确
• as.py build lane 成功
• vis_random_sample.py 叠加正确
• 与 DMS Campaign 可同时存在

---

10. 关键文件清单

操作	路径
新增	datasets/lane/configs/label_studio/lane_ufld_mask.xml
新增	datasets/lane/configs/lane_mask_encoding.yaml
新增	datasets/lane/scripts/export_ls_to_lane_gt.py
新增	datasets/lane/scripts/test_export_ls_to_lane_gt.py
修改	platform/as_platform/labeling/annotate.py
修改	datasets/labeling.registry.yaml
修改	platform/as_platform/jobs/runner.py
修改	platform/as_platform/labeling/batch_stage.py

---

版本：2026-05-27 · 对齐 workspace/lane UFLD mask 规范