Introduction to Ground Plane in Unity

Introduction

This guide walks developers through how to create an Augmented Reality experience using Vuforia’s Ground Plane feature in Unity. To learn more about Ground Plane, please refer to the Ground Plane Feature Guide.

NOTE: The initial release of Vuforia Ground Plane in Unity 2017.3 (Vuforia v7.0.36) supports ARKit enabled iOS devices only.  Android devices and non-ARKIt enabled iOS devices are supported in Unity 2017.3 Patch 2 (Vuforia 7.0.43 or later). Download Unity 2017.3 Patch 2 from Unity here. See Supported Device List for the latest device coverage. New devices are added frequently.

 

Creating your first Ground Plane Experience

These steps will guide you through the process of creating your first Ground Plane experience in Unity.

  1. Open Unity 2017.3 or newer
  2. Create a New Project
  3. In the Edit Menu select: Project Settings> Player. In the “XR Settings” section of the PlayerSettings, make sure that “Vuforia Augmented Reality Supported” is checked.
Vuforia Image
  1. Replace the default “Main Camera” with an ARCamera. In the Game Object Menu select: Vuforia> AR Camera to create a new AR Camera object in the scene. Remove the default “Main Camera” from the scene.
  2. In the Game Object Menu select: Vuforia> Ground Plane> Ground Plane Stage.
Vuforia Image
  1. The Ground Plane Stage GameObject serves as a parent GameObject. Content should be made a child of the Ground Plane Stage GameObject. Notice that the Ground Plane 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 . Furthermore, the Ground Plane Stage allows for content to be positioned relative to the ground plane itself; allowing you to place content relative to the real-world ground planes.
Vuforia Image
  1. Let’s put some content onto the Ground Plane Stage. In the Game Object Menu, select: 3D Object> Capsule. This will create a new Capsule object in the Unity Hierarchy window. Drag the Capsule so that it is inside of the Ground Plane Stage GameObject. Set the X,Y, and Z position of the Capsule to 0. Set the X, Y and Z Scale to 0.5 and you should see it take up about half of the stage.
Vuforia Image
  1. In the Game Object Menu and select: Vuforia> Ground Plane> Plane Finder. The Plane Finder does the following:
    1. Listens to input from the user (such as a tap on the device screen) with the Anchor Input Listener Behaviour
    2. Attempts to find an appropriate plane to place content in the real world with the Plane Finder Behaviour
    3. Places the content into the real world with the Content Positioning Behaviour
Vuforia Image
  1. Drag your “Ground Plane Stage” object into the “Anchor Stage” parameter of the “Content Positioning Behaviour” component
Vuforia Image
  1. Let's go ahead and deploy to your device to see how our Ground Plane experience looks like. Be sure to use a device that is in the Ground Plane supported devices list. On the device, look around your environment. Notice that there is a reticle that is projected onto planes. Once you find a surface you like, tap on the screen. You should notice that the capsule is placed on the plane where the reticle is pointing to. If you take a couple of steps back, you will notice another capsue floating at the point where you tapped on the screen. The stage is placed at the origin of the scene (device location) and it is also deployed when the user taps on the screen.
Vuforia Image
  1. Vuforia allows developers to emulate a Ground Plane when running in Unity’s Play Mode. Allowing developers to test out their Ground Plane experiences without having to deploy to a device. To emulate a ground plane, in the Project window, go to Assets\Editor\Vuforia\ForPrint\Emulator\ and open the “Emulator Ground Plane.pdf” file and print the appropriate template depending on the size of paper with no scaling in the printer driver.
Vuforia Image
  1. Attach a standard webcam to your computer and press the “Play” button in Unity. Point your webcam to the Ground Plane Template.
Vuforia Image
  1. You should see the Capsule appear relative to the Ground Plane template.
    NOTE: When testing the scene on the device, be aware that Ground Plane on the device will not immediately place the content in your environment as it does in the emulator.
