# DataEngine-AD

**Repository Path**: sh-huangjianqi/data-engine-ad

## Basic Information

- **Project Name**: DataEngine-AD
- **Description**: 自动驾驶场景数据管理工具。支持按数据集根路径加载片段、双路相机（前视长焦/广角）同步浏览、关键帧 JSON 标注联动展示与编辑，以及基于文件的标注版本历史与回退。技术栈：FastAPI + Vue3 + Vite，单容器 Docker 部署，适合 COT 等数据集的标注与查看。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-09
- **Last Updated**: 2026-03-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## DataEngine-AD · 自动驾驶数据管理工具

轻量级的自动驾驶数据管理工具，用于浏览片段级多相机图片和关键帧场景标注，并支持简易版本控制与回退。前后端打包在单个 Docker 镜像中，宿主机只需安装 Docker 即可运行。

### 功能特性

- **数据集浏览**
  - 扫描数据根目录，列出所有片段（segment）
  - 左侧侧栏支持 **片段列表** / **帧列表** 双选项卡：选中片段后自动切换到帧列表，可点击某一帧直接跳转；关键帧以高亮与 badge 区分
  - 侧栏 tab 上会展示当前位置：片段 `i/N`、帧 `j/M`，方便在两个标签页中快速确认当前片段与当前帧
  - 顶部“片段信息面板”以**单行横向**展示片段名、起止时间、时长、帧数、VIN 及当前帧场景标签，信息过长时可横向滚动查看
- **标签统计与检索联动**
  - 加载数据集后，后台自动对当前数据集的 labels 做一次场景/决策/关键目标标签统计
  - 侧栏提供 **统计** 标签页：场景标签按照 **时间 / 天气 / 道路类型 / 外部光照 / 其他** 维度分组展示，决策与关键目标按出现次数排序
  - 在统计列表中点击任意标签（例如 `天气:晴`、`时间:白天`、`超车`、`园区小车`），会自动跳转到“检索”标签页并以该标签值（如 `晴`、`白天`）作为关键字发起检索，显示对应片段缩略图
- **片段导出**
  - 正常浏览时隐藏复选框，点击「导出」进入选择模式后显示复选框
  - 支持单片段/多片段导出，点击「确认导出 (N)」后下载 ZIP，目录结构与原数据保持一致
  - 选择模式下勾选状态会被保留（切换片段/帧浏览不会重置）；如需清空可点击「重置」
- **双视窗图片查看**
  - 前视长焦 / 前视广角双视窗同步浏览
  - 支持逐帧前后翻页与“下一/上一关键帧”跳转
  - 上下区域高度固定，切换帧/无标注时按钮位置稳定不跳动
- **标注联动与编辑**
  - 浏览到关键帧时自动加载对应 JSON 标注
  - 默认以 **树形视图** 展示标注：可折叠展开、按 key/value 搜索并高亮
  - 支持在树形视图中 **双击行内编辑单字段**，统计修改数量并一次性保存/撤销
  - 提供“原始 JSON”高级编辑模式，支持实时格式校验
  - 每次保存前自动备份旧版本，支持历史查看与回退
- **单容器交付**
  - FastAPI 后端 + Vue3/Vite 前端打包在同一镜像
  - 一套 Dockerfile + Makefile 即可完成构建与运行

---

## 架构概览

- **后端**：Python 3.11, FastAPI, uvicorn
- **前端**：Vue 3, Vite, Pinia, Axios
- **部署**：单 Docker 镜像
  - 生产：FastAPI 托管前端静态文件，对外端口 `8080`
  - 开发：Vite dev server `5173` + uvicorn `8000`，通过 Volume 挂载本地代码

项目主要目录：

