🏎️ BITFSD-Annotator

BITFSD (北理工) 无人车队开源的轻量级 3D 点云标注平台。专为赛道场景打造，内置 SOTIF 质检逻辑，打通感知模型训练闭环。

Vue 3 + FastAPI + Three.js | OpenPCDet 标签格式 | 支持 PyTorch / TensorRT 双后端 AI 预标注

---

✨ Core Features

• Fixed-Size Constraint: 强制固定 0.2×0.2×0.3 m 包围盒，严禁标注员随意缩放
• Contextual 3-View Tuning: 选中目标后弹出 Top / Side / Front 正交三视图，WebGL ClippingPlanes 实时裁剪背景噪点
• SOTIF Quality Gate: 后端实时计算框内点数，稀疏框自动拦截，边缘案例强制降级
• AI Auto-Label: CenterPoint 模型预标注，支持 PyTorch (7GB) 或 TensorRT FP16 (~600MB) 双后端
• OpenPCDet Compatible: 标签落盘为标准 x y z dx dy dz heading class_name 格式

---

🛠️ 安装

依赖总览

组件	纯标注	PyTorch 后端	TensorRT 后端
Python 3.10 + conda	✅	✅	✅
Node.js + npm	✅	✅	✅
CUDA Toolkit (nvcc)	—	✅	✅
PyTorch + OpenPCDet	—	✅	—
TensorRT	—	—	✅

1. Conda 环境

conda create -n bitfsd-annotator python=3.10
conda activate bitfsd-annotator
pip install fastapi uvicorn open3d pandas scipy matplotlib scikit-learn pyyaml

2. 前端

cd frontend
npm install

3. CUDA Toolkit (nvcc) — PyTorch / TensorRT 后端需要

使用 NVIDIA 官方 .run 文件安装。不需要完整的 CUDA Toolkit，只安装编译器组件即可。

官方下载：NVIDIA CUDA Toolkit

# 下载 CUDA Toolkit 12.4 runfile (示例 — 根据你的 CUDA 版本调整)
wget https://developer.download.nvidia.com/compute/cuda/12.4.0/local_installers/cuda_12.4.0_550.54.14_linux.run
sudo sh cuda_12.4.0_550.54.14_linux.run 
# 添加到 PATH
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

# 验证
nvcc --version

4. PyTorch 后端（AI 预标注 — 可选，~7GB 显存）

conda activate bitfsd-annotator
pip install torch==2.1.0 --index-url https://download.pytorch.org/whl/cu118

# 安装 OpenPCDet (pcdet 包)
git clone https://github.com/open-mmlab/OpenPCDet.git /path/to/OpenPCDet
pip install -e /path/to/OpenPCDet

5. TensorRT 后端（AI 预标注 — 可选，~600MB 显存）

TensorRT 使用官方 .tar.gz 包安装，不依赖系统包管理器。

官方下载：NVIDIA TensorRT（需要注册 NVIDIA Developer 账号）

# 1. 下载并解压
tar -xzf TensorRT-10.6.0.26.Linux.x86_64-gnu.cuda-12.4.tar.gz
export TENSORRT_DIR=$(pwd)/TensorRT-10.6.0.26

# 2. 安装 Python 绑定
conda activate bitfsd-annotator
pip install $TENSORRT_DIR/python/tensorrt-10.6.0-cp310-none-linux_x86_64.whl

# 3. 添加库路径
echo "export LD_LIBRARY_PATH=$TENSORRT_DIR/lib:$LD_LIBRARY_PATH" >> ~/.bashrc
source ~/.bashrc

# 4. 验证
python -c "import tensorrt; print('TensorRT', tensorrt.__version__)"

注意： .tar.gz 包名中的 cuda-12.4 需与你的 CUDA 版本匹配。cp310 需与 Python 版本匹配。

6. 数据

点云数据和标注放在 data/<dataset>/ 下：

data/<dataset>/
├── lidar/       (或 points/)  — .pcd 点云文件
└── label/       (或 labels/)  — .txt 标注文件 (自动创建)

🚀 运行

./start.sh

访问 http://localhost:5173。

---

⚙️ 配置 (config.yaml)

项目根目录的 config.yaml 控制所有参数：

# ── 通用 ──
common:
  data_dir: data                          # 数据目录

# ── PyTorch 后端 ──
pytorch:
  model_config: /path/to/model.yaml       # OpenPCDet 模型 config
  checkpoint: /path/to/checkpoint.pth     # CenterPoint 权重

