在树莓派5上安装Intel RealSense Python封装的完整指南

前言

Intel RealSense深度摄像头在计算机视觉领域有着广泛应用，而在树莓派5这样的嵌入式设备上使用RealSense摄像头时，Python封装(pyrealsense2)的安装往往会遇到各种问题。本文将详细介绍在树莓派5上正确安装和使用pyrealsense2的完整流程。

系统环境准备

树莓派5目前最新的操作系统版本是Bookworm，但经过实践发现，较新的操作系统版本与RealSense的兼容性存在一定问题。推荐使用Buster版本的Raspberry Pi OS，这是最后一个已知与RealSense摄像头配合良好的操作系统版本。

如果坚持使用Bookworm，需要注意以下几点：

1. 内核版本较新可能导致驱动兼容性问题
2. 软件包依赖关系可能发生变化
3. 需要手动解决一些编译问题

安装前的准备工作

在开始安装前，需要确保系统已更新并安装必要的依赖项：

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install git cmake libssl-dev libusb-1.0-0-dev pkg-config libgtk-3-dev
sudo apt-get install libglfw3-dev libgl1-mesa-dev libglu1-mesa-dev

使用libuvc后端安装

在树莓派上，推荐使用libuvc后端来安装librealsense和pyrealsense2。这种方法已被证明在树莓派设备上工作良好。

1. 首先克隆librealsense仓库：

git clone https://github.com/IntelRealSense/librealsense.git
cd librealsense

2. 修改安装脚本以包含Python绑定：

sed -i '46s/.*/cmake ..\/ -DFORCE_LIBUVC=true -DCMAKE_BUILD_TYPE=release -DBUILD_PYTHON_BINDINGS:bool=true/' scripts/libuvc_installation.sh

3. 运行安装脚本：

./scripts/libuvc_installation.sh

编译配置详解

正确的CMake配置对于成功编译至关重要。以下是推荐的CMake配置参数：

cmake ../ \
-DBUILD_PYTHON_BINDINGS:bool=true \
-DPYTHON_EXECUTABLE=/usr/bin/python3 \
-DFORCE_LIBUVC=true \
-DCMAKE_BUILD_TYPE=release

参数说明：

• BUILD_PYTHON_BINDINGS：启用Python绑定编译
• PYTHON_EXECUTABLE：指定Python解释器路径
• FORCE_LIBUVC：强制使用libuvc后端
• CMAKE_BUILD_TYPE：设置为release以获得优化性能

常见问题解决

模块导入错误

安装完成后，如果遇到类似"ModuleNotFoundError: No module named 'pyrealsense2.pyrealsense2'"的错误，通常是由于以下原因之一：

1. Python绑定未正确编译
2. 系统中有多个Python版本导致路径混乱
3. 编译时指定的Python版本与运行时使用的版本不一致

解决方法：

• 确保编译时指定的Python版本与运行时一致
• 检查编译日志确认Python绑定是否成功构建
• 尝试手动将生成的.so文件复制到Python的site-packages目录

属性访问错误

出现"module 'pyrealsense2' has no attribute 'XXX'"错误时，通常表示：

1. Python绑定生成不完整
2. 编译过程中某些关键组件缺失
3. 版本不匹配问题

解决方法：

• 重新编译并确保所有依赖项已正确安装
• 检查编译日志是否有警告或错误
• 尝试使用更稳定的Raspberry Pi OS版本

验证安装

安装完成后，可以通过以下Python代码验证是否安装成功：

import pyrealsense2 as rs

try:
    pipeline = rs.pipeline()
    config = rs.config()
    print("RealSense library version:", rs.__version__)
    print("Installation verified successfully!")
except Exception as e:
    print("Error:", e)

性能优化建议

在树莓派5上使用RealSense摄像头时，可以考虑以下优化措施：

1. 降低摄像头分辨率：640x480通常足够大多数应用
2. 减少帧率：30fps或更低可以减少处理负担
3. 使用硬件加速：启用树莓派的GPU加速
4. 优化算法：使用更高效的计算机视觉算法

结语

在树莓派5上安装Intel RealSense Python封装虽然有一定挑战，但通过正确的方法和配置是可以实现的。关键是要选择合适的操作系统版本，使用libuvc后端，并确保编译配置正确。遇到问题时，仔细检查编译日志和错误信息通常能帮助快速定位问题根源。