This page concerns the Vuforia Engine API version 9.8 and earlier. It has been deprecated and will no longer be actively updated.
This guide will walk you through how to create an Augmented Reality experience in Unity. We recommend using the Vuforia Core Sample as a starting point. It is available from the Unity Asset Store.
NOTE: Ground Plane is supported for Android, iOS, and UWP. Ground Plane is only compatible with devices supported by Platform Enablers (ARKit/ARCore) or devices that have been specifically calibrated by Vuforia Engine. See the Recommended Devices List for the latest device coverage.
Ground Plane in Unity
The Ground Plane is best demonstrated through the Vuforia Core Samples for Unity and we recommend starting here to get familiar with the concepts and components to build your own surface detecting AR experience.
- Create and open a new project in Unity. Set it up with the Vuforia Engine according to the Getting Started guide here.
- Navigate to the Unity Asset Store (in a web browser) and search for Vuforia.
- Select and add the Vuforia Core Samples to your assets. Make sure you are logged in with your Unity account.
- Return to the Unity Editor and open the Package Manager from the tab Window -> Package Manager.
- In the dropdown menu, select My Assets
- Select the Vuforia Core Samples and press Import. This will install the Vuforia Engine and all necessary dependencies.
- When complete, locate and open the 3-GroundPlane scene in the Project tab under Assets/SamplesResources/Scenes
- To test the Ground Plane feature with Play Mode a target must first be printed. This target is located in Assets/Editor/Vuforia/ImageTargetTextures/VuforiaEmulator/.
Alternatively, open the tab File -> Build Settings and select your platform and build to your device.
Ground Plane Scene structure
Besides the essential components for using Ground Planes, the sample scene offers us a look into other useful parts to build an intuitive AR experience.
PlaneManager.cs controls the logic for hit testing for surfaces and resets. It also defines the content placed in the real world in the stages: Anchor_Plane and Anchor_MidAir.
ProductPlacement.cs and TouchHandler.cs shows a logic on how to let users interact with the placed content.
GroundPlaneUI.cs holds UI to instruct and interact with each virtual content.
Creating your First Ground Plane Experience
In this section, we will add the Ground Plane capabilities to an empty Unity project and we will explain the components as they are added. The steps will guide you in adding and testing the Ground Plane.
- Open Unity and Create a New Project.
- Add the Vuforia Engine SDK as described in this article.
- Delete the default Main Camera and add an ARCamera GameObject by expanding the GameObjectmenu dropdown and select Vuforia Engine -> AR Camera.
- Open the Vuforia Engine configuration and add a license key.
- In the same fashion as above, go to GameObject and add Vuforia Engine -> Ground Plane> Ground Plane Stage.
The Ground Plane Stage GameObject serves as a Parent GameObject. Your content should be made a child of this component.
Notice that the Ground Plane Stage has visual markings indicating that it is a 100 cm square. These visual guides are only rendered in the Unity Editor and serve to determine real-world scale in the Unity Editor. Furthermore, the Ground Plane Stage allows your content to be positioned relative to the Ground Plane itself, allowing you to place content relative to the real-world surfaces and scale.
We will add some content onto the Ground Plane Stage.
- Select the Ground Plane Stage GameObject in the Hierarchy and right-click to add a 3D Object -> Capsule. Set its X, Y, and Z scale to 0.5.
- In the GameObject Menu, select Vuforia Engine -> Ground Plane> Plane Finder.
The Plane Finder does the following:
- Anchor Input Listener Behaviour - Listens to input from the user (such as a tap on the device screen).
- Plane Finder Behaviour - Attempts to find an appropriate plane to place content in the real world.
- Content Positioning Behaviour - Places content into the real world.
Here, you may personalize the indicator for identifying surfaces and set the Mode to either AUTOMATIC for auto detection or INTERACTIVE for detection based on user input. You can also define the Height for the expected distance between the device and plane.
- Drag the Ground Plane Stage GameObject into the Anchor Stage parameter of the Content Positioning Behaviour component in the Plane Finder GameObject. This is all that is needed for the Ground Plane to function.
Building and testing on your device
- We will deploy to the device to test our Ground Plane experience.
Be sure to use a device that is on the Ground Plane Recommended Devices List. See here for instructions to set up the Build Settings and Player Settings and build and run the application to your device. If a device is unavailable, see the Ground Plane Emulator section below.
- Launch the app and look around your environment. Notice that a reticle should appear and project onto planes.
Once you find a suitable surface, tap the screen. You should see the capsule placed on the plane where the reticle is pointing to. Tapping once more add additional capsules.
By default, the Content Positioning Behaviour will duplicate the stage and content each time it is activated. To instead move the stage on each user’s tap, the Content Positioning Behaviour’s Duplicate Stage can be unchecked.
Ground Plane Emulator
If a supported device is unavailable, you can use Vuforia Engine to emulate a Ground Plane when running in Unity’s Play Mode. This allows developers to test out their Ground Plane experiences without having to deploy to a device.
- To emulate a Ground Plane, navigate to the Project window and go to Assets\Vuforia\Databases\ForPrint\Emulator\ and open the Emulator Ground Plane.pdf file and print the template on an A4 sizes paper with no scaling applied.
- Attach a standard webcam to your computer and press the “Play” button in Unity. Point your webcam to the Ground Plane Template.
- You should see the capsule appear relative to the Ground Plane template. If not, then make sure that the Play Mode is correctly set to WEBCAM in the Vuforia Configuration (Cmd+Shift+V or Ctrl+Shift+V).
Placing Floating Content in your Environment
The workflow for placing floating content is very similar to the workflow for placing content onto planes. This section will highlight the major differences between floating content and grounded content.
- Instead of creating a Ground Plane Stage, create a Mid Air Stage. From the GameObject menu, select Vuforia Engine -> Mid Air > Mid Air Stage.
- The Mid Air Stage GameObject serves as a parent GameObject to which content is placed as a child.
Notice that the Mid Air Stage has visual markings indicating that it is 100cm square. These visual guides are only rendered in the Unity Editor and serve to determine real-world scale in the Unity Editor.
- Add your content as a child of the Mid Air Stage. In this example, we added the model of a drone inside the Mid Air Stage.
- Use the real-world scale on the Mid Air Stage to properly position and scale your content relative to the stage – which is 50cm to each side.
- In the GameObject Menu, select Vuforia Engine> Mid Air > Mid Air Positioner. The Mid Air Positioner behaves much like the Plane Finder does for Ground Planes.
The Mid Air Stage does the following:
- Anchor Input Listener Behaviour - Listens to input from the user (such as a tap on the device screen).
- Mid Air Positioner Behaviour - Attempts to find an appropriate plane to place content above.
Here you may configure the distance between the indicator and the camera. You can also customize the indicator.
- Content Positioning Behaviour - Places content into the real world.
- Drag the Mid Air Stage GameObject onto the Anchor Stage parameter of the Content Positioning Behaviour component.
- Now, Build or test with a standard webcam your scene. You will see a green translucent sphere in the middle of your screen. The green sphere is an indicator of where you will place content when tapping.
Advanced Configuration
The Ground Plane sample demonstrates just one way to build your app logic and create an immersive and interactive AR experience. The components for enabling Ground Plane is just for the common use case and can be easily configured to build your own app logic.
To customize, you can write your own logic to position content at an empty Anchor when a hit test result returns a suitable surface. Substitute ContentPositioningBehaviour with a custom script that use the PositionalDeviceTracker API to create empty Anchors. Then, have the MidAirPositionerBehaviour and PlaneFinderBehaviour call the custom script.
Change the way hit tests are delivered to for example user inputs. Integrate your own UI system and invoke events by button presses. Simply, call MidAirPositionerBehaviour and PlaneFinderBehaviour events that normally are invoked by the AnchorInputListener