RealSense D435i 与 librealsense SDK：从测距到深度滤波的实践手册

RealSense D435i 与 librealsense SDK：从测距到深度滤波的实践手册

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

librealsense 是 Intel RealSense 深度相机的官方 SDK，D435i 是其带 6 轴 IMU 的立体深度机型。它把深度流、RGB 流与惯性数据统一在一套 pipeline API 下，适合要写机器人避障、三维测量、SLAM 前置模块的 C/C++ 开发者。

能力速览

三步装好 SDK 并跑通第一帧

Ubuntu 20/22/24 LTS 的流程是：装依赖、补 udev 规则、打内核补丁、cmake 构建。内核补丁必须做，否则深度流不稳定。

git clone https://gitcode.com/GitHub_Trending/li/librealsense cd librealsense ./scripts/setup_udev_rules.sh ./scripts/patch-realsense-ubuntu-lts-hwe.sh mkdir build && cd build cmake .. -DBUILD_EXAMPLES=true -DCMAKE_BUILD_TYPE=Release && make -j$(nproc) && sudo make install

装完用rs-enumerate-devices确认设备在列。最小程序 10 行以内就能读距离，仓库内完整示例在 examples/hello-realsense/：

#include <librealsense2/rs.hpp> rs2::pipeline pipe; rs2::config cfg; cfg.enable_stream(RS2_STREAM_DEPTH); pipe.start(cfg); while (true) { auto depth = pipe.wait_for_frames().get_depth_frame(); // 单位米；无效像素返回 0 std::cout << depth.get_distance(depth.get_width() / 2, depth.get_height() / 2) << " m\n"; }

wait_for_frames()阻塞到帧到齐，get_distance(x, y)已把单位换算好，返回米。要拿原始毫米值就自己读get_data()并乘以RS2_OPTION_DEPTH_UNITS。

核心用法

测距与两点距离

单点距离用get_distance即可。两点间的真实三维距离要先反投影到 3D 再算欧氏距离，仓库里的 examples/measure/ 做了完整的可拖拽标尺实现，关键就三步：

rs2_intrinsics intr = depth.get_profile() .as<rs2::video_stream_profile>().get_intrinsics(); float px[2], p3d[3]; rs2_deproject_pixel_to_point(p3d, &intr, px, dist); // 两个像素各做一次，再对 p3d 求欧氏距离

深度滤波参数怎么调

官方推荐链路与各滤镜参数如下，完整可交互示例在 examples/post-processing/，说明文档见 doc/post-processing-filters.md：

rs2::decimation_filter dec; rs2::spatial_filter spat; rs2::temporal_filter temp; spat.set_option(RS2_OPTION_FILTER_SMOOTH_DELTA, 20); rs2::frame out = depth; out = dec.process(out); out = spat.process(out); out = temp.process(out);

注意：滤镜对象在多线程间共享状态，每台设备维护一条滤镜链；temporal 换帧源会丢失历史，效果直接失效。

多流同步：深度加 IMU

深度、RGB 由 pipeline 自动打包进同一个frameset；IMU 帧率远高于视频，走单帧通道。用first_or_default按流类型取帧即可：

