Vuforia SDK overview

Vuforia 是一个跨平台的增强现实 (AR) 和混合现实 (MR) 应用程序开发平台，可在各种硬件（包括移动设备和混合现实头戴式显示器 (HMD)，如 Microsoft HoloLens）上实现强大的跟踪和性能。Unity 的 Vuforia 集成允许开发者使用拖放式创作工作流程为 Android 和 iOS 创建视觉应用和游戏。Unity Asset Store 提供了一个 Vuforia AR + VR 示例资源包，其中有几个有用的示例演示了该平台最重要的功能。

Vuforia 支持许多第三方设备（例如 AR/MR 眼镜）和具有后置摄像头的 VR 设备（例如 Gear VR）。请参阅 Vuforia 的设备 (Devices) 页面，查看受支持的设备的完整列表。请参阅 Vuforia API 参考，了解 SDK 中使用的类、属性和函数的更多相关信息。

可使用带摄像头的任何设备来测试使用 Vuforia 在 Unity 中构建的 AR/MR 游戏和应用程序。

重要概念

在进一步了解 Vuforia 及其支持的功能之前，需要了解许多重要概念。这些概念中包括 Vuforia 应用程序中常用的跟踪形式和标记类型。

基于标记的跟踪

在 AR 或 MR 中，标记是在应用程序中注册的图像或对象，它们在应用程序中充当信息触发器。当设备的摄像头在真实世界中识别到这些标记时（在运行 AR 或 MR 应用程序时），这会触发在摄像机视图中标记的世界位置上显示虚拟内容。基于标记的跟踪可以使用各种不同的标记类型，包括 QR 码、物理反射标记、图像目标和 2D 标签。游戏应用程序中最简单和最常见的标记类型是图像目标。

图像目标

图像目标是基于标记的跟踪中使用的特定标记类型。它们是您手动向应用程序注册的图像，并充当显示虚拟内容的触发器。对于图像目标，应使用包含具有复杂轮廓的不同形状的图像。这样可以方便进行图像识别并让跟踪算法更容易识别它们。

无标记跟踪

使用无标记跟踪的应用更常见于基于定位或基于位置的增强现实或混合现实。这种跟踪形式依赖于诸如 GPS、加速度计、陀螺仪和更复杂的图像处理算法之类的技术，才能将虚拟对象或信息置于环境中。然后，VR 硬件和软件便会将这些对象视为锚定或连接到特定的真实世界位置或对象。

Hardware and software requirements

This section provides an overview of both hardware and software requirements for using the Vuforia SDK with Unity.

为了运行使用 Vuforia SDK 创建的应用程序，需要采用支持的移动设备操作系统 (OS) 版本，下表列出了这些版本。该表还包括使用 Vuforia 开发应用程序时支持的操作系统和 Unity 版本。

Mobile devices

设备操作系统		开发操作系统		Unity 版本
Android (1)	4.1.x+	Windows (2)	7+	Windows (2)	2017.2+
iOS (2)	9+	OS X	10.11+	OS X	2017.2+
Windows (2)	10 UWP

1.仅 32 位 2.32 位和 64 位

Optical see-through digital eyewear

Vuforia SDK 支持一系列光学透视数码眼镜设备。下表列出了支持的设备及其所需的操作系统 (OS) 版本。该表还包括使用 Vuforia 为这些设备开发应用程序时支持的操作系统和 Unity 版本。

设备		设备操作系统		开发操作系统		Unity 版本
HoloLens	当前版本	Android (1)(2)	4.0.3+	Windows (3)	7+	Windows (3)	2017.2+
ODG	R7+	Windows (1)	10 UWP	OS X	10.11+	OS X	2017.2
Epson	BT–200

1.仅 32 位 2.4.0.3 Native 仅支持 Epson BT–200 3.32 位和 64 位

Vuforia 工具

有些 Vuforia 工具仅在特定硬件上受支持。下表列出了这些工具及其支持的设备和所需的操作系统版本。

应用程序	设备	操作系统版本
Calibration Assistant	Moverio BT–200 ODG R–7	Android 4.0.3+
Object Scanner	Samsung Galaxy S8+ Samsung Galaxy S8 Samsung Galaxy S7 Samsung Galaxy S6	设备上支持的最新操作系统

For more detailed information on these tools see the Vuforia Calibration Assistant and Object Scanner pages in the Vuforia developer library.

虚拟现实 SDK 集成支持

下面列出了完全集成到 Unity Editor 中的 VR SDK 以及首次集成它们的 Editor 发行版本。

