RealSense 深度相机 SDK 实战部署全流程：从环境搭建到跑通多相机尺寸测量

RealSense 深度相机 SDK 实战部署全流程：从环境搭建到跑通多相机尺寸测量

【免费下载链接】librealsenseRealSense SDK项目地址: https://gitcode.com/GitHub_Trending/li/librealsense

本文带你实战部署 RealSense SDK（librealsense）：完成 Ubuntu 内核补丁、C++ 编译安装，再用 Python 跑通深度流、数据回放与多相机尺寸测量。照命令执行，你将在自己的环境得到一条可用的深度感知流水线。

🧭 能力速览：librealsense 能做什么

• C/C++ 核心 SDK，输出深度、彩色、红外与 IMU 数据流，API 头文件在 include/librealsense2/rs.hpp
• GUI 工具realsense-viewer：可视化、录制、回放、参数调节，源码在 tools/realsense-viewer/
• 30+ 可编译示例程序（rs-capture、rs-align、rs-pointcloud等），位于 examples/
• Python 绑定 pyrealsense2，含多相机标定、目标检测等示例，位于 wrappers/python/examples/
• C#/MATLAB/Unity/Unreal/OpenCV 等语言绑定，位于 wrappers/

📦 环境准备：硬件、系统与依赖清单

硬件与系统要求

注意：官方不支持虚拟机安装（USB 3.0 转换层问题），请在物理机上操作。

安装系统依赖：依次执行以下命令，分别安装 USB 库、构建工具链和 OpenGL 示例所需图形库：

sudo apt-get update && sudo apt-get upgrade sudo apt-get install libusb-1.0-0-dev libudev-dev libssl-dev pkg-config libgtk-3-dev sudo apt-get install git wget cmake build-essential

重要：安装图形后端包前，先拔掉所有已连接的 RealSense 相机，避免内核补丁与设备占用冲突：

sudo apt-get install libglfw3-dev libgl1-mesa-dev libglu1-mesa-dev at

获取项目：克隆仓库并进入根目录：

git clone https://gitcode.com/GitHub_Trending/li/librealsense cd librealsense

配置 udev 权限规则：让普通用户无需 sudo 访问相机 USB 节点：

./scripts/setup_udev_rules.sh

执行成功会提示规则安装到/etc/udev/rules.d/；如需卸载，运行./scripts/setup_udev_rules.sh --uninstall。

打内核补丁：RealSense 依赖修改过的uvcvideo驱动，需按内核版本编译并插入补丁模块。Ubuntu 20/22/24（内核 5.15+）执行：

./scripts/patch-realsense-ubuntu-lts-hwe.sh

脚本会下载、打补丁、编译并插入新模块；若插入失败会自动还原原uvcvideo模块。旧版 focal 内核（< 5.13）改用./scripts/patch-realsense-ubuntu-lts.sh。

编译并安装 SDK：-DBUILD_EXAMPLES=true同时构建示例与 viewer，Release 模式启用优化：

mkdir build && cd build cmake ../ -DBUILD_EXAMPLES=true -DCMAKE_BUILD_TYPE=Release make -j$(($(nproc)-1)) sudo make install

无图形环境（headless 部署）时，配置阶段追加-DBUILD_GRAPHICAL_EXAMPLES=false只构建文本示例。make install成功即完成：共享库进入/usr/local/lib，头文件进入/usr/local/include，示例与 viewer 二进制进入/usr/local/bin。

✅ 首次运行验证：3 条命令确认环境就绪

第 1 条：确认补丁驱动已注册。查看内核日志末尾：

sudo dmesg | tail -n 50

成功标准：日志中出现新的uvcvideo驱动注册条目。若报错，对照 doc/troubleshooting.md 排查。

第 2 条：确认 SDK 已安装。列出已安装的共享库：

ls /usr/local/lib | grep librealsense

成功标准：能看到librealsense.so.2*（以及librealsense2-gl.so）。

第 3 条：确认相机可枚举、可出流。启动官方查看器：

realsense-viewer

成功标准：左侧设备列表出现相机型号（如 D435i），点击 Start 后窗口实时显示深度/彩色画面。三条都通过，说明从驱动到 SDK 到设备链路全部就绪。

🎯 场景一：3 分钟用 Python 跑通深度流

场景目标：不写 C++，用 Python 绑定拿到第一份深度数据，理解深度图的物理含义。

操作步骤：先安装 pyrealsense2（pip 的 wheel 已内置编译好的 librealsense 库，无需重复编译 SDK）：

pip install pyrealsense2

再运行官方 Python 教程第 1 课，它会启动 640x480、30fps 的深度流并打印字符矩阵：

cd wrappers/python/examples python3 python-tutorial-1-depth.py

预期输出：终端以 ASCII 网格实时打印 1 米范围内像素的深度覆盖率，你对着相机挥动物品，矩阵亮度随之变化；Ctrl+C退出。

