FAST-Calib 激光雷达与相机联合标定教程 (Docker版)

FAST-Calib 激光雷达与相机联合标定实战教程 (Docker版)

1. 前言与致谢

致谢：本教程核心算法源自开源项目 FAST-Calib (GitHub: hku-mars/FAST-Calib)，在此对原作者表示诚挚的感谢。

背景说明 ：

本教程旨在解决 Ubuntu 22.04 等高版本系统无法直接安装 ROS Noetic (ROS1) 从而难以运行 FAST-Calib 的问题。通过 Docker 容器化部署，我们可以在任意支持 Docker 的系统上快速复现标定环境。

如果你使用的是 Ubuntu 20.04 ，系统原生支持 ROS Noetic，也可以直接参考我的测试分支进行安装：https://github.com/engine1wu/FAST-Calib/tree/test

bash 复制代码

git clone -b test https://github.com/engine1wu/FAST-Calib.git

项目增强 ：

为了提升标定效率，我在原项目基础上添加了辅助脚本（位于 scripts 目录），主要用于：

点云距离过滤：交互式提取标定板周围点云范围。
图像提取：从 Rosbag 中提取清晰的标定图像。

所有相关代码和脚本均已打包在下文提供的 Docker 项目包中。

2. 准备工作

依赖安装

点云距离过滤脚本依赖 Open3D 库，请在宿主机（你的电脑）上安装：

bash 复制代码

pip3 install open3d

数据录制 (Rosbag)

注意：只有确保雷达和相机的采样时间同步，标定才有效。

在进行标定前，需要录制包含传感器数据的 rosbag。请确保标定过程中保持传感器和标定板完全静止。

录制要求

必须包含的话题 ：
- LiDAR 点云 ：sensor_msgs/PointCloud2 或 livox_ros_driver/CustomMsg (例如 /livox/lidar, /hesai/pandar)
- 相机图像 ：sensor_msgs/Image 或 sensor_msgs/CompressedImage (例如 /camera/image_color, /usb_cam/image_raw)
时长：录制 5-10 秒即可。

录制命令示例

bash 复制代码

# 请修改为实际的话题名称
rosbag record /livox/lidar /camera/image_color -O my_calib.bag

3. FAST-Calib 项目部署 (Docker环境)

1. 环境准备

确保已安装 docker 和 docker compose。

(注：Docker 版本不强制，但建议 Docker Compose 保持较新版本)

2. 下载项目包

请下载整合了 Docker 镜像与源代码的压缩包 fast_calib.tar.gz：

百度网盘下载

链接 : https://pan.baidu.com/s/1Lur-kqS7RM2uyHjDfQ3uZw

提取码 : adwm

下载完成后，在终端解压：

bash 复制代码

# 解压
tar -zxf fast_calib.tar.gz

bash 复制代码

.
├── docker-compose-ready.yml     # Docker Compose 配置文件
├── FAST-Calib                   # 项目源代码 (含辅助脚本)
├── fast-calib-docker-image.tar.gz # Docker 镜像离线包
└── import-docker-image.sh       # 镜像导入脚本

3. 导入 Docker 镜像

执行一键导入脚本：

bash 复制代码

# 添加执行权限
chmod +x import-docker-image.sh
# 运行导入脚本
./import-docker-image.sh

导入成功后，执行 docker images 应能看到相关镜像。

4. 启动容器

首先，将录制好的 .bag 文件放入项目的数据目录中，以便容器读取：

bash 复制代码

# 假设当前在 fast_calib 目录
cd FAST-Calib/calib_data/ && mkdir -p data
cd data
# 将你的 bag 文件移动到这里
mv /path/to/your/bag/my_calib.bag ./

(注：本地 FAST-Calib 目录会挂载到容器内部，实现文件同步)

启动容器：

bash 复制代码

# 回到项目主目录 fast_calib
cd ../../../
docker-compose -f docker-compose-ready.yml up -d

# 查看运行状态
docker ps

5. 配置图形界面转发与进入容器

为了显示 RViz 界面，需要允许 Docker 使用本地显示服务：

在宿主机终端执行：

bash 复制代码

xhost +local:docker

进入容器终端：

bash 复制代码

docker exec -it fast-calib-ready /bin/bash

关于 docker exec 的简要说明：

此命令在运行中的容器内启动一个新的 bash 会话。
-it 参数让你能够与容器终端进行交互。
此时你的终端环境已切换到容器内部，操作均在容器中进行。
输入 exit 可退出容器终端（容器本身仍会在后台运行）。

测试图形界面 ：

在容器终端内输入 rviz，如果能弹出 RViz 窗口，说明环境配置成功。

4. 参数配置与标定流程

所有的配置均在 config/qr_params.yaml 文件中进行。你需要根据实际硬件和场景修改以下参数。

注：建议直接在宿主机使用编辑器（如 VS Code）打开 FAST-Calib/config/qr_params.yaml 进行修改，保存后容器内会自动生效。

