3D点云目标检测数据集标注工具 保姆级教程——CVAT （附json转kitti代码）

前言：
笔者尝试过很多3D标注软件都遇到很多问题，例如CloudCompare不适合做3D目标检测的数据集而且分割地面的时很繁琐；labelCloud没有三视图，视角难以调整标得不够精确；SUSTechPOINTS换帧麻烦、输出时存储在docker里面不方便。 CVAT是我这段时间用起来相当丝滑的一个3D目标检测的标注工具了，但是关于CVAT的3D标注教程很少，所以只能自己摸索，最后整理出了这篇教程手册供大家参考。

1. CVAT安装教程

1. 安装Docker

sudo apt-get update
sudo apt-get --no-install-recommends install -y apt-transport-https ca-certificates \
  curl \
  gnupg-agent \
  software-properties-common
 
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository \
  "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) \
  stable"
 
sudo apt-get update
sudo apt-get --no-install-recommends install -y \
  docker-ce docker-ce-cli containerd.io docker-compose-plugin

添加用户到docker组（以便无需sudo运行docker）：

sudo groupadd docker
sudo usermod -aG docker $USER

重启系统以应用docker组的变更。

2. 克隆CVAT源代码：

git clone https://github.com/opencv/cvat
cd cvat

3. 安装chrome（若已安装可跳过）：

cvat推荐只能用chrome浏览器
①安装包下载：

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb

②使用 gdebi 工具自动安装 deb 包和依赖关系：

sudo apt install gdebi
sudo gdebi google-chrome-stable_current_amd64.deb

4. 运行docker容器
   注意是在cvat目录下，第一次会下载需要的镜像
   以后每次开机都需要在这个路径下启动cvat的docker镜像

docker compose up -d

（若docker拉取镜像时出现失败超时，可参考解决方案）

5. 创建一个超级用户

docker exec -it cvat_server bash -ic 'python3 ~/manage.py createsuperuser'

注意在邮箱处可以不填，否则可能报错。

6. 启动CVAT
   在chrome浏览器中输入localhost:8080

2. 3D点云标注详细流程

2.1 创建3D点云标注任务（Task）：

要创建任务，请在 Tasks（任务）页面上单击“+”，选择 Create new task （创建新任务）。

随后页面显示如下：

2.2 指定任务的参数：

1. 在 Name 字段中，输入新任务的名称。
   

2. （可选）从 Projects 下拉列表中，为新任务选择一个项目。
   如果不想将任务分配给任何项目，请将此字段留空（建议）。
   

注意：如果任务不属于项目，则以下步骤有效。
如果任务已分配给项目，则项目的标签将应用于该任务。

3. 在 Constructor 选项卡上，单击 Add label （添加标签）。
   标签构造函数菜单将打开：
   

4. 在 Label name（标签名称）字段中，输入标签的名称。

5. （可选）要将标签的使用限制为特定形状工具， 从 Label shape 下拉菜单中选择形状（默认Any即可）。

6. （可选）选择标签的颜色，建议选择一些区分度比较大的颜色。
   

7. （可选）单击 Add an attribute 并设置其属性。（可以不设置）

8. 单击 Continue 提交标签，就可以在后台保存下来，直接在label name上开始添加新标签，
   
   

单击 Cancel 终止当前标签并返回到标签列表，就会发现添加的标签已经列出来了。

2.3 数据集上传并进入任务job：

1. 单击 Select files （选择文件）的虚线方框区域，或直接将文件拖拽到虚线框，以上传要注释的pcd/bin的压缩文件。（若格式bin，则cvat在标注时会直接转为pcd的格式）
   压缩文件的格式如下：
   
   

注意：文件名尽量做成类似这样以数字序号命名的格式，并且是按照时间排列的顺序，这样便于后续处理。

2. 单击 Submit and open 以提交配置并打开已创建的任务，或 Submit and continue 以提交配置并启动新任务。文件上传成功会有提示：
   

3. 重新点击顶栏的Tasks即可看到新建的标注任务。
   

4. 点击Open进入Jobs页面，再点击job#xx 就可以开始标注了
   

标注工作区界面如下：

2.4 标注说明：

0. （注意：一定要经常保存，以免发生意外情况）

2.4.1. 可使用鼠标或键盘来改变视图：

您还可以使用键盘快捷键操作：

Action	Key
相机旋转	Shift + 箭头（向上、向下、向左、向右）
左/右	Alt+J/ Alt+L
上/下	Alt+U/ Alt+O
放大/缩小	Alt+K/ Alt+I

2.4.2. 使用长方体进行注释

有两个选项可用于3D标注：
• 形状：用于对象检测等任务。
• Track：使用插值来预测对象在后续帧中的位置。 将为每个对象分配一个唯一 ID，并在整个图像序列中维护。（更推荐，效率高）

1）使用shape方式进行批注（适合帧间目标不连续的情况）

要添加3D形状，请执行以下操作：

1. 在对象窗格上，选择 Draw new cuboid>从下拉列表中选择标签>shape.
   

2. 光标后面将跟着一个cuboid。 双击对应的位置，将长方体放置在3D场景中。
   

