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
git clone -b test https://github.com/engine1wu/FAST-Calib.git
项目增强： 为了提升标定效率，我在原项目基础上添加了辅助脚本（位于 scripts 目录），主要用于：
所有相关代码和脚本均已打包在下文提供的 Docker 项目包中。
2. 准备工作
依赖安装
点云距离过滤脚本依赖 Open3D 库，请在宿主机（你的电脑）上安装：
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 秒即可。
录制命令示例
# 请修改为实际的话题名称
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
下载完成后，在终端解压：
# 解压
tar -zxf fast_calib.tar.gz
进入项目主目录，目录结构如下：
.
├── docker-compose-ready.yml # Docker Compose 配置文件
├── FAST-Calib # 项目源代码 (含辅助脚本)
├── fast-calib-docker-image.tar.gz # Docker 镜像离线包
└── import-docker-image.sh # 镜像导入脚本
3. 导入 Docker 镜像
执行一键导入脚本：
# 添加执行权限
chmod +x import-docker-image.sh
# 运行导入脚本
./import-docker-image.sh
导入成功后，执行 docker images 应能看到相关镜像。
4. 启动容器
首先，将录制好的 .bag 文件放入项目的数据目录中，以便容器读取：
# 假设当前在 fast_calib 目录
cd FAST-Calib/calib_data/ && mkdir -p data
cd data
# 将你的 bag 文件移动到这里
mv /path/to/your/bag/my_calib.bag ./
(注：本地 FAST-Calib 目录会挂载到容器内部，实现文件同步)
启动容器：
# 回到项目主目录 fast_calib
cd ../../../
docker-compose -f docker-compose-ready.yml up -d
# 查看运行状态
docker ps
5. 配置图形界面转发与进入容器
为了显示 RViz 界面，需要允许 Docker 使用本地显示服务：
在宿主机终端执行：
xhost +local:docker
进入容器终端：
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 中的点云）：
# 在容器内部终端执行
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
运行脚本：
# 在容器内部终端执行
python3 scripts/extract_image_from_bag.py calib_data/data/my_calib.bag
脚本会默认提取前几秒的图像，保存在 bag 同目录下。 
选择与配置： 挑选一张清晰、无运动模糊、标定板完整的图片（如 my_calib_1.png）。 在 config/qr_params.yaml 中修改 image_path：
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. 编译代码
# 在容器内部执行
cd /root/catkin_ws/
catkin_make
2. 启动程序
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/ 目录。
输出文件说明
- 包含旋转矩阵 (Extrinsic R) 和平移向量 (Extrinsic t)。
- 将图像颜色投射到雷达点云上。这是验证标定效果最直观的方式。
- 检查角点是否被准确提取。
可视化验证
使用 PCL 工具查看彩色点云，检查物体边缘的颜色是否对齐：
# 安装 pcl-tools (如果尚未安装)
sudo apt install pcl-tools
# 查看点云
pcl_viewer colored_cloud.pcd
如果颜色与点云几何结构完美贴合（例如墙上的海报、标定板边缘），则说明标定成功。 
常见问题 QA
- Q: 脚本找不到标定板？
- A: 检查 Distance Filter 的范围是否设置正确，必须包含标定板，且尽量排除背景杂波。
- Q: 图像加载失败？
- A: 检查 image_path 路径是否正确，确保使用了 $(find fast_calib) 前缀或绝对路径。
