This guide will take you through the process of importing and working with Area Targets in Unity. By importing the Unity package that is created from the Area Target Generator (ATG) or using the Vuforia Area Target Creator app (VATC) you will be able to design and develop environment-based AR experiences for Unity’s supported platforms.
Get started with Area Targets using the Vuforia Core Samples that includes an Area Target scene. Or, create your own Area Target following the guides on the Best Practices for Preparing and Scanning an Environment and How to create an Area Target and import it into Unity for authoring.
NOTE: Area Targets are only supported on ARKit or ARCore enabled devices and selected eyewear devices. VISLAM enabled devices are not supported. See Supported Versions.
NOTE: A recent change in Vuforia Engine 10.3 about the Location Prior for Area Targets require that developers using large Area Targets to enable the requiresExternalPositions in the Area Target Behaviour’s component.
Import your Area Target in an Empty Unity Project
If you have your own Area Target ready as a *.unitypackage you can begin with the following steps.
- Start by creating and opening a new project in Unity. For supported Unity Editor versions, see Supported Versions.
- Set up your project with Vuforia Engine by adding the Vuforia Engine Unity package. See here on how to do this.
- Remove the default Main Camera from the scene. Replace it with an ARCamera by going to the GameObject menu -> Vuforia Engine -> AR Camera.
- Obtain a License Key for your project. Please refer to the Vuforia License Manager guide on how to obtain a license key.
- Place your license key in the associated field in Vuforia Configuration (CmD+Shift+V for macOS, Ctrl+Shift+V for Windows)
- If it isn’t already, enable the Track Device Pose at the same time. Enabling Device Tracking is required for tracking Area Targets.
Scene set-up with Area Targets
- Create an AreaTarget GameObject from GameObject->Vuforia Engine->Area Target->Area Target.
- Import the Area Target database .unitypackage that was generated from the Area Target Generator by selecting Assets -> Import Package -> Custom Package (or double click the .unitypackage).
- Select the imported Database and Area Target from the AreaTarget GameObject via the dropdown menu.
Configure the Area Target
The Area Target database contains additional assets of the scanned area including textures, materials, and a prefab model or mesh. After importing the package, from the Project window, locate these files in the folder Assets/Editor/Vuforia/<dataset name> folder.
The preview mesh of a scanned area is automatically added to the AreaTarget GameObject whilst a prefab model from Matterport™ generated Area Targets is available and can be placed in the scene if you wish to modify certain captured elements of the area.
NOTE: Changing the size of the AreaTarget GameObject is not supported, it is always in ‘meters’. It guarantees that your scanned environment retains its original scale throughout the entire development workflow. If you need to use a different scene scale in your project, please review the Virtual Scene Scale Factor in Unity article.
Large Area Targets require an external location prior to locate the user within the space of the Area Target. Trying to use a large Area Target without the Requires External Position enabled will throw an error. All Area Targets can be set with a Requires External Position in their Area Target Behaviour component in the Inspector.
Smaller Area Targets can still be created without setting an external position, but if you wish to activate the Area Targets, they must have the same setting as the first and currently activated Area Target: Requires External Position as enabled or disabled. For more details about the Location Prior, please see Location Prior for Large Area Targets.
NOTE: If a scene contains multiple Area Targets with inconsistent Requires External Position, a message will appear to apply the setting to all Area Targets. Dissimilar settings from the first activated Area Target prevents the Area Targets from being activated.
Use the Clipping Height (%) slider to hide ceiling and details that obstruct your view of the Area Target preview mesh in your Unity Scene. The complete Area Target will still track as a whole.
In Unity, you can enable occlusion in your real environment. By enabling occlusion, the added content will then be visually obstructed by the environment’s walls and objects. If you wish to test your Area Target while being able to see all your content, you can keep the box unticked.
NOTE: There aren’t any prefab models for point clouds as it is the case with Area Targets generated from meshes. But the occlusion mesh is supported.
- Select your AreaTarget GameObject and in the Area Target Behaviour component, click the Advanced dropdown. Here you may choose to have Add Occlusion Mesh enabled or disabled.
- Enable the Add Mesh Collider option to be able to ray-cast against the mesh representation of your environment or include the environment into collision and physics simulations.
Point Cloud Area Targets will only support colliders for the closest surroundings during runtime.
- Add a 3D Cube or your own content to the scene and position it in relation to the preview model, matching the scale of the environment. Add your augmentation content as a child to the AreaTarget GameObject.
NOTE: When you create a prefab out of an Area Target GameObject, and wish to build to a device and load it at runtime, you will need to add the Area Target’s _occlusion.3dt file to the Assets/StreamingAssets/Vuforia/ folder. Otherwise, the Occlusion or Collider feature will not work.
Further Development Ideas
Here are some suggestions for additional configurations of the Area Target GameObject:
- Use the freely available assets from the Vuforia Core Samples to quickly add responsive UI and billboards to your own Area Target.
- Add other Vuforia targets to your project such as a Model Target to improve tracking around an object that is central for the user experience in the AR scene.
- Add a custom occlusion shader on the preview model to selectively hide content behind walls or doors.
- Use raycasting with a mesh collider to let users place augmented content at runtime.
- Add a navigation mesh to your scene to guide users around. See NavMesh in Unity on how to do this.
- Combine multiple Area Targets in a single scene for seamless transition and tracking into new areas.
- Use the
AreaTargetBehaviourto provide access to Area Target functionality at runtime. In most cases, you call methods using the
BoundingBox()for the target’s bounding box in 3D scene units, and
Size()to get the dimensions of the physical target.
Test your Area Targets in Unity's Play Mode
Press Play in Unity to test your Area Target project with the Simulator or Recording mode located in Vuforia Configuration under Play Mode.
You can read more about the unity play modes here.
Build your Unity Project
When ready, you can build your Unity Project to your ARCore or ARKit enabled device or to a Microsoft HoloLens 2 . A Vuforia project is built in the same way as other Unity apps for Android, iOS, and UWP platforms.
With the release of Vuforia Engine 9.7, earlier generations of Area Targets databases are subject to a compatibility issue. If you have imported your Area Target .unitypackage, and you see the message below either in the log or in the inspector panel of the Area Target, you will need to apply some additional steps to unlock its full capabilities. Legacy Area Targets are essentially no longer supporting occlusion mesh and mesh colliders.
"Legacy Area Target Warning: The target 'targetName' was generated with a tool before Vuforia 9.7. Occlusion Mesh and Mesh Collider are not available automatically. Check documentation for manual steps to resolve."
Options to resolve the legacy Area Target warning:
- To use your existing legacy Area Target with all capabilities, go to the Unity Migration Guide and follow the steps to manually configure colliders and occlusion meshes.
- Re-generate your Area Target with the latest ATG. See How to Create Area Targets.
- If you are using the Area Target Creator app, re-capture your space and generate a new Area Target database from it.