Introduction to Ground Plane in Unity

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 Supported Device 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.

  1. Create and open a new project in Unity. Set it up with the Vuforia Engine according to the Getting Started guide here.
  2. Navigate to the Unity Asset Store (in a web browser) and search for Vuforia.
  3. Select and add the Vuforia Core Samples to your assets. Make sure you are logged in with your Unity account.
  4. Return to the Unity Editor and open the Package Manager from the tabWindow -> Package Manager.
  5. In the dropdown menu, selectMy Assets

  1. Select the Vuforia Core Samples and pressImport. This will install the Vuforia Engine and all necessary dependencies.
  2. When complete, locate and open the3-GroundPlane scene in the Project tab underAssets/SamplesResources/Scenes
  3. To test the Ground Plane feature with Play Mode a target must first be printed. This target is located inAssets/Editor/Vuforia/ImageTargetTextures/VuforiaEmulator/.

Alternatively, open the tabFile -> Build Settingsand 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 andTouchHandler.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.

  1. Open Unity and Create a New Project.
  2. Add the Vuforia Engine SDK as described in this article.
  3. Delete the defaultMain Camera and add anARCamera GameObject by expanding theGameObjectmenu dropdown and selectVuforia Engine -> AR Camera.
    1. Open theVuforia Engine configurationand add a license key.
  4. In the same fashion as above, go toGameObjectand addVuforia Engine -> Ground Plane> Ground Plane Stage.

TheGround Plane Stage GameObject serves as aParent 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.

  1. Select theGround Plane Stage GameObject in the Hierarchy and right-click to add a3D Object -> Capsule. Set its X, Y, and Z scale to 0.5.

  1. In theGameObject Menu, selectVuforia 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 theModeto 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.

  1. Drag theGround Plane Stage GameObject into theAnchor Stage parameter of theContent Positioning Behaviour component in thePlane Finder GameObject. This is all that is needed for the Ground Plane to function.

Building and testing on your device

  1. We will deploy to the device to test our Ground Plane experience.

Be sure to use a device that is on the Ground Plane supported devices list. See here for instructions to set up theBuild SettingsandPlayer Settingsandbuild and run the application to yourdevice. If a device is unavailable, see the Ground Plane Emulator section below.

  1. 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, theContent Positioning Behaviour will duplicate the stage and content each time it is activated. To instead move the stage on each user's tap, theContent Positioning Behaviour'sDuplicate 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.

  1. To emulate a Ground Plane, navigate to the Project window and go toAssets\Vuforia\Databases\ForPrint\Emulator\ and open theEmulator Ground Plane.pdf file and print the template on an A4 sizes paper with no scaling applied.

  1. Attach a standard webcam to your computer and press the "Play" button in Unity. Point your webcam to the Ground Plane Template.

  1. You should see the capsule appear relative to the Ground Plane template. If not, then make sure that thePlay Mode is correctly set to WEBCAM in theVuforia 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.

  1. Instead of creating aGround Plane Stage, create aMid Air Stage. From theGameObject menu, selectVuforia Engine -> Mid Air > Mid Air Stage.
  2. TheMid Air Stage GameObject serves as aparent 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.

  1. 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.

  1. 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.

  1. In theGameObject Menu, selectVuforia 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.
  1. Drag theMid Air Stage GameObject onto theAnchor Stage parameter of theContent Positioning Behaviour component.

  1. 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.