企业官网建设流程全解析

RealSense 与 OpenVINO 集成实战指南：用 Depth 相机驱动人脸与物体检测示例

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

本指南以 wrappers/openvino 目录为核心，系统讲解如何将 RealSense 深度相机与 Intel OpenVINO™ 推理工具包结合，完成人脸检测与基于 MobileNet-SSD 的物体检测，并利用深度帧为每个检测目标估算物理距离。读完本文，你将掌握 OpenVINO 示例的 CMake 集成方式、模型下载与版本适配机制、异步推理调用链，以及深度对齐与距离标注的完整实现方案。

示例定位：补齐 SDK 示例之外的 AI 能力

wrappers/openvino/readme.md 开宗明义：本目录下的示例旨在补充现有 SDK examples（如 capture、pointcloud、align 等纯感知与可视化示例），专门演示 RealSense 相机与 OpenVINO™ 工具包在计算机视觉（computer-vision）领域的协同工作方式。

目录下提供两个可独立构建运行的示例：

其中 dnn 示例与 wrappers/opencv/dnn 中的 OpenCV DNN 示例使用完全相同的神经网络，便于在同一模型下对比 OpenVINO 与 OpenCV 两种推理后端的集成方式与效果。

版本支持与适配机制

原文档明确列出该示例集设计并测试过的 OpenVINO 版本：

2019.3.379、2020.3.194、2020.4.287、2021.1.110、2021.3.394

使用其他版本可能需要修改代码。版本适配的核心逻辑在 wrappers/openvino/check_vino_version.cmake 中实现：CMake 通过探测特定文件是否存在来判断 OpenVINO 版本代际——

• 若存在{INTEL_OPENVINO_DIR}/inference_engine/src/extension/ext_list.hpp，判定为2019 或更低（OPENVINO2019），使用旧版CNNNetReaderAPI 读取模型、依赖ie_cpu_extension库；
• 若存在{INTEL_OPENVINO_DIR}/deployment_tools/ngraph/include/ngraph/ngraph.hpp，判定为2020.1 或更高（OPENVINO_NGRAPH），使用InferenceEngine::Core::ReadNetwork读取模型、链接 nGraph 库。

对应地，wrappers/openvino/CMakeLists.txt 依据这两个宏选择不同的依赖集合与头文件目录。也就是说，同一份示例源码通过宏开关同时兼容了 2019 与 2020+ 两代 OpenVINO API——这正是示例能在多个版本上运行的关键设计。

构建前置条件

在开始任何 OpenVINO 安装之前，强烈建议先查阅 OpenVINO 官方的 Getting Started 指南（本指南并不试图替代它）。示例本身还需满足以下两项前置：

1. OpenVINO Toolkit：示例通过 CMake 变量INTEL_OPENVINO_DIR定位安装目录，CMakeLists.txt 中该变量默认为空，若未配置或路径无效会直接报FATAL_ERROR: Invalid OpenVINO directory specified with INTEL_OPENVINO_DIR；
2. OpenCV：OpenCV 是这些示例的硬性依赖（OpenVINO 本身并不强制要求），需要通过 CMake 变量OpenCV_DIR指向 OpenCV 的安装或构建目录（例如C:/work/opencv/build）。更省事的做法是直接使用 OpenVINO 自带的 OpenCV，在 CMake 命令行追加：

-DOpenCV_DIR=<openvino-dir>/opencv/cmake

关于 OpenCV 与 RealSense 的更多集成方式，可参考 OpenCV samples。

提示：在 dnn/CMakeLists.txt 中，若OpenCV_DIR未定义或不是有效目录，同样会以FATAL_ERROR终止配置，说明 OpenCV 缺失时示例无法构建。

Windows 平台安装与配置

以下步骤基于将 OpenVINO 安装到C:\work\intel\openvino的假设（原文全部命令以此路径为基准，请按实际安装位置替换）。

1. 打开命令行并初始化环境

> cd C:\work\intel\openvino

2. 确保 Python 可用并加载环境变量

OpenVINO 的模型工具链依赖 Python 及其脚本（如pip），若缺失会引发各类失败。建议显式将 Python 与 Scripts 目录加入PATH，然后运行环境脚本：

> set "PATH=%PATH%;C:/Program Files (x86)/Microsoft Visual Studio/Shared/Python36_64;C:\Program Files (x86)\Microsoft Visual Studio\Shared\Python36_64\Scripts" > bin\setupvars.bat

3. 安装模型优化器（Model Optimizer）前置依赖

