在Ubuntu 20.04上部署SUSTechPOINTS点云标注工具的完整实战指南

自动驾驶和机器人领域的开发者们，是否曾为寻找一款高效、易用的3D点云标注工具而烦恼？SUSTechPOINTS作为一款开源的3D点云边界框标注工具，正逐渐成为行业内的热门选择。本文将带你从零开始，在Ubuntu 20.04系统上完成SUSTechPOINTS的完整部署，特别针对安装过程中可能遇到的gcc版本冲突等"坑"提供详细解决方案。

1. 环境准备与Docker配置

在开始之前，请确保你的Ubuntu 20.04系统已更新至最新状态。打开终端，执行以下命令进行系统更新：

sudo apt update && sudo apt upgrade -y

1.1 Docker引擎安装

SUSTechPOINTS推荐使用Docker容器运行，这能有效隔离环境依赖。以下是Docker的安装步骤：

1. 安装必要的依赖包：

   sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
   

2. 添加Docker官方GPG密钥：

   curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
   

3. 添加Docker仓库：

   sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu focal stable"
   

4. 安装Docker CE：

   sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io
   

安装完成后，验证Docker是否正常运行：

sudo systemctl status docker

1.2 解决常见Docker权限问题

许多用户在初次使用Docker时会遇到权限不足的问题。以下是解决方案：

• 将当前用户加入docker组：

  sudo usermod -aG docker ${USER}
  

• 使组变更生效（需要重新登录或执行）：

  newgrp docker
  

• 验证权限：

  docker run hello-world
  

如果看到"Hello from Docker!"消息，说明配置成功。

2. SUSTechPOINTS项目部署

2.1 克隆项目仓库

选择一个合适的目录，克隆SUSTechPOINTS源码：

git clone https://github.com/naurril/SUSTechPOINTS
cd SUSTechPOINTS

2.2 构建Docker镜像

项目提供了Dockerfile用于构建定制镜像：

cd Docker
sudo docker build -t sustechpoints:v1.0.0 .

构建过程可能需要几分钟时间，取决于网络速度和系统性能。

2.3 创建并运行容器

成功构建镜像后，创建容器实例：

sudo docker run -it -d --restart=always --name STPointsServer \
-p 8081:8081 -v $(pwd)/../data:/app/data sustechpoints:v1.0.0 bash

参数说明：

参数	说明
-it	交互式终端
-d	后台运行
--restart=always	自动重启
--name	容器名称
-p 8081:8081	端口映射
-v	数据卷挂载

注意：确保 data 目录存在且包含 example 文件夹，这是标注工具的示例数据。

2.4 容器管理技巧

遇到容器冲突时的处理方法：

1. 查看运行中的容器：

   sudo docker ps
   

2. 停止冲突容器：

   sudo docker stop <容器ID>
   

3. 删除已停止的容器：

   sudo docker rm <容器名称或ID>
   

3. 解决uWSGI安装问题

3.1 gcc版本冲突分析

SUSTechPOINTS依赖uWSGI服务，但在Ubuntu 20.04上直接安装常因gcc版本过高导致编译失败。这是因为：

• Ubuntu 20.04默认gcc版本为9.x
• uWSGI某些组件需要较低版本的gcc

3.2 gcc降级方案

推荐使用conda管理gcc环境：

1. 安装Miniconda（如未安装）：

   wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
   bash Miniconda3-latest-Linux-x86_64.sh
   

2. 创建专用环境：

   conda create -n sustech python=3.8
   conda activate sustech
   

3. 安装兼容的gcc版本：

   conda install -c anaconda gcc_linux-64
   

4. 验证gcc版本：

   gcc --version
   

   应显示版本为7.x或更低

3.3 安装uWSGI

在conda环境中执行：

pip install uwsgi

4. 项目配置与启动

4.1 安装Python依赖

进入项目目录，安装所需依赖：

pip install -r requirements.txt

4.2 下载预训练模型

从项目发布页下载模型文件：

wget https://github.com/naurril/SUSTechPOINTS/releases/download/0.1/deep_annotation_inference.h5
mkdir -p .algols/models
mv deep_annotation_inference.h5 .algols/models/

4.3 启动服务

在项目根目录执行：

python ./main.py

服务启动后，通过浏览器访问：

http://127.0.0.1:8081

5. 数据准备与标注实践

5.1 理解示例数据结构

SUSTechPOINTS的 data/example 目录包含标准格式的示例数据，结构如下：

example/
├── image/          # 2D图像数据
├── label/          # 标注文件
├── calib/          # 校准参数
└── velodyne/       # 点云数据

5.2 准备自定义数据

要标注自己的点云数据，需按照相同结构组织：

1. 在 data 目录下创建新文件夹
2. 按上述结构组织子目录
3. 确保点云文件为 .bin 格式

5.3 标注操作指南

• 加载数据 ：界面左上角选择你的数据文件夹
• 创建标注 ：右键点击目标 → 选择"New" → 指定类别和名称
• 调整边界框 ：使用鼠标拖动控制点
• 保存标注 ：自动保存到 label 目录

6. 性能优化与高级配置

6.1 容器资源分配

通过Docker限制资源使用，防止标注工具占用过多系统资源：

sudo docker update --memory 4G --memory-swap 6G STPointsServer

6.2 网络配置

如果需要从其他设备访问标注工具，修改端口绑定：

sudo docker run -it -d -p 0.0.0.0:8081:8081 ...

然后在防火墙中开放8081端口：

sudo ufw allow 8081/tcp

6.3 数据备份策略

为防止标注数据丢失，建议定期备份 data 目录：

tar -czvf sustech_backup_$(date +%Y%m%d).tar.gz /path/to/SUSTechPOINTS/data

7. 常见问题排查

7.1 容器启动失败

现象 ：容器立即退出
解决方案 ：

1. 查看日志：

   sudo docker logs STPointsServer
   

2. 常见原因：
   • 端口冲突 → 更改映射端口
   • 挂载路径错误 → 检查 -v 参数

7.2 标注界面空白

可能原因 ：

• 数据路径不正确
• 点云文件格式不支持

检查步骤 ：

1. 确认浏览器控制台无错误
2. 验证点云文件是否可读

7.3 uWSGI安装失败

即使降级gcc后仍可能遇到的问题：

1. 清理旧安装：

   pip uninstall uwsgi
   rm -rf ~/.cache/pip
   

2. 指定版本安装：

   pip install uwsgi==2.0.20
   

8. 实际应用技巧

在多个自动驾驶项目中，我们发现以下技巧能显著提升标注效率：

• 快捷键使用 ：熟悉界面快捷键可节省大量时间
• 批量处理 ：合理组织数据文件，避免频繁切换
• 质量检查 ：定期抽样检查标注一致性
• 团队协作 ：建立统一的标注规范文档

对于大规模点云标注任务，建议：

1. 将数据分割为多个子集
2. 使用脚本自动化数据准备过程
3. 建立标注-检查-修正的工作流程