ROS Noetic 中自定义编译和替换 cv_bridge 的完整指南

写在前面

在 ROS Noetic 开发中，有时我们需要修改或自定义 cv_bridge 的功能包，比如修改图像编码方式、添加自定义的图像转换功能等。然而，系统默认安装的 cv_bridge 位于 /opt/ros/noetic 目录下，直接修改是不推荐的，也不容易维护。

本文将详细介绍如何从源码编译 cv_bridge，并强制让 ROS 使用我们自己编译的版本，而不是系统默认版本。

1. 理解 cv_bridge 的作用

cv_bridge 是 ROS 和 OpenCV 之间的桥梁，它提供了一种在 ROS 图像消息（sensor_msgs/Image）和 OpenCV 图像格式（cv::Mat）之间进行转换的功能。在 ROS Noetic 中，cv_bridge 默认使用 Python 3 和 OpenCV 4。

2. 环境准备

2.1 系统要求

Ubuntu 20.04
ROS Noetic（完整版安装）
Python 3.8+
OpenCV 4.2+

2.2 创建工作空间

bash 复制代码

# 创建专门用于 cv_bridge 的工作空间
mkdir -p ~/cv_bridge_ws/src
cd ~/cv_bridge_ws

3. 安装编译依赖

3.1 更新系统包

bash 复制代码

sudo apt-get update
sudo apt-get upgrade -y

3.2 安装 ROS 基础依赖

bash 复制代码

sudo apt-get install -y python3-catkin-tools python3-rosdep python3-vcstools

3.3 安装 cv_bridge 依赖

bash 复制代码

# 安装 OpenCV 开发库
sudo apt-get install -y libopencv-dev python3-opencv

# 安装 Boost Python3 支持
sudo apt-get install -y libboost-python-dev libboost-thread-dev

# 安装 Python3 开发库
sudo apt-get install -y python3-dev python3-numpy

# 安装 ROS 图像相关依赖
sudo apt-get install -y ros-noetic-cv-bridge ros-noetic-vision-opencv

3.4 初始化 rosdep

bash 复制代码

sudo rosdep init
rosdep update
cd ~/cv_bridge_ws
rosdep install --from-paths src --ignore-src -r -y

4. 下载源码

4.1 克隆 vision_opencv 仓库

bash 复制代码

cd ~/cv_bridge_ws/src
git clone https://github.com/ros-perception/vision_opencv.git -b noetic

4.2 查看目录结构

你应该看到以下目录：

cv_bridge/
image_geometry/
opencv_tests/
vision_opencv/

5. 编译 cv_bridge

5.1 单独编译 cv_bridge

bash 复制代码

cd ~/cv_bridge_ws

# 方法一：使用 catkin_make
catkin_make --only-pkg-with-deps cv_bridge -DPYTHON_EXECUTABLE=/usr/bin/python3

# 方法二：使用 catkin build（推荐）
catkin build cv_bridge -DPYTHON_EXECUTABLE=/usr/bin/python3

5.2 如果需要指定 OpenCV 路径

bash 复制代码

# 查找 OpenCV 路径
pkg-config --cflags opencv4
# 通常输出：-I/usr/include/opencv4

# 使用指定 OpenCV 路径编译
catkin build cv_bridge \
  -DPYTHON_EXECUTABLE=/usr/bin/python3 \
  -DOpenCV_DIR=/usr/lib/x86_64-linux-gnu/cmake/opencv4

5.3 编译全部包（如果需要）

bash 复制代码

catkin build -DPYTHON_EXECUTABLE=/usr/bin/python3

5.4 验证编译成功

bash 复制代码

# 检查生成的库文件
ls -la ~/cv_bridge_ws/devel/lib/python3/dist-packages/cv_bridge/
ls -la ~/cv_bridge_ws/devel/lib/libcv_bridge.so

6. 替换系统 cv_bridge 的多种方法

6.1 方法一：使用 catkin overlay（推荐）

6.1.1 Source 工作空间

bash 复制代码

source ~/cv_bridge_ws/devel/setup.bash --extend

6.1.2 添加到 .bashrc

bash 复制代码

echo "source ~/cv_bridge_ws/devel/setup.bash --extend" >> ~/.bashrc
source ~/.bashrc

6.1.3 检查 ROS_PACKAGE_PATH

bash 复制代码

echo $ROS_PACKAGE_PATH

期望输出 ：你的工作空间路径应该排在 /opt/ros/noetic/share 之前。

6.2 方法二：使用 ROS_PACKAGE_PATH 覆盖

6.2.1 手动设置环境变量

bash 复制代码

export ROS_PACKAGE_PATH=~/cv_bridge_ws/src/vision_opencv/cv_bridge:$ROS_PACKAGE_PATH

6.2.2 永久设置

bash 复制代码

echo "export ROS_PACKAGE_PATH=~/cv_bridge_ws/src/vision_opencv/cv_bridge:\$ROS_PACKAGE_PATH" >> ~/.bashrc
source ~/.bashrc

