企业官网建设流程全解析

RealSense SDK 2.0 在 Windows 平台的完整分发与安装指南：二进制安装、源码构建与帧元数据启用

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

RealSense™ SDK 2.0（librealsense）为 Windows 平台提供了一套开箱即用的二进制发行方案：用户既可以直接下载预编译的RealSense.Viewer.exe与RealSense.SDK.exe快速体验深度相机并完成 SDK 安装，也可以使用 CMake 与 Visual Studio 从源码自行构建。本文以仓库中的 Windows 发行说明 为主线，完整覆盖预编译发行包的使用流程、安装器逐步操作、从源码构建的配置要点，并结合 Windows 安装指南 与仓库源码，深入讲解 Windows 平台帧元数据（Frame Metadata）的启用原理、注册表配置和 CMake 构建选项，帮助开发者在 Windows 10/11 上从零搭建可用的 RealSense 开发环境。

本文聚焦于 Windows 平台的分发与安装环节。若需了解 Linux 平台对应的 dpkg 包安装与内核补丁流程，可参阅 Linux 发行说明；若需了解帧元数据的软件设计与查询 API，可继续阅读 帧元数据设计文档。

前置认知：Windows 上如何获得 SDK

RealSense™ SDK 2.0 在 Windows 上的获取途径有两条，分别对应不同场景：

1. 预编译二进制发行：官方在项目的 GitHub Releases 页面发布打包好的安装程序，涵盖 RealSense Viewer 独立程序（Intel.RealSense.Viewer.exe）与完整 SDK 安装器（RealSense.SDK.exe）。适合快速验证硬件、安装运行库并获取各语言开发包。
2. 源码构建：克隆仓库后使用 CMake 与 Visual Studio 从源码编译。适合定制功能、集成进现有工程或使用非标准构建选项（如强制启用元数据支持）的场景，完整步骤见 Windows 10 & 11 源码安装指南。

在开始任何操作之前，将 RealSense 深度相机插入主机的USB3 端口，然后打开 Windows 的“设备管理器”（Device Manager），在“图像设备”（Imaging Devices）分类下应能看到新接入的设备，例如Intel(R) RealSense(TM) Camera D415 Depth：

如果设备未出现在设备管理器中，请先排查 USB 端口类型与线缆是否满足 USB3 规格，再继续后续安装步骤。

快速体验：使用 RealSense Viewer

RealSense Viewer 是官方提供的图形化工具，用于直接预览深度、彩色、红外等流数据，无需编写任何代码。

1. 前往项目 Releases 页面的latest stable release（最新稳定版），展开Assets资源区，下载并运行Intel.RealSense.Viewer.exe：

2. 启动后即可浏览相机的深度数据：

Viewer 不仅能实时显示深度图，还集成了后处理滤镜、测量、点云等功能，是验证相机硬件与 SDK 运行状态最快捷的手段。若 Viewer 无法识别相机，可参考文末的故障排查小节。

安装 SDK：RealSense.SDK.exe 安装器

若需要在系统层面安装完整的 SDK（包含运行时库、头文件、各语言开发包以及 RealSense Viewer），请下载并运行RealSense.SDK.exe，然后按以下步骤完成安装：

1. 许可协议：RealSense™ SDK 2.0 采用 Apache 2.0 宽松开源许可证，安装向导第一步会展示该许可条款（界面见 win_step1）。
2. 组件选择：SDK 同时包含 RealSense Viewer 以及针对多种编程语言（如 Python、C#、MATLAB 等）的开发包，可按需勾选（界面见 win_step2）。
3. 快捷方式：批准在桌面创建两个快捷方式（界面见 win_step3）。
4. 安装前审查：确认安装路径与组件列表后进入安装（界面见 win_step4）。
5. 打开示例工程：安装完成后，打开随 SDK 分发的RealSense™ Samples解决方案（界面见 win_shortcuts）。
6. 编译运行示例：在 Visual Studio 中按F5编译并运行示例程序（界面见 win_samples）。
7. 完成：至此 SDK 安装成功，可以开始基于 RealSense API 开发应用。

安装器同时会部署设备驱动与必要的运行时组件，因此安装完成后建议重新插拔一次相机，确保驱动正确加载。

从源码构建：CMake + Visual Studio

对于需要定制构建或集成源码的开发场景，仓库提供了完整的 CMake 构建体系，整体入口为 根 CMakeLists.txt。

构建环境要求

