3D 点云标注
3D 点云是由大量三维空间中的点组成的数据，每个点包含 X、Y、Z 坐标，还可带有颜色、强度等信息。点云通常由激光雷达、深度相机等设备采集，用于描述物体的形状和场景的空间结构。
X-AnyLabeling 支持 3D 目标检测、语义分割和实例分割标注：用 3D 框标出车辆、行人等感兴趣目标的位置、尺寸与朝向；逐点标注道路、建筑等类别；或进一步区分同一类别中的不同对象，例如两辆车。可用于自动驾驶环境感知、机器人导航、三维场景理解等任务的数据集制作。
3D 点云工作区
加载界面
点击 X-AnyLabeling 主窗口左侧工具栏中的点云图标，或按 Ctrl+6，即可打开 3D 点云工作区。
整个 3D 点云工作区大致分为以下几部分：
- 顶部操作栏：创建任务、导入与导出标注，以及另存当前帧标注。
- 左侧文件列表：查看点云文件并切换待标注的帧。
- 中间标注区域：包含工具栏和 3D 画布，用于浏览点云和执行标注；检测任务还提供俯视、侧视和前视三视图，方便调整 3D 框。
- 右侧管理面板：管理标注类别，以及检测框或分割实例，支持控制显隐、锁定等操作。
- 底部状态栏：查看当前帧信息和标注保存状态。
悬停工具栏图标可查看功能提示，点击窗口右上角的 ⌘ 图标可查看工作区快捷键。
创建任务
进入工作区后，首先点击顶部菜单栏的创建任务按钮，依次完成以下三步：
- 选择任务类型与类别：根据需求自行选择相应的任务类别，添加标注类别，或加载自定义类别文件。需要保存类别时，点击底部左侧的 Save labels（保存标签），自行选择保存目录和 JSON 文件名。
- 选择数据与保存目录：选择点云文件所在目录，并按需设置标注保存目录；留空时默认保存到点云所在目录。
- 配置相机数据（可选）：按需添加相机图像目录和标定文件，无需图像辅助时可跳过。
完成后点击 Create task，即可加载点云并开始标注。
文件格式
点云文件格式
当前检测与分割均支持以下三种点云格式：
| 格式 | 要求 |
|---|---|
.bin | 每点包含 X、Y、Z、强度四个小端 float32 数值，共 16 字节。 |
.ply | 包含 x、y、z 坐标，可附带颜色和强度。 |
.pcd | 支持 PCD v0.5/v0.7，以及 ASCII、binary 和 binary_compressed 数据；必须包含 x、y、z，可附带 intensity 和打包的 rgb/rgba。 |
类别文件格式
用户可以在创建任务第一步点击 Save labels（保存标签），选择保存目录和文件名，将当前任务的类别保存为 JSON 文件。文件包含类别编号、名称与颜色，检测与分割分别使用 detection 和 segmentation 节点，示例如下：
{
"version": 1,
"detection": {
"classes": [
{"id": 1, "name": "Car", "color": "#6496F5"}
]
},
"segmentation": {
"classes": [
{"id": 0, "name": "unlabeled", "color": "#000000"},
{"id": 10, "name": "car", "color": "#6496F5"}
]
}
}
id 为类别编号，name 为类别名称，color 为 #RRGGBB 颜色。分割类别必须包含编号 0，表示未标注；检测框不能使用编号 0。文件可只包含当前任务的节点，完整配置可参考示例类别文件。
基础操作
加载点云后，先按 V 切换到浏览模式，在中间的 3D 画布中调整视角：
- 左键拖动：旋转视角。左右拖动调整偏航（Yaw），上下拖动调整俯仰（Pitch）。
- 右键或中键拖动：平移整个视图，方便查看点云的不同区域。
- 滚轮：放大或缩小视图。
- 适应视图：按
F将整帧点云显示在画布中；也可点击工具栏的俯视、前视、侧视或重置视角按钮。
在左侧文件列表中点击文件即可切换帧，也可按 A / D 查看上一帧或下一帧。右侧类别和对象列表用于选择标注目标，眼睛图标控制显隐，锁图标控制是否允许编辑。标注后可在底部状态栏查看保存状态。
分割时，左键用于笔刷涂抹或多边形圈选，需要旋转视角时先切回浏览模式。检测任务的三视图中，拖动框体或节点用于调整标注，按住 Ctrl 配合左键拖动，或使用中键拖动，可平移视图。
快捷操作
使用快捷键前，先点击对应画布使其获得焦点。下表列出工作区现有的快捷操作；撤销和重做使用系统默认组合键，实际显示可在右上角的 ⌘ 面板中查看。
| 快捷键 / 操作 | 功能 | 适用范围 |
|---|---|---|
V | 切换到浏览模式 | 通用 |
A / PgUp | 上一帧 | 通用 |
D / PgDown | 下一帧 | 通用 |
F | 显示整帧点云 | 通用 |
Ctrl+Z | 撤销上一步标注操作 | 通用 |
Ctrl+Shift+Z / Ctrl+Y | 重做，具体组合键取决于系统 | 通用 |
Esc | 取消未完成的选择、绘制或框调整 | 分割 / 检测 |
Alt+U / Alt+O | 向上 / 向下移动相机 | 3D 视角 |
Alt+J / Alt+L | 向左 / 向右移动相机 | 3D 视角 |
Alt+I / Alt+K | 放大 / 缩小视图 | 3D 视角 |
Shift+↑ / Shift+↓ | 向上 / 向下调整俯仰 | 3D 视角 |
Shift+← / Shift+→ | 向左 / 向右旋转视角 | 3D 视角 |
B | 切换到笔刷工具 | 分割 |
P | 切换到多边形工具 | 分割 |
Ctrl+滚轮 | 调整笔刷大小 | 分割：笔刷工具 |
Ctrl+左键拖动 / 右键拖动 | 平移视图并保留未完成的多边形 | 分割：多边形工具 |
Enter / 左键双击 | 完成多边形圈选 | 分割：多边形工具 |
N | 开始或取消绘制 3D 框 | 检测 |
| 左键双击 | 在预览位置创建 3D 框 | 检测：3D 画布绘制模式 |
G | 聚焦选中的 3D 框 | 检测 |
Delete | 删除选中的 3D 框 | 检测 |
Ctrl+D | 复制选中的 3D 框 | 检测 |
Ctrl+C / Ctrl+V | 复制 / 粘贴 3D 框 | 检测 |
↑ / ↓ / ← / → | 沿当前视图方向移动选中的框，每次 0.1 个坐标单位 | 检测 |
| 左键或右键拖动框体 / 节点 | 移动框、调整尺寸或旋转 | 检测：三视图 |
Shift+拖动旋转节点 | 按 15° 步长调整朝向 | 检测：三视图 |
Ctrl+左键拖动 / 中键拖动 | 平移视图 | 检测：三视图 |
3D 点云检测
检测任务使用 3D 框标注目标的类别、位置、尺寸和朝向。
示例数据
仓库提供 KITTI 3D 检测最小示例，使用训练集的 000008 帧，包含 122,555 个点、一张左侧彩色相机图像和 6 个 Car 检测框。
assets/pointcloud/detection/KITTI_3D_det/
├── velodyne/000008.bin # 原始 XYZI 点云
├── labels/000008.cuboids.json # 工作区检测框
├── image_02/000008.png # 对应相机图像
├── calibration.json # 对应 image_02 的标定
└── source/
├── calib/000008.txt # KITTI 原始标定
└── label_2/000008.txt # KITTI 原始标签
创建任务时按以下方式配置，即可加载已有检测框：
- 选择 Det，加载共用的类别文件。检测类别包括 Car、Pedestrian 和 Cyclist，本帧只有 Car。
- 点云目录选择
assets/pointcloud/detection/KITTI_3D_det，标注保存目录选择其中的labels目录。 - 添加一路相机，图像目录选择
image_02，标定文件选择calibration.json，完成创建后即可查看叠加效果。
添加其他帧时，点云、检测框和图像使用相同文件名主体，例如 000009.bin、000009.cuboids.json 和 000009.png。只标注点云时可省略相机数据。
KITTI 检测集为每帧提供独立标定，多帧共用一个标定文件前需确认相机参数一致，否则应分别配置任务。
转换说明
示例的点云和图像保持原样，检测框与标定已转换为工作区格式：
- 原始框位于整流相机坐标系，位置为底面中心。先沿相机 Y 轴减去半个高度得到框中心，再通过
R0_rect × Tr_velo_to_cam的逆变换转到点云坐标系。 size保存为[length, width, height]，朝向转换到点云坐标系，以 XYZ 欧拉角保存，单位为弧度。- 相机内参取自
P2的左侧 3×3 矩阵，平移项并入外参，保持投影与P2 × R0_rect × Tr_velo_to_cam一致。 DontCare忽略区域不生成 3D 框；遮挡值 1、2 转为occluded: true，0、3 转为false。完整遮挡状态、截断率和 2D 框保留在原始 TXT 中。
数据来源
示例来自 KITTI 3D Object Detection，作者为 Andreas Geiger、Philip Lenz 和 Raquel Urtasun，相关论文为 Are we ready for Autonomous Driving? The KITTI Vision Benchmark Suite（CVPR 2012）。原始文件取自官方压缩包：
| 压缩包 | 原始文件 |
|---|---|
| data_object_velodyne.zip | training/velodyne/000008.bin |
| data_object_image_2.zip | training/image_2/000008.png |
| data_object_calib.zip | training/calib/000008.txt |
| data_object_label_2.zip | training/label_2/000008.txt |
KITTI 数据及转换标注遵循 CC BY-NC-SA 3.0，详见 KITTI 官方版权说明。
创建对象
- 在右侧 Labels（类别） 中选择目标类别。
- 将鼠标移到 3D 画布，按
N或点击绘制框按钮，移动预览框到目标位置。 - 左键双击创建对象。也可在下方的俯视、侧视或前视图中拖出矩形创建框，再调整剩余方向的尺寸。
- 创建后检查三个方向，使框尽量贴合目标。按
Esc可取消未完成的绘制。
编辑对象
在 3D 画布或右侧 Objects（对象） 列表中选中框，按 G 聚焦目标。下方三视图会对齐选中框的局部坐标轴，适合分别检查位置、尺寸和朝向。
| 操作 | 方法 |
|---|---|
| 移动 | 在三视图中拖动框体，或按方向键微调。 |
| 调整尺寸 | 拖动框边缘的方形节点。 |
| 调整朝向 | 拖动旋转节点；按住 Shift 可按 15° 步长旋转。 |
| 精确编辑 | 在 Objects 列表右键选择 Edit object（编辑对象），设置类别、中心坐标、尺寸、旋转角度和遮挡状态。 |
| 贴合框内点 | 右键选择 Fit to points（贴合点云），根据当前框内的点收紧边界，保留朝向。框应先覆盖完整目标。 |
俯视、侧视和前视图分别展示框的局部 X/Y、X/Z 和 Y/Z 平面。鼠标移到三视图上时，右上角会出现放大按钮，点击可放大查看，再次点击恢复。
默认按选中框的深度范围裁剪三视图中的点，便于减少前后背景干扰；需要查看周围点时，可关闭 Crop depth to selected cuboid（按选中框裁剪深度）。
管理对象
| 操作 | 方法 |
|---|---|
| 复制当前对象 | 按 Ctrl+D，生成一个略微偏移的新框，再调整到目标位置。 |
| 跨帧复用 | 按 Ctrl+C 复制框，切换到另一帧后按 Ctrl+V 粘贴，再检查位置与尺寸。 |
| 删除 | 选中框后按 Delete，或点击对象行的删除图标。 |
| 锁定 | 点击类别或对象的锁图标，避免误改；编辑前先解锁。 |
| 显示或隐藏 | 使用类别、对象行或标题栏的眼睛图标，控制单个对象或整类对象的显隐。 |
| 撤销与重做 | 使用工具栏按钮或对应快捷键恢复标注操作。 |
跨帧粘贴仅复用框的属性，不会自动跟踪目标；每帧仍需检查。对象编号用于区分当前帧中的框。
相机图像辅助
任务中配置相机图像后，可在右上角查看对应照片；添加标定文件后，还可叠加点云和 3D 框，辅助检查目标位置。
图像与点云按同名配对，例如 000000.bin 对应 000000.png。多路相机分别配置图像目录和标定文件，用相机区域的箭头切换；滚轮缩放图像，拖动左下角可调整面板大小。只查看照片时无需标定。
导入与导出
顶部 Upload（导入） 和 Export（导出） 支持以下三种检测标注格式，均使用 ZIP 文件：
| 格式 | 标注结构 |
|---|---|
| Datumaro 3D | annotations/*.json，使用 cuboid_3d 保存框的位置、旋转和尺寸；本工具导出为 annotations/default.json。 |
| Kitti Raw Format | tracklet_labels.xml 保存框及帧信息；本工具还导出 frame_list.txt 和 dataset_meta.json。 |
| Sly Point Cloud Format | meta.json 定义类别，ds0/ann/*.pcd.json 保存逐帧对象与框，key_id_map.json 保存键映射。 |
导入标注：
- 点击 Upload，选择已有标注 ZIP 和对应格式。
- 核对提示中的帧数、对象数和替换数量，再确认导入。
- 导入后逐帧检查框的位置、尺寸、朝向和类别。
导入的类别名称需包含在当前任务中；缺少类别时，需重新配置任务后再导入。帧通常按文件名匹配，仅提供帧索引的格式按当前序列顺序匹配，因此应保持文件命名和帧顺序一致。
导入会替换匹配帧的全部检测框，包括已锁定的框；未匹配帧和点级分割标注保持原样。需要保留现有结果时，请先备份标注文件。
导出标注：
- 点击 Export，选择 ZIP 保存路径和目标格式。
- 按需勾选 Save images，将点云和已关联的相机图像一起打包；点云会转换为 PCD。
- 点击 OK 完成导出。
导出范围是左侧文件列表中的全部帧。上述格式导出的是检测框，逐点分割结果使用 .label 文件交付。Kitti Raw 导出将每个框写为单帧 tracklet，不会生成跨帧跟踪关系。
检测框文件格式
标注会自动保存为与点云同名的 .cuboids.json，例如 000000.bin 对应 000000.cuboids.json。顶部 Save as（另存为） 可另存当前帧标注。
文件采用 UTF-8 JSON，示例如下：
{
"version": 1,
"type": "pointcloud-cuboids",
"point_cloud": "000000.bin",
"cuboids": [
{
"id": 1,
"class_id": 1,
"center": [5.0, 2.0, 0.8],
"size": [4.5, 1.8, 1.6],
"rotation": [0.0, 0.0, 0.5],
"occluded": false,
"locked": false
}
]
}
| 字段 | 定义 |
|---|---|
version / type | 当前为 1 / pointcloud-cuboids。 |
point_cloud | 原始点云文件名，包含扩展名，加载时须与点云匹配。 |
cuboids | 当前帧的检测框数组，无对象时为空数组。 |
id | 当前帧内唯一的对象编号，范围为 1–65535。 |
class_id | 检测类别编号，范围为 1–65535，对应类别文件。 |
center | 框中心的 [x, y, z]，使用原始点云坐标系。 |
size | 框沿局部 X、Y、Z 轴的尺寸，单位与点云一致，每项至少为 0.01。 |
rotation | [rx, ry, rz]，单位为弧度，旋转矩阵为 Rx(rx) × Ry(ry) × Rz(rz)。属性编辑窗口中显示和输入的是角度。 |
occluded | 是否被遮挡，布尔值。 |
locked | 是否锁定，布尔值。 |
交付或继续标注时，请保留原始点云、逐帧 .cuboids.json 和类别文件。重新加载对应点云与保存目录后，即可继续编辑已有标注。
3D 点云分割
分割任务为每个点赋予语义类别，还可进一步区分同一类别中的不同实例。以下操作适用于已加载的 Seg（分割） 任务。
示例数据
仓库提供点云分割最小示例，包含 2011_10_03_drive_0042_sync 序列的一个点云帧、逐点标签和 4 路相机图像。本帧有 122,829 个点，已有道路、植被等语义标注，以及 5 个 moving-car 实例。
assets/pointcloud/segmentation/2011_10_03_drive_0042_sync/
├── velodyne/0000000000.bin # 原始 XYZI 点云
├── labels/0000000000.label # 逐点语义与实例标签
├── image_00/0000000000.png # 左侧灰度相机
├── image_01/0000000000.png # 右侧灰度相机
├── image_02/0000000000.png # 左侧彩色相机
├── image_03/0000000000.png # 右侧彩色相机
└── calibration.json # 对应 image_02 的标定
创建任务时按以下方式配置，即可加载已有分割标签：
- 选择 Seg，加载共用的类别文件，使用其中的
segmentation类别。 - 点云目录选择
assets/pointcloud/segmentation/2011_10_03_drive_0042_sync，标注保存目录选择其中的labels目录。 - 按需添加相机。使用
image_02时选择calibration.json，可查看点云投影；其他相机可先只加载图像，留空标定。无需图像辅助时可跳过此步。
创建后，可在 Classes 中查看各类点，在 Instances 中选择已有实例，尝试补点、移出点或拆分操作。类别编号 252 表示 moving-car；标签中保留了运动类别，加载时使用示例类别文件即可。
示例中的标定只适用于 image_02，其他相机叠加点云时需提供各自的标定。新增帧时，点云、标签和图像应保持同名，标签的点数和顺序须与原始点云一致。
点云与图像来自 KITTI，分割类别与逐点标签格式参见 SemanticKITTI。相关论文为 SemanticKITTI: A Dataset for Semantic Scene Understanding of LiDAR Sequences（Behley 等，ICCV 2019）。数据遵循 CC BY-NC-SA 3.0，使用时请保留 KITTI 与 SemanticKITTI 的来源说明。
标注语义类别
- 在右侧 Classes（类别） 中选择目标类别，点击 Assign semantic（赋予语义类别）。
- 按
B使用笔刷，按住左键涂抹，松开后完成一次标注；按Ctrl+滚轮调整笔刷大小。 - 或按
P使用多边形工具，沿区域边缘逐点点击，按Enter、双击或点击起点闭合圈选。 - 按
V切回浏览模式，转动视角检查边缘和背面，再继续补画。
重新选择类别并涂抹或圈选，可修改已有点的类别；改变类别时会清除这些点原有的实例编号。需要清除误标时，选择编号 0（未标注），使用 Assign semantic 涂抹或圈选对应区域，语义和实例标签都会清除。
控制选择范围
默认只选择当前视角的表面点，适合沿可见轮廓标注。打开 Through selection（穿透选择） 后，会选中圈选或笔刷范围内各个深度的点，适合一次标注整个目标。
隐藏或锁定的点不会被笔刷和多边形修改。标注密集场景时，可先隐藏无关类别，再从多个视角检查，避免将前后不同目标一起选中。
创建实例
语义分割只区分“是什么”，实例分割还区分“是哪一个”。例如两辆车都属于 car，但应分别创建实例。
- 先为目标点赋予语义类别。
- 在 Classes 中选择该类别，点击 Create instance（创建实例）。
- 使用笔刷或多边形选中一个对象的点，完成后生成一个实例；对下一个对象重复操作。
创建实例只处理选中范围内属于当前类别的点，其他类别会被排除。若选中的点已经属于其他实例，界面会提示确认转移。实例编号在同一类别内分配，使用“类别编号 + 实例编号”确定实例。
编辑与管理实例
先在右侧 Instances（实例） 列表选中目标实例，再选择对应操作：
| 操作 | 方法与效果 |
|---|---|
| 补充点 | 选择 Add to current instance，圈选同类别的点并加入当前实例。 |
| 移出点 | 选择 Remove from current instance，圈选要移出的点；保留语义类别。 |
| 拆分 | 选择 Split current instance，圈选当前实例的一部分，生成同类别的新实例。 |
| 合并 | 按住 Ctrl 多选同类别实例，点击标题栏的合并图标；保留当前行实例的编号。 |
| 定位 | 选中实例后点击标题栏的定位图标，将视图聚焦到目标。 |
| 删除实例 | 点击实例行的删除图标，清除该实例编号；点的语义类别保留。 |
| 锁定 | 点击实例或类别的锁图标，避免误改；编辑前先解锁。 |
合并和删除实例作用于整个实例，包括当前隐藏的点，操作前会提示确认。只需要语义分割时，无需创建实例。
保存与标注文件格式
语义与实例标签一起自动保存到同名 .label 文件，例如 000000.bin 对应 000000.label。类别定义使用前文介绍的类别 JSON 文件中的 segmentation 节点，请在创建任务第一步手动保存。
.label 是无文件头的二进制文件，按原始点云顺序为每个点保存一个小端无符号 32 位整数（uint32）：
| 内容 | 定义 |
|---|---|
| 低 16 位 | 语义类别编号，范围为 0–65535；0 表示未标注。 |
| 高 16 位 | 实例编号，范围为 0–65535；0 表示未分配实例。 |
| 编码 | label = (instance_id << 16) | semantic_id。 |
| 解码 | semantic_id = label & 0xFFFF；instance_id = label >> 16。 |
| 文件大小 | 点数 × 4 字节。 |
例如，类别编号为 10、实例编号为 2 的点，保存值为 (2 << 16) | 10 = 131082；只标注类别时，保存值就是类别编号。
.label 与原始点云逐点对应。标注后请保持点云的点数和顺序，不要直接对点云删点、重排或降采样后复用原标签。
交付时保留原始点云、逐帧 .label 和类别文件。继续标注时，加载对应类别、点云和保存目录，即可读取已有标签。