```text
data_manager/
├── backend/                # FastAPI 应用
│   ├── app/
│   │   ├── main.py         # 入口，挂载路由与静态文件
│   │   ├── config.py       # 应用状态（数据集根路径）
│   │   ├── routers/
│   │   │   ├── dataset.py  # 扫描、帧列表、图片服务
│   │   │   └── labels.py   # 标注 CRUD + 版本控制
│   │   │   └── export.py   # 片段导出（ZIP）
│   │   └── services/
│   │       ├── scanner.py  # 文件系统扫描逻辑
│   │       └── label_version.py  # 标注版本管理
│   └── requirements.txt
├── frontend/               # Vue3 + Vite 前端
│   ├── src/
│   │   ├── api/index.js    # Axios API 封装
│   │   ├── stores/dataset.js
│   │   ├── components/     # DatasetLoader / SegmentList / DualImageViewer / LabelPanel / ...
│   │   └── assets/style.css
│   ├── vite.config.js
│   └── package.json
├── Dockerfile              # 多阶段构建：前端构建 + 后端运行
├── Makefile                # 构建 / 运行 / 开发脚本
├── scripts/dev-entrypoint.sh
├── project_info/           # PRD / 任务进度 / 实施计划
└── LICENSE
```

---

## 数据集目录结构

以当前实际数据集结构作为统一规范：

```text
base_datasets/
├── images_resized/<segment>/Images_resize/
│   ├── camera_forward_far/*.jpg      # 前视长焦
│   └── camera_forward_wide/*.jpg     # 前视广角
└── labels/<segment>/Vlm_annotations/camera_forward_wide/*.json
```

- 相机映射：`camera_forward_far` = 前视长焦；`camera_forward_wide` = 前视广角
- 帧名可能包含多级点号（例如 `0000000195.090332`）；匹配标注时仅去掉 `.json` 后缀
- 只有关键帧存在 JSON 标注，其余帧仅有图片
- 若存在 `images_origin/` 目录，在本工具中会被忽略

---

## 后端 API 概览

| 端点 | 方法 | 说明 |
|------|------|------|
| `/api/dataset/load` | POST | 传入数据集根路径，扫描并返回片段列表 |
| `/api/segments/{name}/frames` | GET | 返回片段帧列表，含 `has_label` 与各相机文件名 |
| `/api/images/{segment}/{camera}/{filename}` | GET | 返回图片文件（流式响应） |
| `/api/labels/{segment}/{filename}` | GET | 读取指定帧的 JSON 标注 |
| `/api/labels/{segment}/{filename}` | PUT | 保存标注，并将旧版本备份到 `.label_history` |
| `/api/labels/{segment}/{filename}/history` | GET | 获取历史版本列表 |
| `/api/labels/{segment}/{filename}/revert` | POST | 将当前标注回退到指定历史版本 |
| `/api/stats/labels` | GET | 按场景 / 决策 / 关键目标维度统计当前数据集 labels |
| `/api/export` | POST | 导出指定片段为 ZIP（images_resized + labels 原样打包） |

版本控制策略：

- 保存前将当前文件复制到 `.label_history/<segment>/<frame>/<timestamp>.json`
- 历史目录位于数据集根路径下，不修改原始 `labels` 结构
- 回退时同样先备份当前版本，再覆盖为历史版本

---

## 快速开始（Docker）

### 1. 前置要求

- 已安装 Docker（Linux / macOS / Windows 均可）
- 数据集已放置在宿主机某个路径，例如：`/mnt/hjq/COT数据集/base_datasets`

### 2. 克隆仓库

```bash
git clone git@gitee.com:sh-huangjianqi/data-engine-ad.git
cd data-engine-ad
```

### 3. 开发模式（推荐）

开发模式下代码通过 Volume 挂载到容器中，前端和后端都支持热更新。

```bash
# 默认 DATA_PATH=/mnt/hjq/COT数据集/base_datasets
export DATA_PATH=/mnt/hjq/COT数据集/base_datasets  # 如有需要可修改为你的路径

make dev-bg  # 后台启动开发容器
```

启动成功后：

- 前端：`http://localhost:5173`
- 后端 API：`http://localhost:8001`

### 4. 生产模式（单端口）

```bash
make build
make run
```

然后访问：

- `http://localhost:8080`

---

## 使用说明

1. 打开前端（开发模式 `5173` 或生产模式 `8080`）。  
2. 在顶部输入数据集根路径，例如 `/data`（容器内挂载到该路径）。  
3. 点击「加载」，左侧列出所有可用片段。  
4. 在左侧「片段列表」中选择片段：侧栏会自动切换到「帧列表」，可点击某一帧快速跳转；关键帧在列表中高亮并带“关键帧”标记。  
   - 帧列表顶部提供「上一个片段 / 下一个片段」快捷按钮（首尾循环切换）。  
