labelCloud

:information_source: 交互式文档

一个用于在点云中标注3D边界框的轻量级工具。

安装

:information_source: 目前labelCloud支持Python 3.7至3.9版本。

通过pip（PyPI）

pip install labelCloud
labelCloud --example  # 使用示例点云启动labelCloud

通过git（手动安装）

git clone https://github.com/ch-sa/labelCloud.git  # 1. 克隆仓库
pip install -r requirements.txt  # 2. 安装依赖
# 3. 将点云文件复制到`pointclouds`文件夹中。
python3 labelCloud.py  # 4. 启动labelCloud

根据需要编辑config.ini文件或设置来配置软件（参见配置）。

标注

labelCloud支持两种不同的标注方式（拾取和拖拽），并提供多种鼠标和键盘操作以进行后续修正。

（另请参阅https://www.youtube.com/watch?v=8GF9n1WeR8A，了解该工具的简短介绍和预览。）

拾取模式

• 点击选择边界框的前顶角位置。
• 通过滚动鼠标滚轮调整z轴旋转角度。

拖拽模式

• 接着通过选择四个顶点来拖拽确定边界框的长、宽、高。
• 最后两个顶点（宽度和高度）所在的层会被锁定，以便于选择。

修正

• 使用左侧按钮或快捷键来修正边界框的平移、尺寸和旋转。
• 按住鼠标指针悬停在某一边上，并滚动鼠标滚轮即可调整边界框大小。

默认情况下，边界框的x轴和y轴旋转将被禁止。若要标注9自由度边界框，请在菜单、设置或config.ini文件中关闭仅z轴旋转模式。此时边界框可以绕三个轴自由旋转。

基于边界框的语义分割

labelCloud还支持基于边界框创建分割标签。要启用语义分割模式，请在启动对话框中切换分割按钮。然后按常规方式标注，并在当前边界框内的所有点都应标记为同一类别时，点击分配按钮。

生成的标签将以*.bin文件的形式存储在labels/segmentation/目录下。每个*.bin文件包含一个形状为(点数, )、数据类型为np.int8的数组，其中每个条目代表原始点云中对应点的标签索引。

导入与导出选项

labelCloud旨在实现多功能使用，支持常见的点云文件格式及用于存储3D边界框的标签格式。该工具设计灵活，易于适应多种应用场景。欢迎界面会提示输入最常用的参数（模式、类别、导出格式）。

如需更多配置，可编辑labels/_classes.json文件以配置标签类别，或编辑config.ini文件以进行全局设置（参见配置以获取所有参数的说明）。

支持的导入格式

类型	文件格式
彩色	*.pcd, *.ply, *.pts, *.xyzrgb
无色	*.xyz, *.xyzn, *.bin (KITTI)

支持的导出格式

标签格式	描述
centroid_rel	质心 [x, y, z]; 尺寸 [长度, 宽度, 高度]; 相对旋转以弧度表示的欧拉角 (-π..+π) [yaw, pitch, roll]
centroid_abs	质心 [x, y, z]; 尺寸 [长度, 宽度, 高度]; 绝对旋转以度表示的欧拉角 (0..360°) [yaw, pitch, roll]
vertices	边界框的8个顶点，每个顶点包含 [x, y, z]（顺序参见约定）
kitti	质心；尺寸；z轴旋转（参见KITTI规范）；需要标定文件
kitti_untransformed	如上所述，但不进行任何变换（如果您只想使用相同的标签结构）。

您可以通过继承抽象类BaseLabelFormat轻松创建自己的导出器。所有旋转均为逆时针方向（即90°/π的z轴旋转是从正x轴到负y轴的方向！）。

快捷键

快捷键	描述
导航
左键鼠标	围绕点云质心旋转相机
右键鼠标	平移相机
鼠标滚轮	缩放点云
修正
W、A、S、D	分别向后、向左、向前、向右平移边界框
Ctrl + 右键鼠标	在所有维度上平移边界框
Q、E	上升、下降边界框
Z、X	绕z轴旋转边界框
C、V	绕y轴旋转边界框
B、N	绕x轴旋转边界框
I/ O	增加/减少边界框长度
K/ L	增加/减少边界框宽度
,/ .	增加/减少边界框高度
用光标在边界框边上滚动（“边拉”）	改变边界框的尺寸
R/左, F/右	切换到前一个/后一个样本
T/上, G/下	切换到前一个/后一个边界框
Y、H	将当前边界框类别切换为列表中的前一个/后一个
1-9	使用数字键选择前9个边界框
通用
Del	删除当前边界框
P/Home	重置视角
Esc	取消选中的点

有关软件构建原则，请参阅约定。

使用与引用

在使用本工具时，欢迎您通过电子邮件（christoph.sager[at]gmail.com）向我反馈或描述您的使用场景。如果您将本工具用于科研项目，请考虑引用我们的论文：