3. 使用投影调整长方体。 单击并按住鼠标左键可编辑投影上的标签形状。
   

4. （可选）移动四个点中的一个以更改长方体的大小。
   

5. （可选）要旋转长方体，请单击中间点 ，然后向上/向下或向左/向右拖动长方体。
   

6. （可选）若相邻多帧均有相似大小的物体，可以选择传播（propagrate）当前帧的包围框到后续多帧以提高标注效率。
   

（图中笔者是从第9帧开始的，传播了10帧，故到第19帧）

2）使用track方式进行批注（适合帧间目标连续的情况）

数据集中的文件若是按照采样时间顺序来排列，则可以根据物体在帧间移动的轨迹进行插值，从而大大节省人力。

1. 在对象窗格上，选择 Draw new cuboid>从下拉列表中选择标签>track.
   

2. 为对象创建track（轨迹）（以所选container为例）：
   通过单击创建，然后调整3D包围框
   

3. 但是此时会发现后面所有帧都被标注了3D框，且越往后偏离越大：
   
   
   

对于这种问题，CVAT中具有自动插值的功能，通过选取一些关键帧（点击标注界面右侧的label状态栏的符号空心的五角星使其变成实心的五角星，即可将该帧变为关键帧），只需要将关键帧内的包围框手动对齐，然后就会发现关键帧之间的包围框便可以自动移动到了比较合适的位置，进而只需要微调就可以了。

4. 结束当前目标的轨迹
   如图所示点击标注界面右侧的label状态栏的Switch Outside Property的按钮，即可终止后续帧track的操作，（注：操作了这一按钮的那一帧中对应的包围框也会消失失效）
   
   

5. 如果对象只是在几个帧上不可见，然后再次出现，可以使用Merge功能合并多个单独的track合二为一，从而保证同一物体在不同帧中对应ID的一致性。
   

① 这里以图像标注为例，为骑行者可见的时刻创建轨迹：

② 单击Merge按钮，然后再单击第一个track的任意矩形以及第二个track的任意矩形，依此类推：

③结束时再单击Merge按钮，使更改生效。这样就统一了数据集中同一物体在不同帧中的id了。

2.5 导出标注结果

1. Save整个工程后，重新进入Task的界面，点击Export annotations：
   

2. 输出格式调整为Datumaro 3D 1.0，它自带的kitti输出的格式会有bug（没有帧信息），save images 的开关打开以保存原始点云数据
   

3. 如图点击顶栏跳到Requests中，然后点击刚刚导出的工程download即可
   

4. 最终下载的是一个zip的压缩包，内容如下：
   
   
   这种格式可以通过python脚本来转成KITTI数据集的格式，代码我放在最后了。

5. 最后记得将整个task也做一个备份留存以供后续的二次开发

3. 标注文件格式转换代码——Datumaro 3D（json）转KITTI格式

import json
import os

def json_to_kitti(json_path, output_dir):

    with open(json_path, 'r') as f:
        data = json.load(f)

    labels = data['categories']['label']['labels']

    os.makedirs(output_dir, exist_ok=True)

    # 遍历每一帧
    for item in data['items']:
        item_id = item['id']  # 使用 JSON 中的 'id' 值
        annotations = item['annotations']

        # 输出 KITTI 格式文件的路径，使用 'id' 命名
        output_path = f"{output_dir}/{item_id}.txt"
        
        with open(output_path, 'w') as f_out:
            # 遍历每个标注
            for annotation in annotations:
                label_id = annotation['label_id']
                label_name = labels[label_id]['name']
                
                # 提取 3D 立方体信息
                position = annotation['position']
                rotation = annotation['rotation']
                scale = annotation['scale']
                
                # KITTI 格式字段
                truncated = 0  # 默认为 0，因为未提供截断信息
                occluded = 1 if annotation['attributes']['occluded'] else 0
                alpha = rotation[2]  # 使用 Z 轴的旋转角作为方向角
                bbox_left = 0.0  # 2D 边界框位置，点云标注中通常为 0
                bbox_top = 0.0
                bbox_right = 0.0
                bbox_bottom = 0.0
                height = scale[2]  # 物体高度
                width = scale[0]   # 物体宽度
                length = scale[1]  # 物体长度
                x = position[0]    # 物体在相机坐标系中的 x 坐标
                y = position[1]    # 物体在相机坐标系中的 y 坐标
                z = position[2]    # 物体在相机坐标系中的 z 坐标
                rotation_y = rotation[2]  # KITTI 中物体绕 Y 轴的旋转角度

                # 将数据写入到 KITTI 格式文件
                f_out.write(f"{label_name} {truncated} {occluded} {alpha} "
                            f"{bbox_left} {bbox_top} {bbox_right} {bbox_bottom} "
                            f"{height} {width} {length} {x} {y} {z} {rotation_y}\n")


json_to_kitti('/home/zpmc/code/demo_study_project/data_convert/default.json', 
              '/home/zpmc/code/demo_study_project/data_convert/kitti_labels')

参考链接： https://blog.csdn.net/wxtcstt/article/details/134601044
https://docs.cvat.ai/docs/