Authored by Tom Southworth @Draw & Code Dec 20, 2017 for general use. Reviewed by Unity Technologies and Vuforia.
Unity 2017.3 and Vuforia 7 Integration
In recent months, Vuforia and Unity have combined their software, meaning that you can now install Vuforia as part of the Unity installation process just like any other module. During the Unity 2017.3 installation, in the components section, you can now select Vuforia as a component that you wish to install alongside the Unity Editor, just like you can do with iOS and Android support.
Previously, if you wanted to use Vuforia with Unity, you would have to download a Unity package of the latest version of Vuforia from Vuforia’s website and then import said package into Unity. This would create a folder for Vuforia in your project, where you could access all the necessary scripts and prefabs.
With the new integrated version, a few project setup things have changed, but not so many that long-time users of Vuforia will be baffled by them. The first change to notice is that you need to enable Vuforia in the Player Settings section of the Unity Editor under the ‘XR Settings’ label. This enables Vuforia to be used throughout your project.
There is a behavior with this that a few users have encountered, and that is the fact that once you have enabled Vuforia in your project, it is active in every scene by default. What does this mean? Previously, in order to have augmented reality capabilities enabled in a particular scene in Unity, you had to use the ARCamera prefab provided to you by Vuforia. If you had an ordinary, non-AR camera in your scene, it would not enable augmented reality capabilities in your scene by default. However, in the integrated version of Vuforia, if you have a non-AR camera in your scene and have Vuforia enabled in the ‘XR Settings’, then Vuforia will automatically add augmented reality capabilities to the non-AR camera in question, essentially turning it into an ARCamera. This can interfere with applications that were set up using older versions of Vuforia and applications where non-AR and AR cameras are needed.
The other change that is worth mentioning in regards to project setup is how you create your prefabs. Instead of having to go to the Vuforia folder in your project, you can now go to the ‘GameObject’ menu at the top of the Unity Editor, then to Vuforia and create all of your GameObjects from there. When you create a Vuforia GameObject for the first time, Vuforia will ask you to import a few things in order for the prefabs to be created and once you’ve done that then you’re ready to go.
When using Vuforia and creating augmented reality applications in general, it is important to think about what your app will be used for and how it be used. Will your application be used in a wide open public space like a street or somewhere smaller and more confined like an art gallery? Below are some questions for your consideration.
Purpose: What will the augmentation be used for?
Location: Where will the augmentation take place? Will the objects be moved?
Target Audience: Who is your target audience? Do they have any particular needs?
Lighting Conditions: What kind of lighting will be used in the area where the augmentation will be shown?
When working with AR targets a naming convention is usually quite useful. In general, the full name of a project or an abbreviation of it followed by an underscore followed by the name of the target is the convention that we use. Also, numbering is important for differentiating targets from each other when using such a naming convention in case two targets have the same name. See below for examples.
Full Target Name: Unity3D_MarkerTom
Full Target Name Numbered: Unity3D_MarkerTom_001
Abbreviated Target Name: U3D_MarkerTom_001
The main reason for having a naming convention is to help with the order of things. Having targets called many different names makes it harder to find what you are looking for when browsing through Vuforia’s target databases. If someone else needs to work on a project and browse through your targets, having a naming convention makes it easier for them to find what they are looking for also.
It can also be useful to have a naming convention if you want to unload and load targets at runtime based on user input. Whilst in Unity you can assign trackables/targets as public variables in the Inspector element of the Unity Editor, sometimes, for some reason, you might not want to or may not be able to. In cases like these, you can load and unload targets by name in code.
Downloading a Vuforia Database
Vuforia lets a user download a database of targets as a Unity Package which can be quite useful, since this allows both the database xml and dat files to be imported into Unity directly, along with all of the related imagery needed to display the targets in the database in the Unity Editor’s Scene view. Since the actual package itself is not needed in the Unity project, only the contents of it, the package file should remain outside of the Unity project. The “Add Database” button is a handy button in the Vuforia Configuration Window that takes a user straight to the Vuforia Target Manager page where a database can be created.
Importing a Vuforia Database
When importing a Vuforia database into your Unity project there are one or two key things that you should be aware of. Firstly is that, like all other Unity package imports, if a file exists both in your Unity project and in the package being imported then the file in your project will be overwritten by the file in the package unless you uncheck the box next to it in the import dialogue. If you are not careful, you can undo a lot of MultiTarget xml setup in just a moment and that can be a problem.
Here’s a scenario. You have a Vuforia database in your project, with then carefully set up MultiTargets, each with a unique position and rotation. You have updated said database online on Vuforia’s developer website with some new targets and now want to import it into your project so that your project is up to date. All databases that are downloaded as Unity packages from Vuforia’s site do not contain any of your MultiTarget xml setup. See below for an example of some database XML data.
If you import the package without unchecking the xml file of the database in Unity’s import dialogue then your MultiTarget setup will get overwritten. If you do uncheck it then you will have to manually enter all of the names and statistics of the new targets from the up to date xml file into the xml file in your project.
There are solutions to this problem. One solution is to do the following. Before importing the newer version of your Vuforia database into your project, copy the older database’s xml file from your Unity project and back it up outside of the project. Then import the newer version of the Vuforia database into your project, including the xml. You can then go back to your old xml file outside of the project, copy the MultiTarget setup from it and paste it into the new xml file inside of your Unity project.
This will result in the database xml file in your project having up to date marker details and your old MultiTarget setup information as shown above. The problem with this solution is that you may have to re-assign any MultiTargets you have in Unity’s scene Hierarchy due to the fact that importing the up to date database, which has no MultiTarget information, can cut the link between the MultiTargets in your scene hierarchy and the database xml until you copy the old MultiTarget information back into the xml.
The easier solution is to import the up to date database into your Unity project without the xml file checked in the import dialogue as shown below.
Then, go back to the Vuforia website and download the database again, this time download it not for Unity but for the other development platform ‘Android Studio, Xcode or Visual Studio’. The download for this will be a zip file which contains the database’s dat and xml files. The xml file contained in this zip is the same as the one in the Unity package, so you can copy all of the new target information from it and paste it into the xml file that is in your Unity project.
That way, you will have imported the new dat file and images related to the database directly into your Unity project and manually copied across the new target information into your old xml file. Both methods are a little involved, but it saves having to re-write the multi-target setup in the xml file, which could take a significant amount of time based on how many MultiTargets you have.
There are many uses for augmented reality targets in an application. Usually, a user simply wants to display some form of content on top or around of an AR target. Sometimes though, the need will arise for multiple AR targets to interact with each other. These can be multiple ImageTargets, multiple MultiTargets or a mixture of both. If you are going to be using multiple targets together to achieve some kind of game mechanic, for example, if a GameObject attached to one AR target gets close to another GameObject parented to another AR target , you need to keep in mind that when setting up targets inside of Unity you need to assign the size of the target correctly. For MultiTargets the assignation of size is done within the xml that defines them, this is covered below.
For an ImageTarget though you will need to change the size of the target in the ‘ImageTargetBehaviour’ component of the ImageTarget in question. This can be done by changing the values of the ‘Width’ and ‘Height’ fields. When you change one of these fields, the other changes with it to make sure that the target’s aspect ratio stays correct. If your target is portrait, put the largest measurement in the height field or if the targetis landscape then put the largest measurement in the width field. If you do not ensure that targetsare the correct size, then sometimes objects that are parented to them will not properly collide or interact with other each other in 3D space because they will be further apart than they need to be when the targetscome together. The best way to see this happening is to incorrectly size one targetand correctly size another, place them next to each and see how they look in Unity’s Scene view compared to how they look in Unity’s Game view. See the link below for more details:
MultiTargets are a type of target that come in very handy when you have a 3D real world product that you want to augment. Let’s take a cube for example. You could apply one individual ImageTarget to each side of a cube and these individual targetswould track fine, as long as they were designed in such as way that meant they had a variety of different tracking features. There might be a reason why you want to use individual targets in this way, perhaps one target on one side of the cube needs to be turned off at a certain point in time and another activated. However, by using a MultiTarget, you can combine these six individual targets into one and have a much more stable target that makes use of all of the individual targets’ tracking features. Or, to put it another way, the cube can be tracked as one augmented reality target instead of six individual ones.
The setup of a MultiTarget takes place within a Vuforia database’s xml file inside of the Unity project. The xml file can be opened with Unity’s default code editor Monodevelop or any other text editing software. It is much easier to edit the xml code in a piece software that recognises xml code though, as it becomes colour coded etc. The xml file contains a set of tracking brackets, that look like this: <Tracking> </Tracking>.
Inside of those brackets are all of the markers/ImageTargets inside of the database in question. An example of an ImageTarget can be seen below:
In order for a MultiTarget to be created there needs to be at least one ImageTarget present.
Of course, using just one ImageTarget in a MultiTarget would be a bit pointless, as the whole purpose of using MultiTargets is to stitch multiple ImageTargets into one big MultiTarget. In order to create a new MultiTarget, you must create a new set of brackets: <MultiTarget></MultiTarget>. Inside of the first bracket a name for this new MultiTarget must be given and between the two brackets each Part of the MultiTarget needs to be defined. Below you can see an example of a full MultiTarget that is enclosed within the tracking brackets as part of a full Vuforia database xml.
Note how the MultiTarget brackets are inside of the Tracking brackets and set below the ImageTargets. This is important. If you place the MultiTarget brackets outside of the Tracking brackets then Vuforia will not create a MultiTarget for you and it won’t appear as an option on any MultiTarget GameObject. Each Part of a MultiTarget has a name, translation and rotation. The first two of these are easy enough to assign. The name is the name of the ImageTarget you want to add to the MultiTarget. The translation is position of the ImageTarget in 3D space. The rotation however can be tricky to set. It uses Quaternions, which are not ideal when trying to set something up in 3D space in the Unity Editor, as people generally use Euler Angles when rotating a GameObject using the Transform Component in Unity’s Inspector view. This results in difficulty when trying to get the rotation of the entire MultiTarget correct. It is sometimes easier to lay the ImageTargets out in the positions/translations they need to be in in the xml, change their rotation values in the xml for them so they all fit together then rotate the MultiTarget as a whole in Unity’s scene view.
Using a MultiTarget
You can create a MultiTarget in two different ways, based upon which version of Vuforia you are using. See below for the different methods.
Vuforia 6.5 and upwards: To create a MultiTarget GameObject, first enable Vuforia by going to the Player Settings, locating the ‘XR Settings’ tab and making sure that the ‘Vuforia Augmented Reality Supported’ checkbox is ticked. Then, go the the GameObject menu at the top of the UnityEditor, locate the Vuforia menu and click on ‘Multi Image’.
Older Versions: To create a MultiTarget prefab in older versions of Vuforia, you must drag the MultiTarget prefab from the Vuforia/Prefabs folder in Unity’s Project view into the Hierarchy of your scene.
The process here on out is the same for both versions. You must set the 'Database’ and ‘MultiTarget’ fields of the ‘MultiTargetBehaviour’ component on your MultiTarget GameObject. You must ensure that these are loaded and activated in Vuforia’s configuration panel in Unity, which can be reached by clicking on the ARCamera in your scene and clicking on the ‘Open Vuforia Configuration’ button. Then you can drag and drop your 2D/3D content onto the MultiTarget in your Hierarchy, position it accordingly, and see the content appear when you press Unity’s play button and show the physical MultiTarget to the webcam that you are using.
When designing a MultiTarget that is of a 3D shape in the real world, you have to be careful of how you want to display your content in and around that MultiTarget. Let’s say that you have a MultiTarget that is the shape of a box, and you also have a 3D model which is the same shape of that box. However, the 3D model has an opening in it and the MultiTarget does not. This means that when you make your 3D model a child of the MultiTarget, line in up over the MultiTarget and press play, you will not see the opening of your 3D model because the physical MultiTarget covers the hole up, since the hole is not incorporated into the design of the MultiTarget that way. This is a masking issue. The MultiTarget ends up hiding a feature of a 3D model which is parented to it and is contained within its boundaries. This can be solved by expanding the MultiTarget in your Hierarchy, expanding the ‘ChildTargets’ GameObject, selecting all of the GameObjects which are children of the ‘ChildTargets’ GameObject and then removing their ‘MeshRenderer’ components as well as their ‘MaskOutBehaviour’ components. That way the physical MultiTarget will no longer hide an ‘Inner Feature’ of the 3D model.
Older Versions of Vuforia
As a developer, there are times when you may need to work on an older augmented reality project that uses Vuforia where it is not possible to update either your version of Unity or Vuforia. If this is the case and you are using a version of Unity that is lower than 2017.2 or a version of Vuforia that is lower than 6.5, then take a look at the two issues below, as there is a chance that they will show up in your project.
Target Texture Issue
With Vuforia version 6.5 which is built into Unity 2017.2 this appears to no longer be an issue, however, in previous versions of Vuforia that are not built into Unity, there is also an issue with texture importing regarding targets. So, if you have the new version of Vuforia that comes as part of Unity 2017.2, then you don’t need to worry about the below issue. If you have an older version of Vuforia, specifically 5.5 upwards up until 6.5, do read the below.
In previous versions of Unity the texture setup was slightly different. When you click on a texture in Unity’s Project view a setup window opens up in the Inspector view. This allows a user to configure the image to be of a certain type and have certain properties. In previous versions of Unity, the default Texture Type for any texture imported by Vuforia was that of ‘Texture’. However, in Unity versions 6.0 and above the default ‘Texture Shape’ is set to ‘Cube’. This results in any texture imported by Vuforia being invisible when applied to a target prefab in Unity’s scene view. This is not ideal. In order to fix this issue simply set up the texture for the target in question to have ‘2D’ for its Texture Shape. If you have many targets that need to be changed an editor script can always be created that can find and change all textures that have this issue within multiple folders. See below for the correct texture setup.
Like the Marker Texture Issue mentioned above, this issue no longer is a problem if you are using the Vuforia 6.5 in Unity 2017.2. The issue seems to have been resolved. If you are using an older, non integrated version of Vuforia, then read on. If you have a scene open with a Vuforia ARCamera tracking targets and want to load another scene, this can present an issue where the scene will crash when trying to load to another scene. This may not happen if you are additively loading scenes, as you are not attempting to leave the current scene you are in to go to another one, you are merely adding more scenes to the current one that you are in.
As a standard practice, it is a good idea to stop Vuforia’s ‘ObjectTracker’ before loading any new scene in Unity, which can prevent this issue from happening. You can do this in your code by creating an IEnumerator and having it carry out these lines before loading a scene like below:
public class LoaderScript : MonoBehaviour
// Coroutine to stop Vuforia's Objecttracker.
IEnumerator StopObjectTrackerAndLoadScene (string sceneName)
// Store a reference to the ObjectTracker currently running.
ObjectTracker objectTracker = TrackerManager.Instance.GetTracker <ObjectTracker> ();
// If there is an Active ObjectTracker running in the scene then Stop it.
if (objectTracker != null)
// Wait for the ObjectTracker to Stop.
Debug.Log ("Waiting for tracker to stop \'DisconnectAndLoadScene\'..");
yield return null;
// After the ObjectTracker has stopped, a new scene can be loaded.
Debug.LogError("Loading scene failed: " + sceneName + " not found.");
Lessons learned in AR Design
If you are interested in breaking into AR gaming, you should also check out the best practices and tips for AR design our cofounder John Keefe shared with the community in the Unity blog.
Unity Blog: Breaking into AR with Vuforia: a Unity creator shares practical advice
We also recommend you download Vuforia’s Unity Scenes available for free in the Unity Asset Store which should give you all the assets you need to get started experimenting with AR mobile development.
Asset Store: Download Vuforia Unity Sample Scenes for Free