# ── TensorRT 后端 ──
tensorrt:
  trt_config: /path/to/deploy.yaml        # TRT 运行时参数 (体素、范围)
  engine: /path/to/model.engine           # TensorRT engine 文件
  vfe_weights: /path/to/vfe_weights.bin   # VFE 权重 (19KB 二进制)

# ── 推理设置 ──
inference:
  backend: tensorrt                       # "pytorch" | "tensorrt"
  score_thresh: 0.35

# ── SOTIF 质检 ──
sotif:
  min_points_discard: 5                   # 点数 < 此值 → 丢弃
  min_points_hard: 8                      # 点数 ≤ 此值 → Cone_Hard

选哪个后端就填哪个 section，不需要跨配。

---

🤖 AI 预标注配置

两种后端任选其一。PyTorch 精度高但显存大 (~7GB)，TensorRT 显存极低 (~600MB)。

方案 A：PyTorch

config.yaml 中设置：

inference:
  backend: pytorch

pytorch:
  checkpoint: /path/to/checkpoint_epoch_120.pth

需要 torch + pcdet 可用。

方案 B：TensorRT（显存 ~600MB，无需 pcdet）

需要三个文件（均从 PyTorch checkpoint 一次性导出）：

文件	大小	说明
model.engine	~12MB	TensorRT engine，替换 Backbone+Head
vfe_weights.bin	~19KB	VFE 权重 (PFN0/PFN1)，从 checkpoint 提取
deploy.yaml	~300B	运行时参数（点云范围、体素大小、网格尺寸）

导出步骤： 依照 /path/to/test_ws/src/centerpoint/scripts/ 中的 export_onnx.py + export_vfe_weights.py + build_engine.sh。

部署时不需要 OpenPCDet / spconv — VFE 在 CPU (numpy) 上运行，decode 由 JIT 编译的 CUDA kernel 完成。仅需 tensorrt + nvcc。

config.yaml 中设置：

inference:
  backend: tensorrt

tensorrt:
  trt_config: /path/to/deploy.yaml
  engine: /path/to/model.engine
  vfe_weights: /path/to/vfe_weights.bin

---

🖱️ 标注操作

操作	快捷键
放置锥桶框	Shift + Left Click
平移手柄	G
旋转手柄 (Yaw)	R
删除选中框	Backspace / Delete
切换 3D / BEV 视角	V
切换帧	W / S 或方向键
保存标注	Ctrl + S
AI 自动标注	点击 "AI Auto-Label" 按钮

---

📏 标注规范

• 中心对齐: 远距离锥桶因光晕效应呈水平拉伸，框放在横向线段正中心
• 底面贴地: 框底面严格贴合地面点云，避免飞天或入地
• Yaw 对齐: 锥桶轴向对称，Yaw 大致对准传感器即可

质检标准

框内点数	处理	含义
< discard	自动丢弃	物理特征不足
discard ~ hard	强制 Cone_Hard	边缘案例，训练降权
> hard	保存为 Cone	标准数据

阈值 min_points_discard 和 min_points_hard 在 config.yaml 中配置。

---

🧱 项目结构

bitfsd-annotator/
├── config.yaml              ← 主配置
├── start.sh                 ← 一键启动
├── peek_pcd.py              ← PCD 文件查看工具
├── backend/
│   ├── main.py              ← FastAPI (文件列表, 标签 CRUD, 质检, 推理路由)
│   ├── inference.py         ← PyTorch CenterPoint 推理
│   ├── inference_trt.py     ← TensorRT 推理 (CPU VFE + TRT + CUDA decode JIT)
│   └── vfe_weights.bin      ← VFE 权重 (从 checkpoint 导出)
├── frontend/
│   └── src/App.vue          ← Vue 3 + Three.js 主组件
└── data/
    └── <dataset>/
        ├── lidar/            ← .pcd 点云
        └── label/            ← .txt 标注

---

📋 Roadmap

Done

• 3D 点云可视化与交互
• 智能放置包围盒 (Shift+Click)
• 锥桶物理尺寸锁死
• 局部三视图精调 (Top/Side/Front)
• SOTIF 质检拦截器
• OpenPCDet 标准标签输出
• 前后端分离 + 一键启动
• 帧导航 (W/S)
• AI 预标注 — PyTorch 后端
• AI 预标注 — TensorRT CPU-VFE 低显存后端
• 集中配置文件 (config.yaml)

Planned

• 多类别支持 (Cone / Car / Pedestrian)
• GPU VFE for TensorRT (更快但显存略高)
• 标注统计与导出面板
• 多用户协作

---

Built with passion by the Autonomous Systems Group of BITFSD.