> cd deployment_tools\model_optimizer\install_prerequisites > install_prerequisites.bat ...

注意事项（原文档实测经验）：networkx库曾因 API 变更引发问题，手动回退到1.11版本后一切正常。注意事项：若需重做本步或后续步骤，建议先清理此前安装的包。默认情况下 OpenVINO 会将其安装到C:\Users\<user>\Documents\Intel\OpenVINO。

4. 运行官方演示脚本完成附加配置

> cd ../../demo > demo_squeezenet_download_convert_run.bat ... > demo_security_barrier_camera.bat ...

这些脚本会下载并转换示例模型、验证推理环境，是确认 OpenVINO 安装可用的快速手段。

5. 下载模型

> python tools/model_downloader/downloader.py --all --output_dir C:\Users\<user>\Documents\Intel\OpenVINO\models

该命令会下载 OpenVINO 模型库（model zoo）中的全部预训练模型，耗时较长。如果只想跑示例，也可以只下载所需模型（见下文模型自动下载机制）。

6. 转换额外公共模型

部分模型以源码格式（TensorFlow 等）存放在public目录，需转换为 OpenVINO IR 格式后才能使用。转换命令如下：

> cd C:\Users\${USER}\Documents\Intel\OpenVINO\models > python C:\work\intel\openvino\deployment_tools\tools\model_downloader\converter.py --name faster_rcnn_resnet101_coco [--mo C:\work\intel\openvino\deployment_tools\model_optimizer\mo.py]

--name指定要转换的模型名，--mo可选地显式指定 Model Optimizer 入口脚本路径。

与示例项目的 CMake 集成

完成上述环境准备后，构建示例的方式在 CMakeLists.txt 中可见一斑：项目名为RealsenseOpenVINSamples，通过include(${INTEL_OPENVINO_DIR}/inference_engine/share/InferenceEngineConfig.cmake)引入 Inference Engine 的 CMake 配置，随后依据版本宏组装DEPENDENCIES，并将rs-vino目录下的共享辅助类（base-detection、object-detection、detected-object与openvino-helpers）与 EasyLogging++（ELPP）源码一并编译进每个示例可执行文件。

Linux 平台安装与配置

Linux 下的步骤与 Windows 高度相似，原文档归纳为三步：

1. 下载最新版 OpenVINO 工具包，并遵循官方 Linux 安装指南（与上述 Windows 步骤非常类似）；
2. 按 librealsense 安装文档 从源码构建librealsense，但 CMake 命令需追加三个关键选项：

   -DBUILD_OPENVINO_EXAMPLES=true -DOpenCV_DIR=... -DINTEL_OPENVINO_DIR=...

   其中BUILD_OPENVINO_EXAMPLES是总开关，OpenCV_DIR指向 OpenCV，INTEL_OPENVINO_DIR指向 OpenVINO 安装根目录；

3. 运行示例前确保$LD_LIBRARY_PATH指向 OpenVINO 库目录，执行source $INTEL_OPENVINO_DIR/bin/setupvars.sh即可完成设置。

模型文件：自动下载与手动放置

模型不在发行包中

OpenVINO 模型文件既不属于 librealsense 发行包，也不随 OpenVINO 分发，需要单独获取。wrappers/openvino/dl_vino_model.cmake 定义了一个dl_vino_model(filename sha1)函数：CMake 配置时按 SHA1 校验和从https://librealsense.realsenseai.com/rs-tests/OpenVINO_data（2019 版）或.../2020.1.033（新版）下载模型到CMAKE_CURRENT_BINARY_DIR（即各示例的构建目录）。例如 dnn/CMakeLists.txt 针对不同 OpenVINO 代际下载不同 IR 版本的mobilenet-ssd.xml/.bin（IRv10 仅用于 2020.1 及以后），以及mobilenet-ssd.labels与README.txt。

运行时依赖的放置规则

多数示例要求 DLL 或附属文件能在可执行文件同目录下被找到，而非写死绝对路径。例如可执行文件位于c:/work/lrs/build/Release，则缺失的 DLL 或模型文件应复制到同一目录（或修改代码中的查找路径）。以非 Debug 构建为例，需从${OpenCV_DIR}/bin复制以下 OpenCV DLL 到RelWithDebInfo输出目录：

opencv_core411.dll opencv_highgui411.dll opencv_imgcodecs411.dll opencv_imgproc411.dll opencv_videoio411.dll

CMake 运行时会自动将预训练模型放入各示例的构建目录。例如 face 示例的构建目录build/wrappers/openvino/face下会有三个文件：

