librealsense 双层级 API 架构详解从 High-Level Pipeline 到 Low-Level Device 的完整实践指南【免费下载链接】librealsenseRealSense SDK项目地址: https://gitcode.com/GitHub_Trending/li/librealsenseRealSense SDKlibrealsense通过一套分层 API 向开发者开放 RealSense 深度相机的配置、控制与数据流能力High-Level Pipeline API让应用开发者几行代码即可获得最佳默认配置、自动线程管理与时间同步的帧流Low-Level Device API则将单个传感器、全部相机参数、流线程、时间同步与空间映射的控制权直接交给高级研究人员、框架/工具开发者以及 VR/AR 等新兴领域开发者。本文以仓库文档 doc/api_arch.md 为骨架结合 src/pipeline、include/librealsense2/hpp 等源码实现系统讲解两层 API 的设计动机、核心类与方法、处理块Processing Blocks的用法以及底层传感器模型与回调机制帮助你根据自身角色选择正确的 API 层级。为什么需要两套 API一个 SDK两种控制粒度RealSense 设备是高度可配置的硬件既有普通 RGB 摄像头这样的常见传感器也有 D400 立体模块、结构化光传感器这类专有硬件。针对不同使用者的诉求librealsense 提供了两条互补的路径High-Level Pipeline API由pipeline类自动选择最佳推荐设置、配置并激活相机、管理各流线程并输出时间同步的帧。它同时封装了底层设备接口因此传感器的信息与微调能力仍然可达。推荐面向应用开发者Application Developers。Low-Level Device API直接控制单个设备传感器、微调全部相机设置、管理流线程、时间同步与空间映射。推荐面向高级研究人员Advanced Researchers、框架与工具开发者以及 VR/AR 等新兴领域开发者。两套 API 并非互斥pipeline 内部封装了 device 接口见 src/pipeline/pipeline.h 中std::shared_ptrdevice_interface _dev成员与get_device()方法因此你在使用高层 API 的同时仍可通过pipeline_profile::get_device()拿到底层设备句柄进行传感器级操作。High-Level Pipeline API开箱即用的相机流水线pipeline 类从设备到帧的一站式封装pipeline类位于 src/pipeline/pipeline.h其核心职责是根据应用所需的输出流类型、分辨率、格式、帧率选出最佳相机设置获取并激活相机管理不同流的线程并提供时间同步的帧。从源码结构看它内部持有device_hub设备发现与等待、syncer_process_unit内部同步单元与aggregator帧聚合器三个关键组件共同完成选设备 → 配流 → 拉帧 → 同步聚合的完整链路。其顶层 API 由以下方法构成与 C APIrs2_pipeline_*一一对应声明见 include/librealsense2/hpp/rs_pipeline.hpp方法作用start()/start(config)以默认配置或指定配置启动流返回实际生效的pipeline_profile管道已在运行时再次调用会抛异常stop()停止流wait_for_frames(timeout_ms)阻塞等待直到一组时间同步的帧可用默认超时 5000ms超时抛异常poll_for_frames(frameset*)非阻塞查询有可用帧集立即返回 true否则 falsetry_wait_for_frames(frameset*, timeout_ms)超时返回 bool 的等待版本不抛异常最典型的最小用法对应示例 examples/hello-realsense/rs-hello-realsense.cpp 与 examples/capture/rs-capture.cpp#include librealsense2/rs.hpp rs2::pipeline pipe; pipe.start(); // 默认配置自动选择首台可用设备与流 while (true) { rs2::frameset frames pipe.wait_for_frames(); // 时间同步的帧集 auto depth frames.get_depth_frame(); // ... 处理 depth }config 类精确声明你想要的流pipeline不传参start()时使用默认配置自动选择第一台可用设备并启用第一组彩色 深度流。若要精确控制使用config类C 封装见 include/librealsense2/hpp/rs_pipeline.hpp内部实现见 src/pipeline/config.h。config提供多组重载的enable_stream()所有未指定参数均以0表示任意dont carers2::config cfg; cfg.enable_stream(RS2_STREAM_DEPTH, 640, 480, RS2_FORMAT_Z16, 30); // 深度分辨率格式帧率 cfg.enable_stream(RS2_STREAM_COLOR, 1920, 1080, RS2_FORMAT_BGR8, 30); // 彩色 cfg.enable_stream(RS2_STREAM_INFRARED, 1); // 只指定流类型与索引 pipe.start(cfg);enable_stream的重载组合均声明于 include/librealsense2/hpp/rs_pipeline.hppenable_stream(stream_type, stream_index, width, height, format, framerate)最完整的形式enable_stream(stream_type, stream_index)仅流类型与索引其余内部解析enable_stream(stream_type, width, height, format, framerate)指定分辨率索引取任意enable_stream(stream_type, format, framerate)指定格式与帧率enable_stream(stream_type, stream_index, format, framerate)指定索引与格式。config的其余重要方法方法作用enable_all_streams()显式启用设备全部原始流流列表依设备而定enable_device(serial)按序列号锁定设备序列号取自RS2_CAMERA_INFO_SERIAL_NUMBER便于在启动前设置传感器选项enable_device_from_file(file, repeat_playback true)从录制文件回放设备与enable_record_to_file互斥enable_record_to_file(file)要求解析到的设备录制到文件与enable_device_from_file互斥disable_stream(stream, index -1)清除某流的过滤请求仍可能因管线模块需求被启用disable_all_streams()清除全部流过滤请求resolve(pipeline)解析过滤条件返回匹配的设备与流配置不实际应用到设备可在启动前用于预检与设备控制can_resolve(pipeline)布尔版预检判断当前条件下是否存在有效配置从 src/pipeline/config.h 可以看到配置解析的关键逻辑config内部维护_stream_requests流请求表、_device_request序列号/文件请求与_enable_all_streams标志resolve()会先处理设备请求真实设备或回放设备再通过get_default_configuration()取得设备默认配置最后用filter_stream_requests()在默认配置上叠加用户过滤条件。多个enable_stream调用同一流时后者覆盖前者resolve()时才做冲突检查。处理块Processing Blocks同步、对齐与点云投影Pipeline API 配套一组处理块将相机原始数据的常见处理抽象为即插即用的组件C 实现位于 include/librealsense2/hpp/rs_processing.hppsyncer按硬件时间戳同步异步流syncer类include/librealsense2/hpp/rs_processing.hpp 第 699 行起依据硬件时间戳将任意一组异步流整理为相干帧集coherent set。构造时可指定内部队列大小syncer(int queue_size 1)并提供wait_for_frames(timeout_ms 5000)、poll_for_frames(frameset*)与try_wait_for_frames(frameset*, timeout_ms)三种取帧方式与 pipeline 的取帧语义保持一致。其底层由asynchronous_syncersrc/sync.h驱动帧经内部处理线程送入frame_queue。rs2::syncer sync; // 将各流帧送入 syncsync 可作函数对象调用sync(frame) // rs2::frameset fs sync.wait_for_frames();align将流对齐到统一视口align类第 766 行起使用深度数据与相机标定参数完成图像对齐。构造参数align_to指定对齐目标流将深度图对齐到彩色图align(RS2_STREAM_COLOR)将非深度图对齐到深度图align(RS2_STREAM_DEPTH)相机标定与流的类型在第一次传入有效帧集时动态确定determined on the fly。用法rs2::align align_to_color(RS2_STREAM_COLOR); rs2::frameset aligned align_to_color.process(frames); // 返回对齐后的帧集文档特别指出你也可以使用自己的标定数据去对齐未经出厂标定的设备——这为多相机、异源设备的对齐场景留出了扩展空间。完整示例见 examples/align/rs-align.cpp 与 examples/align-advanced/rs-align-advanced.cpp。pointcloud将深度数据投影到 3D 空间pointcloud类第 429 行起基于深度帧生成 3D 点云并可将彩色帧映射为纹理rs2::pointcloud pc; rs2::points pts pc.calculate(depth_frame); // 由深度帧计算点云 pc.map_to(color_frame); // 将点云映射到彩色帧作为纹理构造时可指定pointcloud(stream, index)以限定点云来源流。示例见 examples/pointcloud/rs-pointcloud.cpp点云数据类型的底层实现见 src/points.cpp。未来扩展计算机视觉插件文档还预告了 pipeline 未来的computer vision plugins能力插件可以基于相机流便捷地丰富输出pipeline 会保证这些插件的所有同步与对齐需求得到满足并负责线程与资源管理。当前仓库中与之相关的接口是 src/core/processing-block-interface.h 与 src/core/pp-block-factory.h 定义的处理块工厂体系——pipeline 正是处理块接口的消费者而应用消费的是计算机视觉接口参见 include/librealsense2/hpp/rs_pipeline.hpp 中pipeline类的注释。Low-Level Device API逐传感器、逐参数的完全控制设备-传感器-流的三层硬件模型RealSense 设备由多个传感器sensor构成既有常见的 RGB 摄像头也有 D400 立体模块、结构化光传感器这类专有硬件Low-Level Device API 让你直接控制每个传感器其核心设计原则来自 doc/api_arch.md每个传感器拥有独立的电源管理与控制不同传感器可被不同应用安全使用彼此只能间接影响每个传感器可提供一条或多条数据流图像、运动流必须一起配置且通常相互依赖——例如 D400 深度流依赖红外数据因此这些流必须以单一分辨率一起配置流是最小能力基线每个传感器可扩展出额外功能——例如多数视频设备允许用户为自动曝光机制配置自定义感兴趣区域ROI标准视频传感器遵循 UVC / HID 规范无需自定义驱动即可使用。传感器接口枚举、配置与流控制底层接口的 C API 集中在 include/librealsense2/h/rs_sensor.hC 封装在 include/librealsense2/hpp/rs_sensor.hpp核心流程为// 1. 枚举设备与传感器 rs2::context ctx; auto devices ctx.query_devices(); // 连接的所有设备 auto dev devices[0]; auto sensors dev.query_sensors(); // 设备上的所有传感器 // 2. 查询传感器的流配置 auto profiles sensor.get_stream_profiles(); // 支持的流配置列表 // 3. 打开指定配置的流并注册帧回调 sensor.open(profile); sensor.start([](rs2::frame f) { /* 新帧到达时回调 */ }); sensor.stop(); sensor.close();关键要点rs2::sensor是低层 API 的操作主体open打开流、start启动并挂接回调、stop/close关闭传感器的选项曝光、增益、白平衡、自动曝光 ROI 等通过选项接口查询与设置get_option/set_option声明见 include/librealsense2/hpp/rs_options.hpp底层实现在 src/option.cpp通过sensor.isrs2::roi()/sensor.asrs2::roi()可探测并启用扩展能力如 ROI 扩展声明于 src/core/roi.h传感器能力的分发机制基于扩展extension体系核心定义见 src/core/extension.h 与 src/core/has-features-interface.h。帧回调模型OS 线程上的最低延迟低层 API 的取帧模型与高层完全不同用户提供一个回调callback每当新数据帧可用时被调用。这个回调直接在产生数据的 OS 线程上执行从而提供可能的最佳延迟——代价是需要你在回调内部自行处理线程安全与耗时操作不应在回调中执行阻塞操作。回调返回的帧携带与其流类型相关的数据类型例如视频流帧数据包含图像分辨率以及解析原始缓冲区的信息视频帧接口见 include/librealsense2/hpp/rs_frame.hpp底层实现在 src/frame.cpp。D400 Advanced Mode直接操控深度生成 ASIC 寄存器文档特别指出RealSense D400 立体模块提供Advanced Mode功能允许你控制负责深度生成的各个 ASIC 寄存器。这一能力的实现位于 src/ds/advanced_mode公开接口为 include/librealsense2/rs_advanced_mode.h命令定义见 include/librealsense2/h/rs_advanced_mode_command.h。典型用法rs2::context ctx; auto dev ctx.query_devices()[0]; if (dev.isrs2::advanced_mode()) // 探测是否支持高级模式 { auto advanced dev.asrs2::advanced_mode(); rs2::depth_table_control dtc advanced.get_depth_table(); // 读取当前深度表参数 dtc.depthUnits 1000; // 调整深度单位 advanced.set_depth_table(dtc); // 写回 ASIC }Advanced Mode 的完整操作示例见 examples/sensor-control/rs-sensor-control.cpp更多高级参数说明可参考 doc/rs400/rs400_advanced_mode.md。两层 API 的协作如何同时获得便利与掌控实践中两层 API 经常组合使用。推荐的协作模式用configresolve()预检配置在启动 pipeline 前调用cfg.resolve(pipe)获得将生效的设备与流配置此时配置不会被应用到设备你可以安全地读取设备信息锁定设备后做传感器级预设通过cfg.enable_device(serial)锁定设备再通过resolve()返回的pipeline_profile::get_device()设置传感器选项或扩展如高级模式、ROI然后才pipe.start(cfg)运行中混合使用pipeline 启动后get_active_profile().get_device()返回的仍是对底层设备的访问句柄可用于运行时的选项微调。注意约束文档与头文件注释均明确——pipeline 控制着设备的流配置、激活状态与帧读取直接调用 device API 中执行这些操作open/start/stop 等的函数会导致未定义行为见 include/librealsense2/hpp/rs_pipeline.hpp 中pipeline_profile::get_device()的注释。设备与传感器选项的查询和设置则不受此限制。选择指南你该用哪一层你的角色推荐 API理由应用开发者App DeveloperHigh-Level Pipeline API关注相机输出本身无需微调设置或控制流线程syncer/align/pointcloud处理块覆盖常见需求高级研究人员Low-Level Device API需要逐传感器、逐参数的完全控制与自定义同步/映射框架与工具开发者Low-Level Device API需要将 SDK 嵌入自己的抽象层掌控线程与资源VR/AR 等新兴领域开发者Low-Level Device API依赖精确的时间同步与空间映射能力快速原型 / 演示High-Level Pipeline API默认配置即可出帧几分钟内跑通延伸阅读高层 API 完整 C 接口include/librealsense2/hpp/rs_pipeline.hpp处理块syncer/align/pointcloud/filter 体系include/librealsense2/hpp/rs_processing.hpp底层传感器 C/C 接口include/librealsense2/h/rs_sensor.h、include/librealsense2/hpp/rs_sensor.hpppipeline 内部实现src/pipeline/pipeline.cpp、src/pipeline/config.cpp可运行示例examples/hello-realsense/rs-hello-realsense.cpp、examples/capture/rs-capture.cpp、examples/align/rs-align.cpp、examples/pointcloud/rs-pointcloud.cpp、examples/sensor-control/rs-sensor-control.cpp高级模式说明doc/rs400/rs400_advanced_mode.md【免费下载链接】librealsenseRealSense SDK项目地址: https://gitcode.com/GitHub_Trending/li/librealsense创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