6.3 方法三：屏蔽系统包（终极方案）

6.3.1 备份系统 cv_bridge

bash 复制代码

sudo cp -r /opt/ros/noetic/share/cv_bridge /opt/ros/noetic/share/cv_bridge_backup
sudo cp -r /opt/ros/noetic/lib/libcv_bridge.so /opt/ros/noetic/lib/libcv_bridge.so.backup

6.3.2 重命名系统包

bash 复制代码

sudo mv /opt/ros/noetic/share/cv_bridge /opt/ros/noetic/share/cv_bridge.bak
sudo mv /opt/ros/noetic/lib/libcv_bridge.so /opt/ros/noetic/lib/libcv_bridge.so.bak

6.3.3 创建符号链接指向你的版本

bash 复制代码

sudo ln -s ~/cv_bridge_ws/src/vision_opencv/cv_bridge /opt/ros/noetic/share/cv_bridge
sudo ln -s ~/cv_bridge_ws/devel/lib/libcv_bridge.so /opt/ros/noetic/lib/libcv_bridge.so

6.3.4 更新缓存

bash 复制代码

rospack profile
sudo ldconfig

6.4 方法四：使用 CMAKE_PREFIX_PATH

bash 复制代码

export CMAKE_PREFIX_PATH=~/cv_bridge_ws/devel:/opt/ros/noetic
echo "export CMAKE_PREFIX_PATH=~/cv_bridge_ws/devel:/opt/ros/noetic" >> ~/.bashrc
source ~/.bashrc

6.5 方法五：使用 LD_LIBRARY_PATH 覆盖动态库

bash 复制代码

export LD_LIBRARY_PATH=~/cv_bridge_ws/devel/lib:$LD_LIBRARY_PATH
echo "export LD_LIBRARY_PATH=~/cv_bridge_ws/devel/lib:\$LD_LIBRARY_PATH" >> ~/.bashrc
source ~/.bashrc

7. 验证覆盖成功

7.1 检查包路径

bash 复制代码

rospack find cv_bridge

成功标志：输出应该是你的工作空间路径

bash 复制代码

/home/your_username/cv_bridge_ws/src/vision_opencv/cv_bridge

7.2 检查 Python 导入

bash 复制代码

python3 -c "import cv_bridge; print(cv_bridge.__file__); print(cv_bridge.__version__)"

7.3 测试 cv_bridge 功能

python 复制代码

python3 << EOF
from cv_bridge import CvBridge
import cv2
import numpy as np

# 创建测试图像
test_image = np.zeros((480, 640, 3), dtype=np.uint8)

# 测试转换
bridge = CvBridge()
ros_image = bridge.cv2_to_imgmsg(test_image, "bgr8")
cv_image = bridge.imgmsg_to_cv2(ros_image, "bgr8")

print("cv_bridge 测试成功！")
print(f"图像尺寸: {cv_image.shape}")
EOF

7.4 检查动态库链接

bash 复制代码

ldd ~/cv_bridge_ws/devel/lib/libcv_bridge.so

7.5 检查 rospack 缓存

bash 复制代码

rospack find --disable-cache cv_bridge

8. 常见问题与解决方案

8.1 问题：编译时找不到 Python3

错误信息：

复制代码

Could NOT find PythonLibs (missing: PYTHON_LIBRARIES PYTHON_INCLUDE_DIRS)

解决方案：

bash 复制代码

sudo apt-get install python3-dev
# 编译时指定 Python3
catkin build cv_bridge -DPYTHON_EXECUTABLE=/usr/bin/python3

8.2 问题：OpenCV 版本不匹配

错误信息：

复制代码

Could NOT find OpenCV (missing: OpenCV_DIR)

解决方案：

bash 复制代码

# 安装 OpenCV
sudo apt-get install libopencv-dev

# 指定 OpenCV 路径
catkin build cv_bridge -DOpenCV_DIR=/usr/share/OpenCV

8.3 问题：Boost.Python3 找不到

错误信息：

复制代码

Could NOT find Boost (missing: python3)

解决方案：

bash 复制代码

sudo apt-get install libboost-python-dev libboost-python1.71-dev

8.4 问题：rospack 仍然找到系统包

错误信息：

复制代码

rospack find cv_bridge  # 仍然返回 /opt/ros/noetic/share/cv_bridge

解决方案：

bash 复制代码

# 清除缓存
rm -rf ~/.ros/rospack_cache

# 检查环境变量
echo $ROS_PACKAGE_PATH
echo $CMAKE_PREFIX_PATH

# 重新 source
source ~/cv_bridge_ws/devel/setup.bash --extend

8.5 问题：Python 导入错误

错误信息：

复制代码

ImportError: No module named cv_bridge.boost.cv_bridge_boost

解决方案：

bash 复制代码

# 检查 Python 路径
echo $PYTHONPATH