VR SDK	版本
Google VR SDK	Unity 2017.2
Cardboard Android SDK	Unity 2017.2
Windows Mixed Reality（仅限 HoloLens）	Unity 2017.2

图形 API 支持

下表列出了在支持的操作系统上开发应用程序时 Vuforia 支持的所有图形 API。

Android	iOS	Windows
OpenGL ES 2.0 OpenGL ES 3.x	OpenGL ES 2.0 OpenGL ES 3.x Metal (iOS 8+)	Windows 10 上的 DirectX 11

• 有关将 Vuforia 与数码眼镜（例如 ODG R7+ 和 Epson BT–200）结合使用的更多信息，请参阅关于 Vuforia 数码眼镜应用的 Vuforia 文档

• 有关将 Vuforia 与 HoloLens 结合使用的更多信息，请参阅关于使用 Unity 中的 Hololens 示例的 Vuforia 文档

• 有关将 Vuforia 与 Google VR SDK 结合使用的更多信息，请参阅关于 Google Cardboard 开发的 Vuforia 文档

Quick start guide

This section provides instructions on setting up a Unity project with Vuforia as well as creating your first Vuforia application with Unity. Use this tutorial as a starting point for the development of your AR or MR application.

Project setup

为开发 Vuforia AR 或 MR 移动应用程序而设置项目的过程，与使用 Unity 进行移动平台的构建时设置的过程非常相似。Unity 安装程序包含 Vuforia SDK。请按照在 InstallingUnity 手册页上下载和安装 Unity 的说明进行操作。Vuforia 提供了一系列旨在放入场景中的预制件，从而为应用程序提供各种功能。所有这些预制件均可在 Unity Editor 中找到。

应遵循开发常规移动端游戏时所需的相同性能注意事项。有关移动设备优化的信息，请参阅有关移动端优化的 Unity 文档。

要使用 Unity 设置 Vuforia，请执行以下操作：

• 安装最新版本的 Unity，然后在安装程序的 Unity 组件选择部分中选择 Vuforia Augmented Reality Support 以及 iOS Build Support 或 Android Build Support 包。

注意：大多数 AR 和 MR 应用程序都以移动设备为目标，因此本指南重点关注 Android 和 iOS 的开发。请参阅 Android 和 iOS 入门文档了解如何为 Android 和 iOS 设备启用构建支持。

• 从 Vuforia 注册页面中创建 Vuforia 开发者帐户。通过此帐户可以访问一些必要的工具，从而在 Unity 中使用 Vuforia 开发 AR 和 MR 应用程序。

• 如果尚未创建 Unity ID，请从 Unity 注册页面中进行此操作。需要 Unity ID 才能从 Unity Asset Store 下载资源包。

• 打开 Unity 并创建新的 3D 项目（确保选中 Add Asset Package 按钮旁边的 3D 选项）。为项目命名，然后单击 Create project 按钮。

提示：从 Unity Asset Store 下载 Vuforia AR+VR Sample 资源包。此资源包提供了一些用于展示重要功能的有用示例场景。本指南不需要这些场景，但它们对于以后进一步学习很有用。

Activating Vuforia in Unity

要在 Unity 项目中激活 Vuforia，请通过 Edit > Project Settings > Player 访问 Player Settings，然后选择要构建到的目标移动设备的相应选项卡。在 XR Settings 下，勾选 Vuforia Augmented Reality Support 复选框。

场景中现在包含两个游戏对象：主摄像机和方向光。需要向场景添加新的 AR 摄像机才能启用 AR 功能，并需要从场景中删除当前的__主摄像机__游戏对象。

要删除摄像机游戏对象，请在 Hierarchy 窗口__中选择该游戏对象，然后按键盘上的 Delete 键，或者右键单击该游戏对象并选择 Delete__。

Adding a Vuforia AR Camera and other GameObjects

要将 AR 摄像机添加到场景，请选择 GameObject > Vuforia > AR Camera。

如果这是第一个添加到场景中的 Vuforia 游戏对象，则 Unity 还会提示导入 Vuforia 资源。选择 __Import__，Unity 便会将所有必要的 Vuforia 文件导入到项目中。

Project 窗口__会显示 4 个新文件夹，其中一个名为 Vuforia__。此文件夹中的代码和资源提供了主要的 AR 和 MR 功能。其他文件夹提供示例场景、资源、工具和插件，便于为各种设备开发 AR 和 MR 应用程序。

在项目中创建一个新文件夹。为此，请导航到 Project 窗口，单击 Create 按钮，然后选择 Folder。将此新文件夹命名为 _Scenes_，并在此文件夹中保存新场景。

此过程还会在 Scene 层级视图中添加新的 ARCamera 游戏对象。

