Ubuntu 22.04上Intel RealSense深度相机Python开发环境搭建：从零到完美运行的避坑指南
Ubuntu 22.04上Intel RealSense深度相机Python开发环境搭建：从零到完美运行的避坑指南
【免费下载链接】librealsense Intel® RealSense™ SDK 
项目地址: https://gitcode.com/GitHub_Trending/li/librealsense
还在为RealSense深度相机在Linux上的驱动安装头疼吗？每次编译都遇到奇怪的Python导入错误？别慌，这篇文章将带你避开所有常见陷阱，30分钟内搞定Intel RealSense SDK的完整Python开发环境配置。
为什么你的RealSense相机在Ubuntu上"认生"？
当你第一次连接RealSense相机到Ubuntu 22.04系统时，可能会遇到各种问题：设备识别失败、Python模块导入错误、深度流无法启动。这通常不是你的错，而是Linux内核驱动与RealSense硬件之间的"语言不通"问题。
RealSense深度相机需要特定的内核模块支持才能正常工作。Ubuntu的默认内核虽然包含UVC驱动，但缺少对深度相机特有功能的支持。这就是为什么我们需要进行内核补丁和驱动配置。
驱动安装：让系统"听懂"你的相机
问题现象：lsusb能看到设备但应用无法访问
当你运行lsusb | grep 8086时能看到Intel设备，但运行Python程序却提示"No device connected"或权限错误。
根本原因：Linux系统的udev规则没有为RealSense设备配置正确的权限，内核模块缺少必要的补丁。
解决方案：使用我们的一键配置脚本
创建一个名为setup_realsense.sh的文件，内容如下：
#!/bin/bash
# RealSense一键安装脚本
set -e
echo "开始配置RealSense开发环境..."
# 1. 安装系统依赖
echo "安装系统依赖包..."
sudo apt-get update
sudo apt-get install -y \
libssl-dev \
libusb-1.0-0-dev \
libudev-dev \
pkg-config \
libgtk-3-dev \
git \
wget \
cmake \
build-essential \
libglfw3-dev \
libgl1-mesa-dev \
libglu1-mesa-dev
# 2. 克隆源码仓库
echo "克隆librealsense源码..."
git clone https://gitcode.com/GitHub_Trending/li/librealsense
cd librealsense
# 3. 配置udev规则
echo "配置设备权限规则..."
./scripts/setup_udev_rules.sh
# 4. 应用内核补丁（针对Ubuntu 22.04 LTS HWE内核）
echo "应用内核补丁..."
./scripts/patch-realsense-ubuntu-lts-hwe.sh
echo "请重启系统以应用内核更改"
echo "重启后运行: sudo modprobe uvcvideo"
保存后执行：
chmod +x setup_realsense.sh
./setup_realsense.sh
验证方法：重启后运行以下命令检查驱动状态：
# 检查内核模块加载
lsmod | grep uvcvideo
# 查看设备识别
lsusb | grep "Intel Corp"
# 查看内核日志中的RealSense相关消息
sudo dmesg | grep -i realsense
图：RealSense设备从硬件连接到系统识别的完整流程，展示了内核模块如何与硬件交互
Python绑定编译：避免"ImportError: No module named pyrealsense2"
问题现象：编译成功但Python无法导入模块
你按照官方文档编译了librealsense，但在Python中导入时却遇到各种奇怪的错误。
根本原因：Python绑定编译时缺少正确的库路径配置，或者Python版本不匹配。
解决方案：使用精确的CMake配置
进入librealsense目录，执行以下精确配置：
# 创建构建目录
mkdir build && cd build
# 确定你的Python版本
PYTHON_VERSION=$(python3 --version | cut -d' ' -f2 | cut -d'.' -f1-2)
echo "检测到Python版本: $PYTHON_VERSION"
# 精确配置CMake
cmake ../ \
-DBUILD_PYTHON_BINDINGS=ON \
-DPYTHON_EXECUTABLE=$(which python3) \
-DCMAKE_BUILD_TYPE=Release \
-DFORCE_RSUSB_BACKEND=OFF
# 编译并安装
make -j$(nproc)
sudo make install
# 设置Python路径
echo "export PYTHONPATH=\$PYTHONPATH:/usr/local/lib/python$PYTHON_VERSION/dist-packages" >> ~/.bashrc
source ~/.bashrc
替代方案：如果你只是想快速测试，可以直接使用预编译的wheel包：
pip install pyrealsense2
验证方法：创建简单的测试脚本test_realsense.py：
import pyrealsense2 as rs
import sys
print(f"Python版本: {sys.version}")
print(f"pyrealsense2版本: {rs.__version__ if hasattr(rs, '__version__') else '未知'}")
# 尝试发现设备
ctx = rs.context()
devices = ctx.query_devices()
print(f"发现设备数量: {len(devices)}")
for i, dev in enumerate(devices):
print(f"设备 {i}: {dev.get_info(rs.camera_info.name)}")
深度流采集实战：从黑屏到实时数据
问题现象：能识别设备但无法获取深度数据
设备识别成功，但启动深度流时要么黑屏，要么帧率极低。
根本原因：流配置参数不正确，或者相机固件需要更新。
解决方案：使用稳健的深度流配置
创建depth_stream_robust.py文件：
import pyrealsense2 as rs
import numpy as np
import cv2
class DepthCamera:
def __init__(self):
self.pipeline = rs.pipeline()
self.config = rs.config()
def start_stream(self):
# 启用深度流 - 使用保守参数确保稳定性
self.config.enable_stream(
rs.stream.depth,
640, 480,
rs.format.z16,
30
)
# 尝试启动管道
try:
self.profile = self.pipeline.start(self.config)
depth_sensor = self.profile.get_device().first_depth_sensor()
# 获取深度尺度（将深度单位转换为米）
self.depth_scale = depth_sensor.get_depth_scale()
print(f"深度尺度: {self.depth_scale}")
return True
except Exception as e:
print(f"启动失败: {e}")
return False
def get_frame(self):
try:
frames = self.pipeline.wait_for_frames(timeout_ms=5000)
depth_frame = frames.get_depth_frame()
if not depth_frame:
return None
# 转换为numpy数组
depth_image = np.asanyarray(depth_frame.get_data())
# 应用深度尺度
depth_image = depth_image * self.depth_scale
return depth_frame, depth_image
except Exception as e:
print(f"获取帧失败: {e}")
return None
def stop(self):
self.pipeline.stop()
# 使用示例
if __name__ == "__main__":
camera = DepthCamera()
if camera.start_stream():
print("深度流启动成功！")
try:
for i in range(100): # 采集100帧
result = camera.get_frame()
if result:
depth_frame, depth_image = result
# 获取中心点深度
center_depth = depth_image[240, 320]
print(f"帧 {i}: 中心深度 = {center_depth:.3f}米")
finally:
camera.stop()
print("相机已停止")
图：RealSense深度相机数据采集界面，显示深度流与彩色流的实时同步
避坑指南：常见问题快速修复
Q1: 编译时出现"Could NOT find PythonLibs"错误
原因：系统缺少Python开发文件 修复：
sudo apt-get install python3-dev python3-numpy
Q2: 导入pyrealsense2时出现"undefined symbol"错误
原因：库路径不正确或版本冲突 修复：
# 查找正确的库路径
find /usr/local -name "pyrealsense2*.so"
# 手动设置库路径
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
Q3: 深度图像显示全黑或全白
原因：深度值范围设置不当 修复：在显示前进行归一化处理
# 在OpenCV显示前处理
depth_colormap = cv2.applyColorMap(
cv2.convertScaleAbs(depth_image, alpha=0.03),
cv2.COLORMAP_JET
)
Q4: 帧率不稳定或掉帧
原因：USB带宽不足或CPU占用过高 修复：
- 降低分辨率：从640x480降至320x240
- 降低帧率：从30FPS降至15FPS
- 使用USB 3.0端口（蓝色接口）
- 关闭不必要的流（如同时开启彩色和红外流）
Q5: 设备频繁断开连接
原因：电源供应不足或USB线质量问题 修复：
- 使用带外部供电的USB集线器
- 更换高质量USB 3.0数据线
- 检查
dmesg日志中的USB错误信息
进阶资源：深入探索RealSense功能
官方文档与配置模板
- 安装指南：doc/installation.md - 包含不同Linux发行版的详细安装说明
- 故障排除：doc/troubleshooting.md - 常见问题解决方案汇总
- Python示例：wrappers/python/examples/ - 丰富的Python代码示例
实用示例代码位置
- 基础深度流：wrappers/python/examples/opencv_viewer_example.py
- 点云生成：wrappers/python/examples/opencv_pointcloud_viewer.py
- 多相机同步：wrappers/python/examples/box_dimensioner_multicam/
- 高级模式配置：wrappers/python/examples/python-rs400-advanced-mode-example.py
性能优化技巧
- 使用对齐功能：将深度流对齐到彩色流坐标系，简化后续处理
- 启用后处理过滤器：使用深度去噪、空洞填充等过滤器提升数据质量
- 硬件加速：如果支持CUDA，编译时启用CUDA支持可大幅提升处理速度
监控与调试工具
# 实时监控USB带宽
sudo usbtop
# 检查内核模块状态
sudo modinfo uvcvideo | grep version
# 查看RealSense特定日志
export LRS_LOG_LEVEL=DEBUG
python your_script.py 2>&1 | grep -i realsense
结语：从问题到解决方案的完整路径
配置RealSense深度相机在Ubuntu上的Python开发环境可能一开始看起来复杂，但一旦理解了每个步骤背后的原理，整个过程就会变得清晰。记住关键三点：
- 驱动是基础：没有正确的内核补丁，硬件无法被系统正确识别
- 路径要正确：Python绑定需要正确的库路径和版本匹配
- 参数要合理：根据应用需求选择合适的流配置参数
通过本文的步骤，你应该能够成功搭建稳定的RealSense开发环境。如果在实践中遇到新问题，建议首先查看内核日志(dmesg)和RealSense的调试输出，这些信息通常能直接指向问题根源。
现在，你的RealSense相机已经准备好为你提供精确的深度数据了——开始构建那些令人兴奋的计算机视觉应用吧！
【免费下载链接】librealsense Intel® RealSense™ SDK 项目地址: https://gitcode.com/GitHub_Trending/li/librealsense
更多推荐
5
0- 0
已为社区贡献11条内容
所有评论(0)