diff --git a/README.md b/README.md index 6f6d735..b565345 100644 --- a/README.md +++ b/README.md @@ -1,35 +1,43 @@ # HSAP — Huaxu Sentinel Active Safety Platform -**华胥 Sentinel 主动安全算法迭代平台**(HSAP):卡车主动安全(DMS / Lane / ADAS)算法迭代平台,含 **Web UI + API + 审核 + Job 队列 + 算法适配器**。 +**华胥 Sentinel 主动安全算法迭代平台**(HSAP):卡车主动安全(DMS / Lane / ADAS)算法迭代平台,含 **Web UI + API + 审核 + Job 队列 + CVAT 标注 + 算法适配器**。 -克隆本仓库即可运行平台;**算法源码与数据集脚手架已内嵌**,无需依赖本地软链。大文件(图像、训练权重)通过外部 `workspace` 挂载或自行 rsync。 +克隆本仓库即可运行平台;**算法源码与数据集脚手架已内嵌**,无需依赖本地软链。大文件(图像、训练权重)通过外部 `workspace` 或 **送标数据湖** 挂载,不进入 Git。 --- ## 仓库结构 ```text -HSAP/ # 建议 clone 目录名 +HSAP/ ├── as.py / workflow.registry.yaml ├── platform/ -│ ├── as_platform/ # FastAPI 后端(Python 包名保留 as_platform) +│ ├── as_platform/ # FastAPI 后端 +│ │ └── labeling/ # CVAT 客户端、格式转换、任务分配 │ └── web/ # React (Vite) 前端 ├── algorithms/ -│ ├── dms_yolo/code/ # DMS YOLO26 训练代码(内嵌) -│ └── lane_ufld/code/ # Lane UFLD 代码(内嵌) +│ ├── dms_yolo/code/ # DMS YOLO 训练代码 +│ └── lane_ufld/code/ # Lane UFLD 代码 ├── datasets/ -│ ├── dms/ # DMS 配置/脚本脚手架 -│ └── lane/ # Lane 列表与脚本脚手架 -├── scripts/ -├── docker-compose.yml / Dockerfile +│ ├── dms/ # DMS 配置/脚本 +│ ├── lane/ # Lane 列表与脚本 +│ ├── adas -> ../../data/送标/adas # ADAS 送标数据湖(符号链接) +│ └── labeling.registry.yaml # 标注 profile(cuboid_7cls 等) +├── vendor/cvat/patches/ # CVAT no_auth + iframe 补丁 +├── scripts/ # dev_up、build_web、reset_labeling 等 +├── docs/HANDOVER.md # 详细交接文档 +├── docker-compose.yml +├── docker-compose.cvat.yml # 内置 CVAT 全套服务 └── manifests/ ``` | 内容 | 是否在 Git 中 | 说明 | |------|---------------|------| | 平台 + 前端 + 适配器 | ✅ | 直接提交 | +| CVAT 补丁 / compose | ✅ | `vendor/cvat/patches/` | | 算法 Python 源码 | ✅ | `scripts/vendor_workspace.sh` 同步 | | 数据集 yaml/脚本 | ✅ | 不含图像 | +| 送标图像 / 标定 / 标注 | ❌ | 数据湖 `DATA/data/送标/`,volume 挂载 | | 图像 / 视频 / 权重 | ❌ | `.gitignore` 排除;用 workspace 挂载 | --- @@ -39,22 +47,25 @@ HSAP/ # 建议 clone 目录名 **依赖:** Docker 20+、Docker Compose v2 ```bash -git clone <你的仓库 URL> HSAP +git clone https://git.sanyele.com/ChengFang.LU/HSAP.git cd HSAP bash scripts/init_after_clone.sh # 生成 .env / feishu.env bash scripts/dev_up.sh # 或: make up ``` -| 服务 | 地址 | -|------|------| -| 平台 UI + API | http://127.0.0.1:8787 | -| PostgreSQL | localhost:5432 | -| Redis | localhost:6379 | +`make up` 会同时启动 **HSAP 平台** 与 **内置 CVAT**(无需单独部署 BK2/cvat,无需 CVAT 账号登录)。 + +| 服务 | 地址 | 说明 | +|------|------|------| +| HSAP 平台 UI + API | http://127.0.0.1:8787 | 登录、送标、标注、审核 | +| CVAT 标注画布 | http://127.0.0.1:8080 | 由 HSAP iframe 嵌入;内部引擎 no_auth | +| PostgreSQL | localhost:5433 | 默认映射端口(见 `.env`) | +| Redis | localhost:6380 | Job 队列 | ```bash make logs # platform / worker 日志 -make down # 停止 +make down # 停止平台 + CVAT make dev # 额外启动 Vite 热更新 :5173 ``` @@ -64,6 +75,85 @@ make dev # 额外启动 Vite 热更新 :5173 --- +## 标注与送标 + +HSAP 统一使用 **CVAT** 作为标注画布;账号、任务分配、权限均在 HSAP 管理,CVAT 仅作内部引擎。 + +### 流程概览 + +```text +数据湖登记批次 → 协调员「开标」→ CVAT 自动建 Task / 上传图片 + → 协调员分配任务(飞书通讯录选人 + 可选 DM 通知) + → 标注员「我的标注」进入 → CVAT 画框/ Cuboid → 保存 → 同步回数据湖 + → 协调员提交批次 → 质检 → 导出入库 +``` + +### 角色与页面 + +| 角色 | 典型页面 | +|------|----------| +| 协调员 (engineer) | 送标工作台、标注进度、任务分配 | +| 标注员 (labeler) | **我的标注**(默认落地页)、标注页 | +| 审核员 (reviewer) | 审核队列 | + +### 支持的标注类型 + +| Profile | 范围 | CVAT 工具 | +|---------|------|-----------| +| `ddaw` / `addw` 等 | DMS 2D 检测 | Rectangle | +| `lane__lane_v1` | 车道线 | Polyline | +| `cuboid_7cls` | ADAS 单目 3D Cuboid(7 类) | Cuboid | + +ADAS 7 类:`car`, `pedestrian`, `truck`, `bus`, `motorcycle`, `tricycle`, `traffic cone` + +### 送标数据湖(ADAS Cuboid 示例) + +宿主机目录(与仓库平级): + +```text +DATA/data/送标/adas/inbox/cuboid_7cls// +├── batch.meta.yaml +├── images/ +├── calib/ # 相机内参(可选) +│ └── cam0_front_6mm.yaml +└── labels/ + └── quaternion_json/ # 3D 预标注 JSON(可选) +``` + +`.env` / `docker-compose.yml` 默认将 `../data` 挂载为容器内 `/data/data`。登记与开标: + +```bash +# API 或平台 UI:register-batch → 标注进度 → 开标 +# 批次出现在「标注进度」后即可分配、标注 +``` + +清空送标/标注 DB 记录(保留账号):`bash scripts/reset_labeling.sh` + +--- + +## 数据挂载 + +### 外部 workspace(DMS / Lane 大文件) + +```bash +# .env 中设置 +AS_WORKSPACE_ROOT=/path/to/DATA/workspace + +bash scripts/setup_links.sh +docker compose -f docker-compose.yml -f docker-compose.cvat.yml up -d --build +``` + +### 送标数据湖(ADAS 等) + +```bash +# .env 可选覆盖宿主机路径(默认 ../data) +AS_DATA_LAKE_HOST=/path/to/DATA/data +``` + +确保 `HSAP/datasets/adas` 符号链接指向 `data/送标/adas`(clone 后若缺失可手动 `ln -sfn ../../data/送标/adas datasets/adas`)。 + +--- + ## 本机直跑(不用 Docker 跑 Platform) ```bash @@ -74,6 +164,7 @@ bash scripts/run_local.sh - Job 默认 `AS_JOB_EXECUTOR=thread`(无需 Redis) - 无 PostgreSQL 时自动回退 SQLite(`manifests/platform.db`) +- 标注功能需 CVAT 可达(`CVAT_HOST`) 仅基础设施用 Docker: @@ -84,62 +175,6 @@ bash scripts/run_local.sh --- -## 外部 workspace(大文件数据) - -若你有 monorepo 布局 `DATA/workspace/`(含 DMS 图像、Lane 数据等): - -```bash -# .env 中设置 -AS_WORKSPACE_ROOT=/path/to/DATA/workspace - -bash scripts/setup_links.sh -docker compose up -d --build -``` - ---- - -## 维护者:从 workspace 刷新内嵌代码 - -```bash -bash scripts/vendor_workspace.sh -git add algorithms/ datasets/ manifests/repo_layout.json -git commit -m "chore: refresh vendored algorithm scaffolds" -``` - -同步到训练服务器: - -```bash -bash scripts/sync_to_server.sh user@host:/opt/HSAP -bash scripts/sync_to_server.sh user@host:/opt/HSAP --code-only -``` - ---- - -## 上传到 Gitea / GitHub - -1. 创建空仓库,名称:**`HSAP`** -2. 本地: - -```bash -cd HSAP -git init -git add . -git status # 确认无 .env、feishu.env、node_modules、*.pt 等大文件 -git commit -m "feat: initial HSAP platform" -git remote add origin https://gitea.example.com/ChengFang.LU/HSAP.git -git branch -M main -git push -u origin main -``` - -3. **Push 前检查:** - -```bash -git check-ignore -v manifests/feishu.env .env platform/web/node_modules -find . -type l ! -path './platform/web/node_modules/*' | wc -l # 应为 0 -``` - ---- - ## 认证(飞书 + PostgreSQL) ```bash @@ -151,10 +186,12 @@ cp manifests/feishu.env.example manifests/feishu.env |------|------| | admin | 全部 + 用户管理 | | reviewer | 审核批准/驳回 | -| engineer | 提交 build/train | -| labeler | 目录/批次登记 | +| engineer | 送标开标、任务分配、build/train | +| labeler | 我的标注、CVAT 画布保存 | | viewer | 只读 | +**飞书任务分配** 需应用权限:`contact:contact:readonly_as_app`、`im:message:send_as_bot` 等(详见 `docs/HANDOVER.md`)。 + --- ## CLI 示例 @@ -168,10 +205,42 @@ python as.py train dms dam --track platform --- +## 维护者 + +### 从 workspace 刷新内嵌代码 + +```bash +bash scripts/vendor_workspace.sh +git add algorithms/ datasets/ manifests/repo_layout.json +git commit -m "chore: refresh vendored algorithm scaffolds" +``` + +### 同步到训练服务器 + +```bash +bash scripts/sync_to_server.sh user@host:/opt/HSAP +bash scripts/sync_to_server.sh user@host:/opt/HSAP --code-only +``` + +### 推送到 Git 远端 + +```bash +cd HSAP +git status # 确认无 .env、feishu.env、node_modules、*.pt、送标图像 +git push origin main +``` + +远端:`https://git.sanyele.com/ChengFang.LU/HSAP.git` + +--- + ## 更多文档 -- [docs/DEVELOPMENT_GUIDE.md](docs/DEVELOPMENT_GUIDE.md) -- [docs/DATA_LAKE_CHECKLIST.md](docs/DATA_LAKE_CHECKLIST.md) +| 文档 | 说明 | +|------|------| +| [docs/HANDOVER.md](docs/HANDOVER.md) | **项目交接**:架构、API、运维、排障 | +| [docs/DEVELOPMENT_GUIDE.md](docs/DEVELOPMENT_GUIDE.md) | 开发指南 | +| [docs/DATA_LAKE_CHECKLIST.md](docs/DATA_LAKE_CHECKLIST.md) | 数据湖检查清单 | ---