rs2::config cfg; cfg.enable_stream(RS2_STREAM_GYRO); cfg.enable_stream(RS2_STREAM_ACCEL); pipe.start(cfg); while (true) { auto set = pipe.wait_for_frames(); if (auto g = set.first_or_default(RS2_STREAM_GYRO)) rs2_vector v = g.get_motion_data(); // 角速度 rad/s if (auto a = set.first_or_default(RS2_STREAM_ACCEL)) // a.get_motion_data() 静止时 y 分量约 -9.8 }

IMU 样本时间戳与深度帧同一时钟，取frame.get_timestamp()相减就是真实时间差，做运动补偿不需要校时。需要自定义多流合流规则时用rs2::syncer构造回调，把pipe.start(syncer)的回调接到队列上；低延迟场景整体换成回调模式，参考 examples/callback/。

生成点云

rs2::pointcloud pc; pc.map_to(color); // 贴彩色纹理 auto points = pc.calculate(depth); // points.get_vertices() 每 3 个 float 一个点

完整渲染版在 examples/pointcloud/。生成点云前先对齐，rs2::align的构造是重操作，放在主循环外：

rs2::align align_to_depth(RS2_STREAM_DEPTH); rs2::frameset out = align_to_depth.process(set);

对齐是合成视口，会引入采样和遮挡伪影，examples/align/ 有双向对齐的可视化对比。

调优与进阶

按这个顺序调，收益从高到低：

1. 分辨率与帧率。CPU 不够就降深度分辨率或帧率，别先加滤镜——滤镜是 CPU 开销大户。
2. 滤镜链路。CPU 吃紧时只开 decimation + spatial；追求平面平滑度再叠 temporal；边缘毛刺多就把 spatial 的RS2_OPTION_FILTER_SMOOTH_DELTA调大（默认 20，上限 50），空洞多再上 hole_filling。
3. 视觉预设。D400 系列支持RS2_OPTION_VISUAL_PRESET，测距场景直接切高精度档：

auto sensor = pipe.get_active_profile().get_device() .first<rs2::depth_sensor>(); sensor.set_option(RS2_OPTION_VISUAL_PRESET, RS2_RS400_VISUAL_PRESET_HIGH_ACCURACY);

4. 高级模式。rs400::advanced_mode暴露约百个硬件参数，可save_json/load_json序列化整套配置。改坏能退出高级模式恢复默认，但深度质量与帧率不再保证。参数面板长这样：

5. 深度质量工具。tools/depth-quality/ 内置 Z / Zi / ZPi 三类误差统计，用它做参数调优的量化验收，比肉眼判断可靠。

实战场景

场景一：桌面式尺寸测量

目标：相机固定，量取画面中两点间距离。

步骤：

1. 参考 examples/measure/ 起 pipeline，深度 + RGBA 彩色双流；
2. 设RS2_RS400_VISUAL_PRESET_HIGH_ACCURACY；
3. 滤镜链用 decimation(2) → spatial（开RS2_OPTION_HOLES_FILL）→ temporal，避免标尺路径从洞里穿过去；
4. 对鼠标两点反投影求 3D 距离。

验证：放一根已知长度的钢尺正对相机，读数偏差应在 1–2 cm 内；偏差大先检查相机是否水平，再看 Z 误差统计。

场景二：录制一次、离线调参

目标：现场采集困难，把数据带回办公室反复试验。

步骤：

1. 用 tools/recorder/ 或 recorder 设备录.bag，IMU 流一并包含；
2. 本地用 playback 设备打开 bag，pipeline 代码不用改，device.as<rs2::playback>()判一下即可；
3. 在回放数据上迭代滤镜参数与高级 JSON 配置。

验证：回放帧的时间戳、分辨率、数据与原始采集逐位一致，rs-replay可直接复放。完整 GUI 示例见 examples/record-playback/。

排障速查

资源索引

常用工具（安装后即可全局调用）：

关键文档与示例：

• 坐标系与 IMU 集成：doc/d435i.md
• 滤镜说明：doc/post-processing-filters.md
• 高级模式：doc/rs400/rs400_advanced_mode.md
• 安装：doc/installation.md
• 录制回放：doc/record-and-playback.md
• 示例总目录：examples/

D435i 加上 librealsense，深度、RGB、IMU 三路数据的时间对齐和坐标统一都已处理，开发者剩下的工作集中在滤波链与业务逻辑上。建议从rs-enumerate-devices和 hello-realsense 起步，再按本文的调优顺序逐步加滤镜。延伸阅读：doc/stepbystep/getting_started_with_openCV.md 和 examples/sensor-control/ 中的传感器选项参考。

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