A. 相机模型与内参 (Camera Intrinsics)

填写相机的标定参数。若未标定，请先使用 camera_calibration 等工具获取。

cam_model: 相机模型，通常为 "pinhole" (针孔) 或 "fisheye" (鱼眼)。
fx, fy: 焦距 (像素单位)。
cx, cy: 主点坐标 (图像中心)。
k1, k2, p1, p2: 畸变系数。

B. 标定板参数 (Calibration Target)

根据标定板的实际物理尺寸填写，单位为 米 (m)。

marker_size: 二维码边长。
circle_radius: 圆形特征半径。
delta_width/height...: 标记间的距离。

(注：如果使用配套的标准标定板，通常无需修改此部分)

C. 点云距离过滤 (Distance Filter) ------ 关键步骤

我们需要设置一个包围盒（Bounding Box），只保留标定板周围的点云，过滤掉背景干扰。

使用辅助脚本 ：scripts/distance_filter_tool.py

运行脚本（自动读取 bag 中的点云）：

bash 复制代码

# 在容器内部终端执行
cd /root/catkin_ws/src/fast_calib

# 语法：python3 scripts/distance_filter_tool.py [bag相对路径]
python3 scripts/distance_filter_tool.py calib_data/data/my_calib.bag

(脚本会自动检测点云话题，无需指定)

交互选点 (Open3D 界面)：
- 操作：按住 Shift + 鼠标左键 点击点云。
- 目标：在标定板的 上、下、左、右 空间各点击一下（至少4个点），形成一个包围标定板的区域。
- 调整视角 ：鼠标左键旋转，滚轮平移/缩放。如果点云太密导致卡顿，可按 - 键减少点数。
- 完成：选好点后，按 Q 键退出。
获取参数 ：

脚本会在 bag 同目录下生成 .txt 文件。打开它，复制 x_min, x_max 等 6 个值。
填入配置 ：

将这 6 个值填入 config/qr_params.yaml 的 Distance filter 部分。

D. 提取静态标定图像

程序需要一张清晰的静态图片用于角点检测。

使用辅助脚本 ：scripts/extract_image_from_bag.py

运行脚本：
bash 复制代码
```
# 在容器内部终端执行
python3 scripts/extract_image_from_bag.py calib_data/data/my_calib.bag
```
脚本会默认提取前几秒的图像，保存在 bag 同目录下。
选择与配置 ：

挑选一张清晰、无运动模糊、标定板完整 的图片（如 my_calib_1.png）。

在 config/qr_params.yaml 中修改 image_path：
yaml 复制代码
```
image_path: "$(find fast_calib)/calib_data/data/my_calib_1.png"
```

E. 确认输入路径

最后检查 config/qr_params.yaml 底部配置：

lidar_topic: 你的雷达话题名 (如 /livox/lidar)。
bag_path: 你的 .bag 文件路径。
image_path: 你选择的 .png 图片路径。

5. 运行标定

1. 编译代码

bash 复制代码

# 在容器内部执行
cd /root/catkin_ws/
catkin_make

2. 启动程序

bash 复制代码

source ~/.bashrc
roslaunch fast_calib calib.launch

3. 查看结果

程序启动后会自动打开 RViz。你应该能看到：

白色点云：原始雷达数据。
绿色/红色平面：算法检测到的标定板位置。
终端输出：实时检测进度和 RMSE 误差值。

关于 RMSE (均方根误差)：

含义：雷达特征点投影到相机图像后的平均距离误差。
评价标准 ：
- < 1 cm (0.01m): 极好，精度极高。
- 1-3 cm: 一般，可用。
- > 3 cm: 较差，建议重做标定或检查内参。
图中 0.0018m (1.8mm) 表示标定结果非常精确。

6. 结果验证与输出

标定结果默认保存在 output/ 目录。

输出文件说明

single_calib_result.txt : 最终结果 。
- 包含旋转矩阵 (Extrinsic R) 和平移向量 (Extrinsic t)。
colored_cloud.pcd : 彩色点云 。
- 将图像颜色投射到雷达点云上。这是验证标定效果最直观的方式。
qr_detect.png : 标定板检测图。
- 检查角点是否被准确提取。

可视化验证

使用 PCL 工具查看彩色点云，检查物体边缘的颜色是否对齐：

bash 复制代码

# 安装 pcl-tools (如果尚未安装)
sudo apt install pcl-tools

# 查看点云
pcl_viewer colored_cloud.pcd

如果颜色与点云几何结构完美贴合（例如墙上的海报、标定板边缘），则说明标定成功。

常见问题 QA

Q: 脚本找不到标定板？
- A: 检查 Distance Filter 的范围是否设置正确，必须包含标定板，且尽量排除背景杂波。
Q: 图像加载失败？
- A: 检查 image_path 路径是否正确，确保使用了 $(find fast_calib) 前缀或绝对路径。