# CAD期刊
@article{Sager_2022,
    doi = {10.14733/cadaps.2022.1191-1206},
    url = {http://cad-journal.net/files/vol_19/CAD_19(6)_2022_1191-1206.pdf},
    year = 2022,
    month = {mar},
    publisher = {{CAD} Solutions, {LLC}},
    volume = {19},
    number = {6},
    pages = {1191--1206},
    author = {Christoph Sager和Patrick Zschech和Niklas Kuhl},
    title = {{labelCloud}: 一种适用于点云中领域无关的3D目标检测的轻量级标注工具},
    journal = {计算机辅助设计与应用}
}

# CAD会议
@misc{sager2021labelcloud,
  title={labelCloud：一种用于点云中3D目标检测的轻量级、领域无关的标注工具},
  author={Christoph Sager和Patrick Zschech和Niklas Kühl},
  year={2021},
  eprint={2103.04970},
  archivePrefix={arXiv},
  primaryClass={cs.CV}
}

致谢

我要感谢Robotron RCV团队在软件准备和用户评估方面给予的支持。 该软件是我作为学位论文的一部分开发的，论文题目为“labelCloud：用于点云中3D目标检测的标注工具的开发”，工作地点是德累斯顿工业大学的商业信息学系，尤其是智能系统教研室。我们正在进行的相关研究可以在我们的ResearchGate项目中跟踪。

labelCloud 快速上手指南

labelCloud 是一款轻量级的开源工具，专为在点云数据中标注 3D 边界框（3D Bounding Boxes）而设计。它支持多种点云格式和标注模式，适用于自动驾驶、机器人感知等领域的 3D 物体检测数据准备。

环境准备

• 操作系统：支持 Windows, macOS, Linux。
• Python 版本：要求 Python 3.7 至 3.9。
  • 注意：Python 3.10 及以上版本可能尚未完全兼容，建议使用虚拟环境安装指定版本。
• 前置依赖：
  • 确保已安装 pip 包管理工具。
  • 建议安装 numpy 和 PyQt5（通常由安装脚本自动处理）。

安装步骤

你可以选择通过 PyPI 直接安装（推荐），或从源码安装。

方式一：通过 pip 安装（推荐）

这是最快捷的方式。国内用户若遇到下载缓慢，可添加清华或阿里镜像源。

# 使用默认源安装
pip install labelCloud

# 或使用国内镜像加速安装（推荐）
pip install labelCloud -i https://pypi.tuna.tsinghua.edu.cn/simple

安装完成后，运行以下命令启动示例项目以验证安装：

labelCloud --example

方式二：通过 Git 源码安装

如果你需要修改代码或使用最新开发版：

# 1. 克隆仓库
git clone https://github.com/ch-sa/labelCloud.git
cd labelCloud

# 2. 安装依赖（国内用户可替换 pip 源）
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

# 3. 将你的点云文件放入 `pointclouds` 文件夹

# 4. 启动工具
python3 labelCloud.py

配置提示：启动前可通过编辑根目录下的 config.ini 文件或软件内的设置菜单，自定义类别、导出格式等参数。

基本使用

启动工具后，你将看到欢迎对话框，可选择标注模式和导出格式。以下是核心操作流程：

1. 选择标注模式

labelCloud 提供两种主要标注方式：

• Picking Mode（拾取模式）：适合快速标注。点击确定边界框的前上角位置，滚动鼠标滚轮调整 Z 轴旋转角度。
• Spanning Mode（跨度模式）：适合精确标注。依次点击四个顶点来确定长、宽、高。后两个顶点的选择平面会被锁定，便于操作。

2. 调整与修正

标注过程中，可使用快捷键或左侧按钮对边界框进行微调：

• 移动：使用 W, A, S, D 前后左右移动；Q, E 上下移动。
• 旋转：使用 Z, X (Z 轴), C, V (Y 轴), B, N (X 轴) 进行旋转。
  • 注：默认仅允许 Z 轴旋转。若需 9 自由度（9 DoF）全向旋转，请在菜单或 config.ini 中关闭 "z-Rotation Only Mode"。
• 缩放：将鼠标悬停在边界框某一边上并滚动滚轮，可直接拉伸该维度；或使用 I/O (长), K/L (宽), ,/. (高) 快捷键。

3. 语义分割（可选）

若需生成基于边界框的语义分割标签：

1. 在启动对话框中勾选 Segmentation 模式。
2. 标注完成后，点击 Assign 按钮，当前框内的所有点将被标记为当前类别。
3. 结果将保存为 labels/segmentation/ 目录下的 *.bin 文件。

4. 保存与导出

完成标注后，工具会自动根据配置将标签保存为支持的格式（如 centroid_rel, kitti, vertices 等）。支持导入 .pcd, .ply, .xyz, .bin (KITTI) 等多种点云格式。

常用快捷键速查

操作	快捷键
导航	左键旋转视角，右键平移视角，滚轮缩放
切换样本	R / Left (上一个), F / Right (下一个)
删除框	Del
重置视角	P 或 Home
取消选择	Esc

更多详细配置和约定请参考官方文档：https://ch-sa.github.io/labelCloud/