Vuforia Image
  1. You can replace the capsule with whatever content you would like. Here we have replaced the capsule with an astronaut.
Vuforia Image
  1. If you are looking to place content once the user taps on the screen and for the content to move when the user taps in a new location, follow these steps:
    1. In the Vuforia Configuration window, make sure that the following "Device Tracker" settings are configured: "Track Device Pose" checked and "Tracking mode" set to "POSITIONAL"
    2. In the "Plane Finder" GameObject, replace the ContentPositioningBehaviour component with the following script:   >
          using System;
          using UnityEngine;
          using Vuforia;
      
          public class DeployStageOnce : MonoBehaviour {
              
              public GameObject AnchorStage;
              private PositionalDeviceTracker _deviceTracker;
              private GameObject _previousAnchor;
              
              public void Start ()
              {
                  if (AnchorStage == null)
                  {
                      Debug.Log("AnchorStage must be specified");
                      return;
                  }
      
                  AnchorStage.SetActive(false);
              }
      
              public void Awake()
              {
                  VuforiaARController.Instance.RegisterVuforiaStartedCallback(OnVuforiaStarted);
              }
      
              public void OnDestroy()
              {
                  VuforiaARController.Instance.UnregisterVuforiaStartedCallback(OnVuforiaStarted);
              }
      
              private void OnVuforiaStarted()
              {
                  _deviceTracker = TrackerManager.Instance.GetTracker<PositionalDeviceTracker>();
              }
      
              public void OnInteractiveHitTest(HitTestResult result)
              {
                  if (result == null || AnchorStage == null)
                  {
                      Debug.LogWarning("Hit test is invalid or AnchorStage not set");
                      return;
                  }
      
                  var anchor = _deviceTracker.CreatePlaneAnchor(Guid.NewGuid().ToString(), result);
      
                  if (anchor != null)
                  {
                      AnchorStage.transform.parent = anchor.transform;
                      AnchorStage.transform.localPosition = Vector3.zero;
                      AnchorStage.transform.localRotation = Quaternion.identity;
                      AnchorStage.SetActive(true);
                  }
      
                  if (_previousAnchor != null)
                  {
                      Destroy(_previousAnchor);
                  }
      
                  _previousAnchor = anchor;
              }
          }
      
    3. Drag your “Ground Plane Stage” object into the “Anchor Stage” parameter of the new “Deploy Stage Once” component

Placing Floating Content in your Environment

The workflow of placing floating content is very similar to the workflow of placing content onto planes. This section will highlight the major differences between floating content and grounded content.

  1. Instead of Creating a “Ground Plane Stage”, create a “Mid Air Stage”. In the Game Object Menu and select: Vuforia> Mid Air> Mid Air Stage.
Vuforia Image
  1. Like the Ground Plane Stage, the Mid Air Stage GameObject serves as a parent GameObject for which content is placed in. 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.
Vuforia Image
  1. Make your content a child of the Mid Air Stage. In this example, we put the model of a drone inside of the Mid Air Stage.
Vuforia Image
  1. Use the real-world scale on the Mid Air Stage in order to properly position and scale your content relative to the stage – which is 50cm on each side
Vuforia Image
  1. In the Game Object Menu and select: Vuforia> Mid Air > Mid Air Positioner. The Mid Air Positioner behaves much like the Plane Finder does for Ground Planes.
Vuforia Image
  1. Drag the Mid Air Stage object onto the Anchor Stage parameter of the Content Positioning Behaviour component.
Vuforia Image
  1. Again, with a standard webcam to your computer and press the “Play” button in Unity. You will  see a green translucent sphere in the middle of your screen. The green sphere is an indicator of where the user is about to place content.
Vuforia Image
  1. Point your webcam to the Ground Plane Template and then move the webcam away from the template into an area floating in the room. Once the screen is tapped/clicked, you will see your content placed in the environment.
Vuforia Image