5. 顶部片段信息面板以单行横向显示片段与当前帧信息，可横向滚动；双视窗同步展示前视长焦和前视广角图片。  
6. 使用底部进度条与按钮：上一帧/下一帧、上一关键帧/下一关键帧。  
7. 当当前帧存在标注时，下方会显示 JSON 内容：  
   - 默认以 **树形视图** 展示：支持折叠/展开、关键字搜索、双击单字段行内编辑；编辑完成后点击顶部「保存全部」。  
   - 如需直接操作完整 JSON，可点击「原始 JSON」切换到 textarea 模式，修改后点击「保存」。  
   - 点击「历史」可查看版本列表，并执行回退操作。  
8. 需要导出片段数据时：在左侧「片段列表」底部点击「导出」进入选择模式，勾选 1~N 个片段后点击「确认导出 (N)」开始下载。选择模式下可继续切换片段/帧进行浏览，勾选不会被重置；点击「重置」可清空勾选；点击「退出」返回正常模式（保留已勾选项）。  
9. 需要从标签角度整体了解数据集分布时：切换到左侧「统计」标签页，可查看按 **时间/天气/道路类型/外部光照** 分组的场景标签统计、决策标签统计和关键目标类别统计；点击任意标签即可跳转到「检索」页面自动展示相关片段的缩略图结果。

---

## 开发指南

- 代码全量在宿主机编辑，容器仅负责运行：\n
  - 后端入口：`backend/app/main.py`\n
  - 路由层：`backend/app/routers/dataset.py`, `backend/app/routers/labels.py`\n
  - 业务逻辑：`backend/app/services/scanner.py`, `backend/app/services/label_version.py`\n
  - 前端入口：`frontend/src/main.js`，根组件 `frontend/src/App.vue`\n
  - 状态管理：`frontend/src/stores/dataset.js`\n
  - UI 组件：`frontend/src/components/*.vue`\n

常用 Make 命令：

| 命令 | 用途 |
|------|------|
| `make build` | 构建生产镜像 `data-manager:latest` |
| `make run` | 以生产模式运行（8080 → 8000） |
| `make dev` | 开发模式（前台，便于实时看日志） |
| `make dev-bg` | 开发模式（后台） |
| `make enter` | 进入容器 shell |
| `make stop` | 停止并移除容器 |
| `make logs` | 查看容器日志 |

---

## 已知问题（历史）与修复

这些问题已在当前版本修复，仅作为设计记录：

- **切换片段后图片黑屏**：\n
  - 根因：在片段切换过程中出现“新 segment + 旧 frame”组合，拼出错误图片 URL（404），且 `<img onerror>` 将元素隐藏后不会恢复。 \n
  - 修复：切换片段时立即清空 `frames` 并重置索引，并为 `<img>` 增加 `:key`，确保 URL 变化时重建元素。\n
- **标注回退目录缺失导致异常**：\n
  - 根因：`revert_to_version` 在将历史文件复制为当前版本时未确保目标父目录存在。 \n
  - 修复：复制前显式创建父目录，与 `save_label` 行为保持一致。\n

---

## 协作与提交规范

- 当前开发主分支为 `dev`。建议在功能分支上开发并合并回 `dev`。  
- 提交信息遵循 **Conventional Commits** 规范（见 `.cursor/rules/git-commit-conventional.mdc`），格式：

```text
<type>(<scope>): <description>
```

常用 `type` 包括：

`feat`（新功能）、`fix`（修 Bug）、`docs`、`style`、`refactor`、`perf`、`test`、`build`、`ci`、`chore`、`revert`。

示例：

```bash
feat(viewer): add dual camera layout
fix(proxy): resolve socket hang up under load
docs: update quick start section in README
```

约定：

- 标题行不超过 72 字符，使用祈使句，小写开头，末尾不加句号。
- 一次提交只做一件事，避免把未完成代码推入仓库。

---

## License

本项目基于 MIT License 开源，详见 [`LICENSE`](LICENSE)。