# 添加 Python 路径
export PYTHONPATH=~/cv_bridge_ws/devel/lib/python3/dist-packages:$PYTHONPATH

8.6 问题：动态库加载错误

错误信息：

复制代码

error while loading shared libraries: libcv_bridge.so: cannot open shared object file

解决方案：

bash 复制代码

sudo ldconfig ~/cv_bridge_ws/devel/lib
export LD_LIBRARY_PATH=~/cv_bridge_ws/devel/lib:$LD_LIBRARY_PATH

9. 恢复系统版本

9.1 如果使用方法一/二

复制代码

# 注释掉 .bashrc 中的相关行
# 重新打开终端即可

9.2 如果使用方法三（屏蔽系统包）

bash 复制代码

# 恢复系统包
sudo rm /opt/ros/noetic/share/cv_bridge
sudo rm /opt/ros/noetic/lib/libcv_bridge.so
sudo mv /opt/ros/noetic/share/cv_bridge.bak /opt/ros/noetic/share/cv_bridge
sudo mv /opt/ros/noetic/lib/libcv_bridge.so.bak /opt/ros/noetic/lib/libcv_bridge.so

# 更新缓存
rospack profile
sudo ldconfig

9.3 如果使用方法四/五

bash 复制代码

# 编辑 .bashrc，删除或注释掉添加的环境变量
# source 默认的 ROS 环境
source /opt/ros/noetic/setup.bash

10. 总结

10.1 推荐流程

创建独立工作空间：避免干扰其他 ROS 包
编译时指定 Python3：确保与 Noetic 兼容
使用 catkin overlay：最安全的覆盖方法
验证覆盖成功：通过 rospack find 和 Python 测试

10.2 关键命令速查表

操作	命令
创建工作空间	`mkdir -p ~/cv_bridge_ws/src`
克隆源码	`git clone https://github.com/ros-perception/vision_opencv.git -b noetic`
编译	`catkin build cv_bridge -DPYTHON_EXECUTABLE=/usr/bin/python3`
Source	`source ~/cv_bridge_ws/devel/setup.bash --extend`
验证	`rospack find cv_bridge`
Python 测试	`python3 -c "from cv_bridge import CvBridge"`

10.3 注意事项

Python 版本：Noetic 必须使用 Python3
OpenCV 版本：建议使用系统 OpenCV 4.2+
环境变量：确保工作空间路径优先
缓存清理：修改后记得清理 rospack 缓存

10.4 最终检查清单

✅ 创建工作空间

✅ 安装所有依赖

✅ 成功编译 cv_bridge

✅ source 工作空间 setup.bash

✅ ROS_PACKAGE_PATH 正确

✅ rospack find 返回自定义路径

✅ Python 导入无错误

✅ 功能测试通过

附录：完整脚本

将以下脚本保存为 install_cv_bridge.sh：

bash 复制代码

#!/bin/bash

# ROS Noetic cv_bridge 自定义编译脚本
set -e

echo "=== 开始自定义编译 cv_bridge ==="

# 创建工作空间
WORKSPACE_DIR=$HOME/cv_bridge_ws
echo "创建工作空间: $WORKSPACE_DIR"
mkdir -p $WORKSPACE_DIR/src
cd $WORKSPACE_DIR

# 安装依赖
echo "安装依赖..."
sudo apt-get update
sudo apt-get install -y \
    python3-catkin-tools \
    python3-rosdep \
    python3-vcstools \
    libopencv-dev \
    python3-opencv \
    libboost-python-dev \
    libboost-thread-dev \
    python3-dev \
    python3-numpy \
    ros-noetic-cv-bridge \
    ros-noetic-vision-opencv

# 初始化 rosdep
sudo rosdep init || true
rosdep update

# 克隆源码
echo "克隆 vision_opencv 仓库..."
cd src
if [ ! -d "vision_opencv" ]; then
    git clone https://github.com/ros-perception/vision_opencv.git -b noetic
fi

# 安装依赖
cd $WORKSPACE_DIR
rosdep install --from-paths src --ignore-src -r -y

# 编译
echo "编译 cv_bridge..."
catkin build cv_bridge -DPYTHON_EXECUTABLE=/usr/bin/python3

# 添加到 .bashrc
echo "添加到 .bashrc..."
echo "" >> ~/.bashrc
echo "# Custom cv_bridge" >> ~/.bashrc
echo "source $WORKSPACE_DIR/devel/setup.bash --extend" >> ~/.bashrc

# 验证
echo "验证安装..."
source $WORKSPACE_DIR/devel/setup.bash --extend
rospack find cv_bridge

echo "=== 完成 ==="
echo "请运行: source ~/.bashrc"

运行脚本：

bash 复制代码

chmod +x install_cv_bridge.sh
./install_cv_bridge.sh

参考链接

本文为原创文章，转载请注明出处。如有问题，欢迎在评论区讨论！