想要图形界面，直接运行编译安装的 C++ 示例rs-capture，它会同时打开深度、彩色与红外窗口：

rs-capture

预期输出：三个窗口实时出流，深度图中近处物体更亮、远处更暗，灰度值对应物体距离。

🎬 场景二：数据录制与回放（.db3 文件）

场景目标：把相机数据流录制成文件，供离线分析、算法复测，摆脱对真机的依赖。

操作步骤：

1. 启动realsense-viewer并开始流，确认画面正常。
2. 在 viewer 右上角 Settings 面板进入 Record & Playback 区域，设置输出文件路径（必须以.db3结尾），点击 Start Recording；录制完成后点 Stop。
3. 回放：把录制文件作为参数传给 viewer，或将文件直接拖入 viewer 窗口：

realsense-viewer ~/my_recording.db3

预期输出：录制文件为 ROS2 rosbag2（SQLite 基础）格式；回放时设备列表出现该文件对应的设备，可以暂停、拖动进度、调整倍速重放。

C++ 侧对应 API 是rs2::recorder与rs2::playback（ctx.load_device("file.db3")），完整用法见 doc/record-and-playback.md。注意：压缩录制仅能用 SDK 回放，若要与 ROS2 工具兼容，需在 Settings 中关闭压缩（Never Compress）。

📐 场景三：多相机 Box Dimensioner 尺寸测量

场景目标：用两台 D400 相机标定统一坐标系，对放在棋盘格上的物体自动测量长宽高（毫米级），这是物流仓储场景的典型用法。

前置条件：至少 2 台 D400 系列相机 + 一个 6x9 棋盘格（格边长 25.3mm，示例目录内的pattern_chessboard.png可打印使用）。

操作步骤：

cd wrappers/python/examples/box_dimensioner_multicam pip install pyrealsense2 opencv-python numpy python3 box_dimensioner_multicam_demo.py

预期输出：程序先把棋盘格放入所有相机视野完成 Kabsch 算法标定，随后提示你将待测物体放到棋盘格上（物体长宽不得超出棋盘格）；完成后终端打印长、宽、高（单位 mm），每台相机的窗口显示彩色图与包围框叠加。

🛠️ 进阶调优：Advanced Mode 参数与 Jetson 平台差异

D400 高级参数调优：rs-sensor-control示例提供了 Advanced Mode 的图形界面，可实时调整激光功率、曝光时间、深度置信度阈值等参数以适配不同光照与场景：

rs-sensor-control

预期输出：出现参数控制窗口，调整滑块后深度画面质量即时变化。源码在 examples/sensor-control/，参数含义参考 doc/rs400/rs400_advanced_mode.md。

Jetson 平台差异：L4T 系统需单独打内核补丁，运行./scripts/patch-realsense-ubuntu-L4T.sh；使用 MiPi 接口的设备（Jetson D400 模组）还需./scripts/rs-enum.sh创建/dev/video-rs-*符号链接，脚本输出中可看到每个传感器对应的 video 节点。

🧯 常见坑与解决

1. 打内核补丁时报fatal error: openssl/opensslv.h原因：缺少 openssl 开发头文件。解决：sudo apt-get install libssl-dev后重新运行 patch 脚本。

2. 编译在fastrtps/fastcdr依赖上报错原因：SDK 尝试集成 eProsima Fast-DDS 网络传输库，但本机依赖缺失。解决：重新配置时禁用 DDS：

cmake ../ -DBUILD_EXAMPLES=true -DBUILD_WITH_DDS=OFF

3. 编译报gcc: internal compiler error原因：内存或 swap 不足（常见于 2GB 内存的机器和虚拟机）。解决：关闭占内存的程序或增加 swap；虚拟机至少分配 2GB RAM 后重试。

4. 补丁脚本成功但设备无数据，dmesg提示 uvc 模块未加载原因：补丁编译的内核版本与当前运行的内核不匹配（例如打补丁后又升级了内核）。解决：用uname -r核对版本，更新内核后回到"环境准备"步骤重新打补丁。

更多问题见 doc/installation.md 末尾的故障排除表。

📚 收尾与资源

到这里，你已完成从内核驱动、SDK 编译到深度流、回放、多相机测量的完整部署链路。后续可以按场景深入：

• 安装文档（含完整依赖与故障排除表）：doc/installation.md
• 故障排除：doc/troubleshooting.md
• C++ API 参考：include/librealsense2/rs.hpp
• 示例程序总入口：examples/
• Python 绑定与示例：wrappers/python/examples/
• 录制与回放 API：doc/record-and-playback.md
• 后处理滤波器（空洞填补、时域滤波等）：doc/post-processing-filters.md

【免费下载链接】librealsenseRealSense SDK项目地址: https://gitcode.com/GitHub_Trending/li/librealsense