• CMake v3.10+（仓库根 CMakeLists.txt 中cmake_minimum_required(VERSION 3.10)即为最低版本约束）；
• Visual Studio 2019 或更新版本——MSVC2015 及更老的编译器不完全兼容项目所使用的 C++14 特性集；
• 不支持虚拟机：由于宿主机与虚拟机之间存在 USB 3.0 转换层，官方不推荐也不支持在 VM 中安装使用，请在物理机上操作。

CMake 配置要点

在 CMake GUI 中指定源码目录与构建目录，点击 Configure 后即可看到大量可调选项。务必勾选BUILD_EXAMPLES，否则不会编译官方示例程序：

常用的构建选项在 CMake/lrs_options.cmake 中定义，Windows 场景下值得关注的包括：

Windows 专属的构建行为

仓库在 CMake/windows_config.cmake 中集中处理了 Windows 平台的构建细节，理解这些行为有助于排查构建与运行问题：

• 输出目录统一：CMAKE_LIBRARY/RUNTIME/ARCHIVE_OUTPUT_DIRECTORY全部指向构建根目录，便于示例与测试运行时找到动态库；
• Debug 库命名：为 MSVC 设置CMAKE_DEBUG_POSTFIX "d"，使 Debug 构建的库带有d后缀，避免与 Release 版本产生命名冲突；
• 并行编译：追加/MP编译标志，支持多核并行构建；
• 后端选择：Windows 7 下强制启用 RSUSB（WinUSB）后端（RS2_USE_WINUSB_UVC_BACKEND），其余 Windows 版本默认使用 WMF（Media Foundation）后端（RS2_USE_WMF_BACKEND）；
• 安全标志：启用ENABLE_SECURITY_FLAGS后会追加/Gy /DYNAMICBASE /GS等安全相关标志，Release 构建还会加上/WX（警告即错误）、/sdl与链接期/LTCG /NXCOMPAT等强化项；
• Win7 驱动打包：启用 RSUSB 后端时，构建系统会把 src/win7/drivers/IntelRealSense_D400_series_win7.inf 等驱动文件复制到构建目录的drivers/下，供 Win7 目标机安装使用。

从源码结构看，WMF 后端实现在 src/mf/（如 mf-backend.cpp、mf-uvc.cpp、mf-hid.cpp），而 Win7 的 RSUSB 后端则在 src/win7/，其入口 rsusb-backend-windows.cpp 通过create_backend()创建rs_backend_windows实例，并配套基于轮询的polling_device_watcher监听设备热插拔。

在 Windows 上启用帧元数据（Frame Metadata）

帧元数据是随每一帧生成的一组传感器配置与系统状态参数，是高级应用（如自动曝光调优、帧同步调试）依赖的能力。默认情况下 Windows 系统不会为视频设备暴露元数据通道，需要按以下步骤显式启用。完整的元数据设计原理可参考 帧元数据文档。

前置条件

• Windows 10 且使用管理员账户登录（Windows 11 亦可）；
• 安装 WinSDK 10（版本 10.0.15063 或更高）——较老的 SDK 不包含 UVC 元数据支持所需的 API。

验证步骤：

1. 在终端运行winver命令，确认系统版本为 Windows 10（Build 15063 或更高，官方推荐 17763+）或 Windows 11：

2. 打开“控制面板” → “程序和功能”，双击 “Microsoft Visual Studio” 并选择 “修改”，在组件列表中确认已勾选 10.0.10586 或更高版本的 SDK，缺失则补充安装：

方式一：使用自动化脚本（推荐）

仓库提供了现成的 PowerShell 脚本 scripts/realsense_metadata_win10.ps1，它能够自动扫描已连接的 RealSense 设备并在注册表中写入对应的元数据键。

以管理员身份启动 PowerShell，切换到脚本所在目录后运行：

# 为当前已连接的 RealSense 设备添加元数据注册表键（等价于 -op install） PS > .\realsense_metadata_win10.ps1 # 也可显式指定操作参数 PS > .\realsense_metadata_win10.ps1 -op install # 为已连接设备添加键 PS > .\realsense_metadata_win10.ps1 -op install_all # 为注册表中所有（含历史）RealSense 设备添加键 PS > .\realsense_metadata_win10.ps1 -op remove # 移除已连接设备的键 PS > .\realsense_metadata_win10.ps1 -op remove_all # 移除所有 RealSense 设备的键