Creating a Vuforia license key

设置过程的最后一步是从 Vuforia 开发者门户的 License Manager 部分中创建许可证密钥。需要将此信息输入到 Unity 的 Vuforia 配置设置中，以便使用 Unity 构建并测试应用程序。

访问 Vuforia 开发者门户并登录（或创建新帐户）。导航到 Develop 部分的 License Manager__，然后单击 Get Development Key__ 按钮以打开 Add License Key 页面。

在 Add License Key 页面上，输入应用程序的名称。接受条款和条件，然后单击 Confirm 按钮以生成新的许可证密钥。

在下一页上，同意 Vuforia 开发者条件（勾选复选框），然后单击 Confirm 按钮。随即将返回 License Manager 页面，并可在列表中看到新创建的许可证及其状态为 Active。单击应用程序的名称即可查看许可证详细信息。这样就能检索开发许可证密钥。

将许可证密钥复制到剪贴板并导航回 Unity 项目。

从 Hierarchy 窗口__中选择 ARCamera__ 游戏对象，然后在 Inspector 窗口中导航到 Vuforia Behaviour(Script) 组件并单击 Open Vuforia configuration 按钮。

Inspector 窗口__将显示一组 Vuforia Configuration__ 选项。将 Vuforia 开发密钥粘贴到 Vuforia 部分下的 App License Key 文本框中，然后单击 Add License 按钮。

Testing your set-up

要在 Unity Editor 中测试 Vuforia 应用程序，必须将网络摄像头连接到 PC 或笔记本电脑。为了确保在 Unity 项目中已正确安装 Vuforia，最后一步是按 Play 按钮来测试场景。如果 Vuforia 设置正确，则 Editor Game 视图中会显示来自网络摄像头的视频。

现在已准备好可以设置图像目标并为项目添加 AR 功能。

Setting up Image Targets

本部分将介绍如何设置简单的图像目标并使其响应基本跟踪事件。

为了让应用程序识别图像并将其用作触发游戏、显示图形或信息的目标，需要创建一个__目标数据库__。可按本部分中的步骤所述，直接从 Vuforia 开发者门户 Target Manager 页面中创建目标数据库。

登录 Vuforia 开发者帐户。然后，导航到 Target Manager 页面，并单击 Add Database 按钮。

在 Create Database 页面上，输入数据库的名称，从 Type 选项中选择 Device__，然后单击 Create__ 按钮。

此时会将新的目标数据库添加到 Target Manager 列表。现在单击列表中的__数据库名称__以打开 Device Database 列表。

此时将显示数据库的__目标列表__页面，在此处可添加新的目标以及使用特定格式下载数据库以用于多种平台。单击 Add Target 按钮可打开 Add Target 弹出窗口。

Add Target 窗口提供了多个选项来指定要添加的目标的详细信息。可添加四种不同类型的目标：Single Image、Cuboid/Box、Cylinder 和 3D Object。在 Type 下，选择 __Single Image__，然后浏览硬盘驱动器以找到要用作图像目标的图像。

此示例使用扑克牌来演示 Unity 中的图像目标识别功能。

可使用任何图像，但请确保图像具有足够的细节可评定为 5 星目标，使摄像机可以轻松跟踪该目标。

Width 值是一个缩放值，需要将其设置为希望图像在 Unity 场景中显示的大小（采用真实世界单位）。Unity 会根据目标图像的大小衡量场景中的所有对象。对于此示例，扑克牌的宽度为 5.5cm，因此要使用 5.5cm 作为 Width 值。如果需要更大尺寸的目标，则增加此 Width。

输入目标图像的名称，然后单击 Add 按钮将图像目标上传到数据库。

该图像会显示在 Targets 列表中，其中 Rating 值由星号表示。如果 Rating 小于 5 星，摄像机可能难以跟踪该目标。要了解有关图像目标评级的影响因素的更多信息，请参阅有关优化目标检测和跟踪稳定性 (Optimizing target detection and tracking stability) 的 Vuforia 文档。

对图像的评级满意后，选中__图像目标__名称左侧的复选框，然后单击 Download Database 按钮。

在 Download Database 窗口上的 Select a development platform 下面，选中 Unity Editor__，然后单击 Download__ 按钮。此时将下载目标数据库的 Unity 包，并可将其保存在硬盘驱动器上。

可切换回 Unity 项目，将 Unity 包导入，从而在应用程序中使用。

Importing and activating the Target Database in Unity

在 Unity Editor 中，导航到 Asset > Import Package > Custom Package 并找到硬盘驱动器上的资源包。在 Import Unity Package 窗口中，单击 Import 按钮。