README.txt face-detection-adas-0001.xml face-detection-adas-0001.bin

rs-face-vino.cpp 的异常处理中也有对应提醒：若模型加载失败，请将.bin与.xml两个文件复制到程序运行的工作目录，或修改构造函数中的模型路径。

推理设备选择与 CPU 扩展

OpenVINO 模型可加载到任意可用设备：CPU、GPU、Movidius™ 神经计算棒或 FPGA，前提是具备对应的.dll/.so运行库。示例默认使用CPU设备而非假定存在独立 GPU——在无独立显卡的环境下 CPU 往往反而更快，但读者完全可以自行实验切换设备。

设备名在源码中以字符串形式配置（rs-face-vino.cpp 中的std::string const device_name { "CPU" }，改成"GPU"即可切换，同时需移除AddExtension()调用）。使用 CPU 设备时，示例在运行时依赖cpu_extension.dll（Windows）或libcpu_extension.so（Linux）。若遇到缺少该组件的运行时错误，可从常规构建产物中找到它们，放到与模型文件相同的位置（当前目录或可执行文件旁）。

从源码看，2019 版通过engine.AddExtension(std::make_shared<openvino::Extensions::Cpu::CpuExtensions>(), device_name)显式注册 CPU 扩展（rs-face-vino.cpp）；而 OpenVINO 2020.1 起该扩展已并入 CPU 插件，此调用被宏#ifdef OPENVINO2019包住不再执行。另外 CMakeLists.txt 提供了BUILD_WITH_CPU_EXTENSIONS开关：关闭时会禁用 AVX2/AVX512F 指令集优化。

人脸检测示例（rs-face-vino）实现剖析

核心类：object_detection

示例将大部分 OpenVINO 细节封装进openvino_helpers::object_detection辅助类（定义于 wrappers/openvino/rs-vino/object-detection.h）。使用时只需两行：

