librealsense 完整教程：如何 5 步跑通 RealSense 深度相机并构建 3D 视觉应用

librealsense 完整教程：如何 5 步跑通 RealSense 深度相机并构建 3D 视觉应用

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

librealsense 是 Intel 官方开源的 RealSense SDK，负责把 RealSense 深度相机输出的彩色、红外与深度数据变成你的 C++/C/Python 程序能直接消费的结构化帧，适用于机器人、三维扫描和 CV 算法工程师。本文带你从克隆仓库到写出第一个测距程序，全部基于仓库内真实代码。

⚡️ 快速上手：克隆、编译与第一次看到深度画面

最省事的路径是直接下载官方预编译包；需要定制或装 Python 之外的语言绑定，就从源码编译。以 Linux 为例，只需四步：

git clone https://gitcode.com/GitHub_Trending/li/librealsense # 获取源码 mkdir build && cd build # 独立构建目录，不污染源码 cmake .. # 配置构建，可加 -DDEPTH_QUALITY_TOOL=on 等选项 cmake --build . -j$(nproc) # 并行编译，产物在 build/ 下

编译完成后，第一屏看什么？运行官方自带可视化程序：

./realsense-viewer # 无需写代码，直接查看彩色/深度/点云三路画面

窗口里左侧是设备树（能看到相机序列号、各传感器可配置的分辨率与帧率），右侧是当前实时画面。确认深度画面不是纯黑、有灰度层次，说明相机链路正常，可以开始写代码。Python 用户跳过编译，pip install pyrealsense2一行即可（注意稳定版与 beta 版只能装一个，import 名都是pyrealsense2）。

📏 第一个程序：读取任意像素的距离

SDK 的高层入口是rs2::pipeline（流水线对象，内部帮你完成打开设备、配置流、同步帧等琐事）。仓库里 examples/ 目录按难度分级，最基础的是hello-realsense：

rs2::pipeline p; // 创建流水线 p.start(); // 以默认配置开始出图 auto frames = p.wait_for_frames(); // 阻塞直到一帧到达 auto depth = frames.get_depth_frame(); // 取出深度帧 float dist = depth.get_distance(x, y); // 该像素距相机的距离，单位米

关键认知：深度帧里的每个像素存的就是距离值（Z16格式，单位毫米），get_distance只是把它换算成米。程序里对x, y取画面中心，就能持续打印"正前方物体离我多远"。想控制出什么流，用rs2::config在start之前声明，比如cfg.enable_stream(RS2_STREAM_DEPTH, 640, 480, RS2_FORMAT_Z16, 30)，参数依次是流类型、宽、高、格式、帧率。

📊 空间对齐：把深度"贴"到彩色图上

深度传感器和彩色摄像头是两个镜头，画面分辨率、视角都不一样。直接拿深度像素 (x, y) 去索引彩色图会错位，距离越远偏得越多——这是新手最常见的"框偏了"问题。

解法是对齐（align）：把一路流变换到另一路的坐标系。注意对齐对象创建开销大，要放在主循环外：

rs2::align align_to_color(RS2_STREAM_COLOR); // 目标选彩色视点 auto aligned = align_to_color.process(frameset); // 整组流一次性变换

变换后get_color_frame()和get_depth_frame()分辨率一致，逐像素对应成立。两个副作用要心里有数：插值只允许最近邻（避免捏造不存在的深度值），且彩色镜头看不到的遮挡区域会出现无效像素。

🔧 深度图降噪：五个常用后处理滤波器

原始深度画面常有两类瑕疵：随机噪点和边缘毛刺。SDK 把清理工作做成可串联的滤波器链，常用五个：

rs2::decimation_filter dec; // 抽稀：降分辨率，减噪兼提速 rs2::spatial_filter spat; // 空间滤波：保边平滑，消毛刺 rs2::temporal_filter temp; // 时序滤波：用历史帧压抖动 rs2::threshold_filter thr; // 阈值：裁掉超范围值 rs2::hole_filling_filter hf; // 填洞：补无效像素

使用方式是按temp → dec → spat → hf顺序对深度帧连续process，每个滤波器都能单独设参数（如dec.set_option(RS2_OPTION_DECIMATION, 2)表示抽到 1/4 像素）。想交互式调参数看效果，直接跑仓库自带的post-processing示例，它给每个滤波器都配了实时滑块。

⏸️ 录制与回放：.bag 文件脱离相机调试

调算法时不可能永远对着实物，librealsense 支持把实时流录成.bag文件，之后像设备一样回放：

rs2::recorder rec = device.as<rs2::recorder>(); rec.start_recording("scene.bag"); // 开始写入文件 rec.stop_recording(); // 结束，得到完整 bag

回放时改用rs2::playback，还能seek_to跳到任意时间点、循环播放。这带来两个实际收益：现场采集的数据可以带回办公室反复分析；算法 bug 出现时有据可查。仓库里的record-playback示例演示了带进度条的完整交互流程。

🔍 三个现场排障场景

场景一：黑色物体在画面里"消失"。现象是纸箱是白色的、旁边的哑光黑设备却测不出深度。原因不是程序错，而是红外结构光被黑色表面吸收，传感器收不到回波。打开 Viewer 把发射强度（emissivity）调高验证；若仍无效，给黑色物体区域加辅助照明，或在算法层对无效区做插值兜底。

场景二：在彩色图上画的检测框，离得远的物体框不住。检查代码里是否跳过了对齐——只要深度和彩色分别来自两个传感器，就必须先align。跑measure示例可直观对比对齐前后：点两个像素量距离，未对齐时结果随距离漂移。

场景三：嵌入式设备上帧率掉到 15 以下。用depth-quality工具确认硬件本身能跑满 30fps 后，问题在 CPU 侧。优先加decimation_filter把深度降档（如 640×480→320×240），再检查是否开启了不需要的流（彩色流占用远大于深度）。每降一档分辨率，后处理和下游算法的开销同步减半。

❓ 安装与平台高频问题

行动清单

1. 今天：按第一节四行命令编译，跑通realsense-viewer看到深度画面。
2. 本周：把hello-realsense改成你要测的像素点，加上align与temporal滤波器，用record_to_file存一段现场数据。
3. 之后：遇到怪问题先看 doc/troubleshooting.md，涉及多语言集成再浏览 wrappers/ 里现成的绑定。

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