HSAP/docs/ADAS_MOON3D_PACK.md

# ADAS 前向训练包 `adas_v1`

> **2026-07 更新**：pack 已从 `adas_moon3d_v1` 重命名为 `adas_v1`（见 `workflow.registry.yaml`）。
> 新增 YOLO HBB 导出路径和 2D 矩形标注支持。

## 目录结构

```text
datasets/adas/packs/adas_v1/
├── sources/{batch}/
│   ├── images/
│   ├── calib/
│   └── labels/
│       ├── quaternion_json/   # 3D cuboid 导出（有 calib 时优先）
│       └── yolo-hbb/          # 2D YOLO HBB 导出（无 calib 回退）
├── lists/
│   ├── train_stems.txt
│   └── val_stems.txt
└── manifests/
    └── pack_index.yaml
```

## class_id（BK2/MOON 顺序）

| ID | 类别 |
|----|------|
| 0 | pedestrian |
| 1 | car |
| 2 | truck |
| 3 | bus |
| 4 | motorcycle |
| 5 | tricycle |
| 6 | traffic cone |

定义于 [`data/送标/adas/adas.registry.yaml`](../../data/送标/adas/adas.registry.yaml) 与 [`datasets/labeling.registry.yaml`](../datasets/labeling.registry.yaml)。

## 管线

1. **labeling_export** — CVAT ls_annotations → `labels/quaternion_json/*.json`
   - 支持 **cuboid**（3D 框）和 **rectanglelabels**（2D 矩形）两种标注类型
   - 2D 矩形自动转为 quaternion_json detection（`fit_ok=false`, `source="2d_rect"`）
2. **cuboid_fit_3d**（有 calib 时自动触发）— 补全 3D 字段
3. **build_adas**（审核）— `promote_batch` 复制到 pack + 刷新 stem 列表
   - 优先使用 quaternion_json，无 cuboid 标注时回退到 YOLO HBB

### 导出路径说明

| 标注类型 | 导出产物 | 条件 |
|---------|---------|------|
| cuboid (3D) | `labels/quaternion_json/*.json` | CVAT cuboid 标注 |
| rectanglelabels (2D) | `labels/quaternion_json/*.json` | 2D 矩形自动桥接 |
| YOLO HBB | `labels/yolo-hbb/*.txt` | 无 cuboid 时使用 `export_adas_yolo` |

## CLI

```bash
# cuboid 导出（平台 Job）
PYTHONPATH=platform python3 -c "from as_platform.labeling.export_cuboid_batch import export_batch; ..."

# YOLO HBB 导出（平台 Job，无 cuboid 时自动选择）
# 由 jobs/runner.py 调用 datasets/adas/scripts/export_ls_to_yolo.py

# 3D 拟合
PYTHONPATH=platform python3 -c "from as_platform.labeling.fit_cuboid_batch import fit_batch; ..."

# 入包
python as.py build adas cuboid_7cls --batch val_front6mm_pilot --pack adas_v1
```

## Smoke

```bash
bash scripts/smoke_adas_promote.sh
```

## 数据目录

ADAS 前向数据在 **数据目录** → **前向** 视图中展示，按 pack → batch 层级显示图片数、标注数和类别分布。