从 Hierarchy 窗口__中选择 ARCamera__，然后在 Inspector 窗口__中导航到 Vuforia Behaviour (Script)__ 组件并单击 Open Vuforia configuration 按钮。

在 Vuforia Configuration 窗口的 Datasets 下，选中 Load [DatabaseName] Database 复选框和 Activate 复选框。随后将激活图像目标数据库以便用于 Unity。

Adding Image Targets to your Scene

要将图像目标添加到场景，请选择 GameObject > Vuforia > Image。

当图像目标游戏对象位于场景中后，选择该游戏对象并在 Inspector 窗口中查看其组件。

在 Image Target Behaviour 组件中，单击 Database 下拉列表，然后选择目标数据库。在 Image Target 下拉列表中，选择数据库中的图像目标的名称。

注意：无需单击 Add Target 按钮，因为这会进入 Vuforia 网站，其中将提供有关向应用程序添加目标的信息。

最后一步是在 Vuforia 识别到图像目标时让 3D 游戏对象显示。

Displaying 3D Models on top of tracked images

This section describes how to display a GameObject when the camera recognizes and tracks an on-screen Image Target.

使游戏对象成为图像目标 (Image Target) 游戏对象的子代。此子代游戏对象必须同时包含 MeshRenderer 和 MeshFilter 组件。

添加立方体图元作为图像目标游戏对象的子代。为此，请右键单击该游戏对象，然后从弹出菜单中选择 3D Object > Cube。

现在缩放立方体游戏对象，将其移近图像目标游戏对象，使其看起来像是置放在目标图像上。使用 Scene 视图__可判断游戏对象的位置。如果使用与本指南中的扑克牌相同的 Width__，则将立方体游戏对象的 Transform 组件的 X、Y 和 Z Scale 值更改为 0.5，并将 Transform Position Y 值更改为 0.25，使立方体在图像目标游戏对象上保持良好的置放状态。

场景应如下所示：

单击 Unity Editor 中的 Play 按钮可测试 AR 功能。将图像放在网络摄像头前面时，在 Game 视图中立方体会显示在图像之上。

ARCamera 上的 Camera 组件的默认 Far Clipping Planes 设置为 2000。对于需要在较远距离进行图像跟踪的游戏或应用程序（例如需要 AR 或 MR 眼镜的游戏或应用程序），必须在 Unity 中调整 Camera 组件的 __Far Clipping Planes__，并增加目标的大小以确保设备摄像头能够轻松跟踪目标。

现在已经成功制作了一个使用图像目标的简单应用程序，并在摄像机可以跟踪目标时显示一个基本 3D 形状。

Platform configuration settings

This section provides a step-by-step guide for configuring your Unity Project to build Vuforia Augmented/Mixed Reality applications.

Here is a list of important XR settings used in Vuforia Unity integration. To access these, open the Player Settings (Edit > Project Settings > Player, then select the tab for the device you are building to):

• __Vuforia Augmented Reality support__：在应用程序中启用 Vuforia 增强现实支持

• __Virtual Reality SDKs__：允许将 Vuforia 功能集成到 VR 应用程序中。选中 Virtual Reality Supported 复选框时显示此菜单。

Vuforia 支持以下 XR SDK：

• Google Cardboard - Google VR SDK

• Google Daydream - Google VR SDK

• Microsoft HoloLens - Windows 10 SDK

• Vuforia SDK

Vuforia VR SDK__（位于 Virtual Reality SDKs__ 列表中）是一种没有外部依赖项的独立 VR 配置。该 SDK 提供立体渲染和失真校正、头部和手部跟踪（具有适用于 Tango 的位置跟踪）以及查看器配置文件支持（用于定义各种 VR 头盔的参数）。

Stereo rendering method

立体渲染方法仅在使用 Vuforia 虚拟现实 SDK 时才有意义。Android、iOS 和 Windows Mixed Reality 设备支持多通道实例化、单通道实例化和非实例化。

将 Vuforia 增强现实与另一个虚拟现实 SDK 结合使用时，立体渲染支持由所使用的虚拟现实 SDK 决定。

Supported graphics APIs

建议：__在 Unity 的 Player Settings（__Edit > Project Settings > Player__，然后选择目标构建设备的相应选项卡）中，打开 Other Settings__，并启用 Use Auto Graphics API。

Android	iOS	Windows
OpenGL ES 2.0 OpenGL ES 3.x	OpenGL ES 2.0 OpenGL ES 3.x Metal (iOS 8+)	Windows 10 上的 DirectX 11

Supported features