openvino_helpers::object_detection faceDetector( "face-detection-adas-0001.xml", 0.5 // Probability threshold -- anything with less confidence will be thrown out );

• 第一个参数是模型 IR 文件（.xml）路径，同目录的.bin权重会被自动加载（源码中通过remove_ext(pathToModel) + ".bin"推导，见 object-detection.cpp）；
• 第二个参数是置信度阈值detectionThreshold，低于该值的检测结果会被丢弃。

该类继承自 base_detection，后者封装了InferenceEngine::ExecutableNetwork、InferRequest、批大小、异步标志等基础设施，并提供load_into(ie, deviceName)将网络加载到指定推理设备。

模型输入输出约束

object_detection::read_network()（object-detection.cpp 起）对模型有明确校验：

• 网络必须恰好有 1 个或 2 个输入，否则抛出std::logic_error；
• 4 维输入（如1,3,300,300）被识别为图像数据data，精度设置为U8；2 维输入（如1x3）被识别为可选的im_info（height, width, image_scale），精度为FP32；
• 输出层预期为DetectionOutput类型。

这些信息都可以在模型.xml文件中查看：搜索type="Input"层可找到输入，type="DetectionOutput"为期望的输出层。示例对 Faster R-CNN 这类双输入模型也做了适配尝试（填充im_infoblob，缩放因子置 1.0），鼓励读者自行试验其他模型。

异步推理流水线

检测采用异步模式：先排队当前帧，等下一帧到来时再取回上一帧的结果，从而将推理耗时与相机采集流水线重叠。核心调用链如下（rs-face-vino.cpp）：

// Wait for the results of the previous frame we enqueued: we're going to process these faceDetector.wait(); auto results = faceDetector.fetch_results(); // Enqueue the current frame so we'd get the results when the next frame comes along! faceDetector.enqueue( image ); faceDetector.submit_request();

在 object-detection.cpp 中，enqueue()负责将cv::Mat转换为 Inference Engine Blob（通过 openvino-helpers.h 中的matU8ToBlob模板实现，支持 1/3 通道、自动 resize），fetch_results()解析输出并生成带label、confidence、location（cv::Rect）的结果集合。

跨帧人脸跟踪：IoU 关联

检测结果会被放入容器并分配自增 ID。为避免同一张脸被反复当作新人脸创建，示例用IoU（Intersection over Union，交并比）关联新旧检测框：detected-object.cpp 的find_object()将当前检测框与上一帧所有人脸框计算交并比，阈值maxIoU = 0.35f——超过该值则视为同一张脸并直接移动旧框位置，否则才创建新的detected_object：

rect = rect & cv::Rect( 0, 0, image.cols, image.rows ); auto face_ptr = openvino_helpers::find_object( rect, prev_faces ); if( !face_ptr ) // New face face_ptr = std::make_shared< openvino_helpers::detected_object >( id++, rect ); else // Existing face; just update its parameters face_ptr->move( rect );

原文档对阈值选取给出了经验性说明：人脸位置越稳定，maxIoU可设得越高；人脸静止但变大/变小（靠近/远离相机）时 IoU 变化不大，而一旦移动 IoU 会迅速变小。

深度距离估算

关键技巧是先将深度帧与彩色帧做空间对齐（rs2::align align_to(RS2_STREAM_COLOR)，rs-face-vino.cpp），使彩色帧中人脸框中心像素与深度帧同一像素对应，随后直接查询深度：

auto center_x = r.x + r.width / 2; auto center_y = r.y + r.height / 2; auto d = depth_frame.get_distance( center_x, center_y );

得到的d（单位米）会被格式化输出到检测框上，实现"检测框 + 实时距离"的可视化（见 rs-face-vino.cpp）。原文档也提醒这是粗略估算：直接取框中心点，未做更精细的深度采样或滤波。

物体检测示例（rs-dnn-vino）实现剖析

rs-dnn-vino 复用与 face 完全相同的openvino_helpers::object_detection辅助代码，仅替换模型为面向通用物体检测的 MobileNet-SSD。运行效果从截图可见，它能识别tvmonitor、bottle、person等类别并同样输出以米为单位的距离（rs-dnn-vino.jpg）。

多模型热切换与 .labels 标签文件

示例自带一组 IR 文件（mobilenet-ssd.xml与.bin），但它会加载当前目录下的任意模型，并支持在运行时切换，便于实验不同网络。为此，rs-dnn-vino.cpp 定义了detector_and_labels结构：用cv::utils::fs::glob扫描磁盘上所有*.xml模型，为每个模型实例化检测器并加载其标签。

每个模型可附带一个可选的.labels分类文件，将输出的整数标签映射为可读名称（如person、bottle）。OpenVINO 模型库本身不提供这些文件，需要根据训练模型时的类别手动创建。格式参见示例附带的mobilenet-ssd.labels：每行一个分类，从 0 开始（第 0 行通常为背景）。加载逻辑在 openvino-helpers.h 的read_labels()中实现——逐行读取字符串；失败时仅告警并继续运行（rs-dnn-vino.cpp）。

性能取向

MobileNet 系列模型面向移动端设计，性能高、适合 CPU 实时推理；而更先进的模型可能精度或分类能力更强，但通常需要 GPU 或其他加速设备才能流畅运行。这与前文"默认 CPU 设备"的设计互为呼应。

从源码看整体调用链

将上述内容串起来，两个示例的运行主线是一致的：

1. 创建rs2::pipeline并start()，声明rs2::align将深度对齐到彩色流；
2. 创建InferenceEngine::Core（2019 版注册 CPU 扩展与错误监听error_listener，其将引擎错误转发到LOG(DEBUG)）；
3. 实例化object_detection（模型路径 + 置信度阈值），load_into()加载到指定设备；
4. 主循环：wait_for_frames()→align_to.process()→frame_to_mat()转cv::Mat→ 异步enqueue/submit_request→wait/fetch_results；
5. 对每个检测框做 IoU 跨帧关联、以框中心查询depth_frame.get_distance()，最后cv::rectangle+cv::putText可视化。

整个数据流横跨 RealSense SDK（采集与对齐）、OpenCV（图像格式与绘制）、OpenVINO Inference Engine（推理）三大组件，wrappers/openvino/rs-vino 目录正是这三者的胶水层。构建层面，wrappers/CMakeLists.txt 与各示例自身的 CMakeLists 共同完成依赖链接、宏定义（OPENVINO2019/OPENVINO_NGRAPH）、模型下载与安装（RUNTIME DESTINATION ${CMAKE_INSTALL_PREFIX}/bin）等全部工作。

常见问题与排错速查

结语

本目录的示例以最少的代码展示了 RealSense + OpenVINO 的完整闭环：采集、对齐、推理、跟踪、测距、可视化。无论是替换自定义模型（满足"单/双输入 + DetectionOutput"约束即可），还是切换推理设备（CPU/GPU/Movidius/FPGA），这套 rs-vino 辅助层都提供了清晰的扩展点。官方给出的适配版本为 2019.3.379 ~ 2021.3.394，实际使用时请以 check_vino_version.cmake 的版本探测结果为准。

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