脚本支持的四个操作参数语义如上：install/install_all分别对应“仅已连接设备”与“注册表内全部设备”，remove/remove_all为对应的清理操作；不传参数时等价于install。

若提示... cannot be loaded because running scripts is disabled on this system，先执行以下命令放开脚本执行策略，回答Y后重新运行：

PS > Set-ExecutionPolicy RemoteSigned

从 脚本源码 可以看到其核心逻辑：它遍历HKLM:\SYSTEM\CurrentControlSet\Control\DeviceClasses下两个元数据相关的 GUID 分支（{e5323777-f976-4f5b-9b55-b94699c46e44}与{65E8773D-8F56-11D0-A3B9-00A0C9223196}），筛选 VID 为8086（Intel）的 UVC 设备记录，并在每台设备的#global\Device Parameters下写入MetadataBufferSizeInKB0（值为 5）。对于脚本内置$MultiPinDevices列表中的多接口设备（涵盖 D400/D410/D415/D420/D430/D435/D435i/D405/D455/D460/D465/L500/L515/L535 等型号，以USB\VID_8086&PID_xxxx&MI_00形式匹配），还会追加MetadataBufferSizeInKB1（以及MetadataBufferSizeInKB2）键，值同样为 5。

重要提示：注册表键是与设备一一对应的（键名包含设备实例路径），因此每接入一台新的 RealSense 设备都必须重新执行一次该脚本。

方式二：手动修改注册表

若因权限或其他原因无法执行脚本，可手动完成配置：

1. 连接 RealSense 设备，打开“控制面板” → “设备管理器”，找到 RealSense 设备条目（例如RealSense™ Camera D415 Depth）：

   • 通过属性页找到设备的Device instance path（设备实例路径）（Step 2）；
   • 同时记下该设备暴露的附加接口（Step 3）：

2. 使用regedit导航到HKLM\SYSTEM\CurrentControlSet\Control\DeviceClasses\{e5323777-f976-4f5b-9b55-b94699c46e44}分支；

3. 展开与上一步Device instance path 同名的子目录，进入#GLOBAL→Device Parameters；

4. 添加一个DWORD (32 位)值，名称为MetadataBufferSizeInKB0，值为5；

5. 对于 RS400 系列设备的零号接口（形如##?##USB#VID_8086&PID... MI_00），再添加DWORD (32 位)值MetadataBufferSizeInKB1，值同样为5（对应脚本中多接口设备需要额外键的逻辑）：

6. 对另一分支HKLM\SYSTEM\CurrentControlSet\Control\DeviceClasses\{65E8773D-8F56-11D0-A3B9-00A0C9223196}重复上述操作；

7. 对设备管理器中列出的每一个RealSense 设备（如RealSense™ Camera D415 RGB等）重复整个过程。

编译开启元数据支持

编译阶段，构建系统会根据所选 WinSDK 版本自动检测并启用/禁用元数据功能。若所选 WinSDK 不暴露元数据接口，编译时会收到如下提示，说明本次构建不包含元数据生成能力：

Librealsense notification: Featuring UVC Metadata requires WinSDK 10.0.10586.0 toolset. The library will be compiled without the metadata support!

要强制开启，请在 CMake 配置阶段勾选ENFORCE_METADATA选项。该选项在 CMake/lrs_options.cmake 中定义（默认 OFF，注释明确“Windows OS Only”），并在 CMake/global_config.cmake 中通过add_definitions(-DENFORCE_METADATA)注入编译定义。设置后，编译器会校验目标 WinSDK 版本，若与元数据要求不兼容则直接中止构建。

另外，当系统安装了多个 WinSDK 版本时，CMake 默认选择最新版本；若自动选择失败，可在 Visual Studio 中手动将解决方案重新定向（Retarget）到合适的 WinSDK 版本（见 win_retarget_platform）。

常见问题排查

小结

Windows 平台下的 RealSense SDK 2.0 提供了“下载即用”与“源码构建”两条并行的落地路径：普通用户可通过 Releases 页面的 Viewer 与 SDK 安装器快速部署；开发者则可基于 CMake 3.10+ 与 Visual Studio 2019+ 从源码定制构建，并通过ENFORCE_METADATA等选项控制功能边界。帧元数据的启用涉及“系统注册表配置 + 编译期选项”两个层面，仓库中的 realsense_metadata_win10.ps1 脚本与 windows_config.cmake 分别为这两个层面提供了自动化与可配置的支撑。完成上述步骤后，即可基于 官方示例 开始 RealSense 应用开发。

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