Vuforia 提供了许多功能来协助开发 AR/MR 应用程序。

下表列出了这些功能以及支持它们的操作系统和设备类型。

功能	描述	操作系统	手机设备	眼镜
图像目标	跟踪平面图像	Android、iOS、UPW	是	是
多个目标	跟踪图像的几何排列	Android、iOS、UPW	是	是
圆柱体目标	跟踪包裹在圆柱和圆锥上的图像	Android、iOS、UPW	是	是
用户定义的目标	跟踪用户在运行时捕获的图像	Android、iOS、UPW	是	不推荐
云端识别	基于云端的图像目标	Android、iOS、UPW	是	是
设备跟踪	3 DoF 和 6 DoF 位置跟踪*	Android、iOS、UPW	是（仅限于 6 DoF）	是（仅限于 6 DoF）
VuMark	可定制、可编码的 AR 标记	Android、iOS、UPW	是	是
对象识别	跟踪扫描中的 3D 对象	Android、iOS、UPW	是	是
模型目标**	跟踪 3D 模型中的 3D 对象	Android、iOS、UPW	是	是
智能地形	跟踪用户环境中的表面和几何体	Android、iOS、UPW	是	受限
AR + VR	VR 应用程序的 AR 功能支持	Android、iOS、UPW	是	是

* Tango 和 HoloLens 设备可使用 6 种自由度跟踪

** 模型目标通过 Vuforia 早期访问计划 (Vuforia Early Access Program) 提供并在 Unity 2017.3 中公开

Helpful tips

Here are a few useful tips that will reduce your learning curve when working with Vuforia in Unity.

Image Target tracking

当摄像机在 Editor 内的播放模式下跟踪图像目标时，Unity 会禁用图像目标游戏对象的子游戏对象包含的所有组件。这不包括图像目标游戏对象的子游戏对象上附加的任何脚本组件。即使图像目标不在视图中，所有脚本都会继续运行。因此可能需要您进行条件检查，从而防止脚本的 Update() 方法中的代码在您不需要时持续运行。或者，也可以在代码中禁用脚本组件，并在需要时再次启用该组件。

Running code during Image Target state change events

在特定图像目标跟踪事件状态（例如目标是否可见）期间运行代码的一种有用脚本是附加到每个图像目标游戏对象的 Default Trackable Event Handler (Script) 组件。

以下是两个最有用的方法：

private void OnTrackingFound()

当 Vuforia 在__摄像机视图__中找到目标图像游戏对象时，Unity 会从该游戏对象的特定实例的 Default Trackable Event Handler (Script) 组件调用此方法。此方法对于在最开始跟踪对象时运行特定代码非常有用（例如将游戏对象添加到激活状态游戏对象的列表中）。

private void OnTrackingLost()

当 Vuforia 在摄像机视图中丢失对图像目标的跟踪时，Unity 会从该游戏对象的特定实例的 Default Trackable Event Handler (Script) 组件调用此方法。此方法可用于在图像目标从视图中消失时立即运行特定代码（例如在 GameManager 中从用于跟踪应用程序中所有激活状态游戏对象的列表中删除游戏对象）。

Extended Tracking

对于仅需要进行初始设置和注册而不需要持续跟踪图像的图像目标，请导航到目标的 Image Target Behaviour (Script) 组件并启用 Enable Extended Tracking 选项。

借助 Enable Extended Tracking 功能，即使图像目标不在摄像机的视野中（在摄像机至少识别一次图像目标之后），图像目标的位置和方向仍然存在；该功能还使用环境功能来提高跟踪性能。有关用于 Vuforia 的扩展跟踪功能的更多详细信息，请参阅关于扩展跟踪的 Vuforia 文档。

Publishing your AR/MR application

要将 Vuforia AR 或 MR 应用程序从 Unity 导出到移动平台，请使用与正常发布到 Android 或 iOS 设备时相同的步骤。请参阅有关这些平台的发布操作的文档：

• 发布到 Android
• 发布到 iOS

无需特殊设置。

实用链接

以下是一些有用的资源和教程，可帮助您了解有关 Vuforia 可用的许多功能的更多信息。

• Unity Vuforia 论坛

• Vuforia 开发者论坛

• Vuforia 文档：Vuforia 开发者库

• Vuforia 文档：混合现实 AR/VR 体验的最佳实践 (Best practices for mixed reality AR/VR experiences)

Troubleshooting guides

本部分提供的链接可用于访问使用 Vuforia SDK 进行开发时可能遇到的最常见问题的有用故障排除信息。

• [Vuforia 开发者门户：常见问题解答](https://developer.vuforia.com/forum/faq/faq