librealsense 实战：三步在 Linux 上跑通 RealSense 深度流与 3D 尺寸测量-开发者社区

librealsense 实战：三步在 Linux 上跑通 RealSense 深度流与 3D 尺寸测量

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

librealsense 是 RealSense 深度相机的开源 SDK，提供深度/彩色流、内外参与多相机对齐能力。按本文操作，你可以完成 SDK 构建安装、通过 Viewer 验证出流、用 Python 多相机示例测出物体毫米级尺寸。

🔌 阶段一：构建 SDK 并验证相机出流

目标只有一个：realsense-viewer窗口里能看到深度与彩色画面。分 Ubuntu 与 Jetson 两条路。

Ubuntu 桌面端安装（20.04/22.04/24.04）

先装系统依赖，注意这些包需要分开安装以避免依赖冲突（见安装文档）：

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

克隆仓库并配置权限与内核补丁。Linux 下必须打补丁插入修改过的 uvcvideo 内核驱动，否则拿不到深度格式支持：

git clone https://gitcode.com/GitHub_Trending/li/librealsense cd librealsense ./scripts/setup_udev_rules.sh ./scripts/patch-realsense-ubuntu-lts-hwe.sh

确认补丁生效：sudo dmesg | tail -n 50，日志中应出现新的 uvcvideo 驱动注册信息。

Jetson 平台内核补丁配置

Jetson 使用 L4T 定制内核，换掉内核镜像风险大，官方脚本在不替换镜像的前提下打补丁并插模块，过程约 30 分钟，需要约 2.5GB 空闲空间（df -h确认）：

cd librealsense ./scripts/patch-realsense-ubuntu-L4T.sh

详细要求（电源模式、断开会干扰的 USB 摄像头等）见 Jetson 安装文档。

编译并安装 SDK

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

共享库装到/usr/local/lib，头文件到/usr/local/include，示例与工具二进制进/usr/local/bin。

出流验证

lsusb | grep 8086 realsense-viewer

图：在 Jetson 上运行realsense-viewer后，窗口同时显示 D400 的深度、彩色与点云流，侧栏可调整帧率与分辨率。

✅ 自检点：lsusb | grep 8086输出一行 RealSense 设备信息，且 Viewer 窗口内深度流不是纯黑，彩色流有正常画面。

🎛️ 阶段二：深度质量调参

出流不等于可用。深度噪声大、远处空洞多时，从这里入手。

用 sensor-control 修改传感器选项

rs2::pipeline是高层 API；需要精细控制时用rs2::context/rs2::device/rs2::sensor三层 API 查询并修改单个传感器选项（曝光、增益、激光功率等）。仓库内置交互式示例：

rs-sensor-control

运行后它会列出已连接设备，让你选择相机、传感器与要操作的选项。代码级写法逐项讲解在 examples/sensor-control/api_how_to.h；D400 系列各参数的官方说明见 doc/rs400/advanced_mode.md。

图：高级模式控制界面示例，逐项调整深度传感器参数后，Viewer 中的深度画面实时反映变化。

用空间/时间滤波压制噪声

后处理滤波器（spatial filter、temporal filter 等）挂在帧流上即可生效，无需改驱动。参数含义与适用场景见 doc/post-processing-filters.md，可直接运行 examples/post-processing 示例对比处理前后差异。

用深度质量工具量化指标

对精度与填充率有量化要求时，跑 SDK 自带工具 tools/depth-quality 测量准确率与 fill rate，作为调参前后的对比基线。

✅ 自检点：Viewer 侧栏勾选 spatial/temporal filter 后深度画面噪点明显减少；depth-quality 工具输出的 fill rate 数值可复现且不低于调参前。

🧩 阶段三：组合出自己的应用

以 Python 为主，最短路径是 pip 装绑定后直接跑仓库自带多相机示例。

安装 pyrealsense2

pip install pyrealsense2

稳定版pyrealsense2与 SDK tag 对齐，适合多数用户；需要更新特性时换pyrealsense2-beta，两者不要同时装。

跑通多相机箱体尺寸测量

示例位置在 wrappers/python/examples/box_dimensioner_multicam，它演示把多台相机对齐到统一坐标系后测量物体三维尺寸，依赖 OpenCV、numpy 与 pyrealsense2：

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

操作流程：先把标定棋盘放入所有相机视野完成标定，程序提示时把待测物体放到棋盘上（物体长宽需小于棋盘），随后输出以毫米为单位的长宽高。

图：两台 D435 对准棋盘上待测物体的布置，右侧窗口在彩色图上叠加检测到的包围框并给出尺寸。

往应用里加自己的逻辑

需要裸帧数据做二次开发时，pipeline 三步起步：pipeline.start()→wait_for_frames()取帧 →depth.get_distance(x, y)读像素距离，完整可编译工程参考 examples/cmake/hello_librealsense2.cpp。数据流的生命周期与拷贝规则见 doc/frame_lifetime.md。想要离线算法迭代，用 Viewer 录制后回放，流程见 doc/record-and-playback.md；实时点云重建可看 wrappers/opencv/kinfu。

✅ 自检点：程序按相机数量弹出窗口，彩色图上叠加绿色包围框，终端/窗口输出毫米级长宽高数值。

❓ 常见问题与求助入口

现象：启动时提示Multiple realsense udev-rules were found!。原因：Debian 包与源码安装同时存在，udev 规则冲突。处理：保留其一，删除另一套安装。
现象：patch 脚本失败，报fatal error: openssl/opensslv.h。原因：缺少 openssl 开发包。处理：sudo apt-get install libssl-dev后重跑脚本。
现象：编译失败，卡在fastrtps/fastcdr依赖。原因：本机缺少 eProsima Fast-DDS 构建环境。处理：cmake 追加-DBUILD_WITH_DDS=OFF重新配置。
现象：sudo modprobe uvcvideo后 dmesg 提示 uvc 模块未加载。原因：补丁模块与当前内核版本不匹配。处理：uname -r核对内核，从系统更新步骤重做（见安装文档）。
现象：SDK 完全检测不到相机。原因：补丁驱动未生效或 USB 权限未配置。处理：依次跑lsusb | grep 8086、sudo dmesg | tail -n 50定位，开启export LRS_LOG_LEVEL=debug复现，按排障手册逐项核对。