Augmented Reality: Vuforia and Unity

Augmented Reality (AR) is a visualization of reality enhanced by virtual objects. The virtual objects are add-ons to reality. They enrich reality by adding extra, unreal content. You probably have heard or seen Pokemon Go game. It is a mobile game based on AR technology. However Augmented Reality is not useful only for games, but anywhere else the virtual, additional objects are needed.

This article shows how to create AR mobile app on Android with the use of Unity environment and Vuforia Engine. Mainly Unity Editor is used for implementing games, but also it gives a possibility to create AR apps. It integrates with Vuforia Engine – a platform used for recognizing various types of real objects.

Environment set up

First of all, you need to create two accounts: Unity ID and Vuforia.

Secondly, you need three editors:

  • IDE for writing and debugging C# code. I recommend Visual Studio Community 2017 because you can install Tools for Unity plugin during VS installation.
  • Obviously, Unity Editor. During installation check Vuforia Augmented Reality component.
  • Android Studio. It is useful for managing Android SDK and writing additional plugins. Unity engine has not every native feature, so sometimes you will need to write your own plugin in a native language.

Create a project

Let’s run Unity. You can work online and you have to sign in with Unity ID or offline either. Then create a project and fill in name, location and choose 3D template.

Settings set up

After loading the project, go to Edit-> Project Settings -> Player Settings and XR Settings section. Check Vuforia Augmented Reality. Then accept Vuforia’s Software License and look at Vuforia Configuration, which you can find on Window section. It needs development key, which you can get from Vuforia Developer Portal account. Go to License Manage tab and click Get Development Key. Then click on a license key record and copy license key. Next, paste it to App License Key in Vuforia Configuration.

license manager vuforia augmented reality

Go to File -> Build Settings. There switch to Android Platform and click a button which downloads Android Support for Editor. Install it and go to Player Settings for Android – set up a name of company and name of the project. Then set Target API in Player Settings, which should be a value of API your phone is using (or whatever device you are going to use to run the app). For example, I have installed API 26, because my phone has Android 8.0. To install Android API, go to Android Studio -> Configure -> SDK Manager -> Android SDK.

android studio augmented reality

ADB driver is the last thing to install. It is necessary for debugging android app via USB with C# IDE and displaying logs on cmd what is really useful. After installation, you need to add the driver path to an environment variable PATH.

Lastly, go to Unity Editor -> Edit -> Preferences -> External Tools and set Android SDK path. On my device it is C:/Users/<my-user>/AppData/Local/Android/Sdk

Let’s have a look at your project settings which should look like below ones.

unity settings augmented reality

Implement a project

The project is an example of recognizing and tracking image, which is called by Vuforia Image Target. We are going to create Image Target and display augmented text on it. Below you can see an output of the app.

augmented reality vuforia app

Go to my GitHub, download the project. Then remove scenes from Assets folder in your project and copy-paste every file and folder from the project of mine. Check whether your project in Unity Editor looks like one on a screen.

vuforia features augmented reality

Let me explain you some the most important parts of the project.

  • VuforiaFeatures scene contains: ARCamera – camera provided by Vuforia (you can add it by right click on the scene and going to GameObject -> Vuforia -> AR Camera); TargetsContainer – Canvas, which is a parent for dynamically loaded Image Target. Without Canvas, the text would not display.
  • Assets folder contains: Resources -> Prefabs, where is Text prefab, which is the text displayed on Image Target; Resources -> Scripts, where is C# code; Scenes where are scenes, of course.

Double click on C# file will open C# IDE. Have a look at VuforiaFeaturesController class.

In Unity Editor you will see all fields with [SerializeField] attribute. This is a way how Unity UI communicates with C# backend. You can add whichever class, which inherits from MonoBehaviour class, to whichever GameObject in Unity Editor. To connect Unity GameObject with backend, drag and drop the GameObject to a field, which is in a script component. You can add a script component to GameObject by clicking on the GameObject and clicking Add Component button.

targets container

How Vuforia deal with Augmented Reality?

This is a clue of this article. Read carefully, you need to know about several matters:

  • API needs a database that contains desirable targets. The database can contain only one type of target. In our case, it is an Image Target. Vuforia Developer Portal, where you already have an account, generates the database. It is just an XML file. I will explain how to create it later,
  • API is able to read a dataset after passing a database path and to create a list of loaded targets. Go to VuforiaService.LoadDataSet method and see how it works,
  • The dataset must be active and tracker must be started. Targets cannot be recognized without it. See VuforiaService.ActivateDataSet,
  • The two above methods must be called after Vuforia is initialized. It initializes itself without necessary to write code. See VuforiaFeaturesController.Start,
  • API doesn’t show or hide AR content by itself. It recognizes the target and sends event which must be handled by a handler, of course. The handler is a component which needs to be added to a target (see constructor of ExtendedTrackableBehaviour). The handler takes care of augmented objects. It enables the target’s children components when the target is found and it disables the children when the target is lost. Vuforia provides handler called DefaultTrackableEventHandler. You can find it on the project on VuforiaScripts -> Assets -> Vuforia -> Scripts folder,
  • API sends the event only when the target’s game object is active. See
    VuforiaFeaturesController.Start.

Time to explain how to generate the database. Login to Vuforia Developer Portal. Then go to Target Manager tab and click on Add Database. Name it ImageTargetsDatabase and check Device type. Next, click on the database’s link and click on Add Target. Your image target should have enough details to gain several stars rating. It is relevant to recognizing a target.

Build and run

Before you click on Play button in Unity Editor, go to C:\Users\<my-user>\AppData\LocalLow\<my-company-in-settings>\<my-project-name> path and create folders Vuforia\Database. Let me clarify how to retrieve the path in the code. See Paths class. There is a property which returns a path of the image target database. Application.persistentDataPath is this
C:\Users\<my-user>\AppData\LocalLow\<my-company-in-settings>\<my-project-name> path on Windows. On Android, installation of an app will create the path. On my device it is as follow: Internal storage -> Android -> data -> com.devsoutput.VuforiaFeatures -> files. Also there you need to create folders Vuforia\Database and paste XML database and .dat file.

Now it is time to build. Go to File -> Build Settings -> Build And Run.

Conclusion

Basic usage of Vuforia is fast to implement. All you need to remember is to load an XML database and put .dat file in the same folder as the database, activate dataset, activate a target’s game object, add an event handler to a target. Then Vuforia API does the whole job to recognize a target.

Configuration of Unity, Vuforia and Android Studio is quite a time-consuming process, but then an implementation is rapid, so it is worth.

That is it for this article. Stay tuned for a next article of the series 🙂

Share on

Leave a Reply

avatar
  Subscribe  
Notify of