Link

This site uses Just the Docs, a documentation theme for Jekyll.

Search

Unity Integration

AR Controller beta release 0.7.0 (2022-06-25)

Table of contents

  1. Augmented Reality and AR Controller Interaction
  2. AR Controller Showcase Scene
  3. ARControllerARSessionOrigin Object
  4. ARCamera Object
  5. ARController Object
  6. Floor Object
  7. Ground Plane Object
  8. Showcase Object
  9. ARController Event Helper Prefab

Augmented Reality and AR Controller Interaction

Below is a brief overview of the recommended augmented reality (AR) interaction flow to use with AR Controller. The AR side of the system is handled by Unity’s AR Foundation, which is explained briefly here. The AR Controller SDK sits within the AR Foundation framework, which allows you to tangibly reach into any AR experiences that you make. The following sections explain the objects that make up the AR Controller interaction system. The AR Controller showcase scene provides a smorgasbord of example implementation of the components described below.

AR Controller Showcase Scene

The easiest way to get started with AR Controller is to take a look at the AR Controller showcase scene: it illustrates some basic types of interaction that can be achieved using AR Controller. You can then use the demo objects as a basis for your own interactions.

  • In your Unity project, open this scene by double-clicking on Assets/AR Controller/Demo/AR ControllerShowcase/AR ControllerShowcase.unity Ensure you have set up your project first.

It is highly recommended that you look through the features available in the AR Controller showcase before getting started with your own project. Future updates and new AR Controller interactions will be demonstrated in the showcase.

Description Hierarchy
1. ARControllerUI hosts a canvas for managing connection to AR Controller and other AR Controller features.
2. ARControllerARSessionOrigin handles scaling and positioning of the AR session and trackables (including AR Controller).
3. ARCamera handles the AR session information, such as whether to process updates.
4. ARController represents the position of AR Controller in AR space.
5. Floor represents the position of the ground in AR space.
6. ARControllerShowcase demonstrates some basic interaction capabilities of AR Controller.
AR Controller Showcase Scene Hierarchy

ARControllerARSessionOrigin Object

To make AR Controller work in AR, the project relies on the AR Foundation package. This prefab contains the other AR Controller and AR objects required to make the scene work. A basic overview is given below, but more detail on AR Foundation can be found here. How AR Controller’s interactions work in Unity is covered in more detail here.

Description Inspector
1. Transform represents spatial properties of the AR session.
2. AR Manager (Script) is essential for AR Controller to work. It interfaces with AR Foundation to allow the user to select a ground plane, then places the Floor object and Focus Object at the chosen position. This removes the need to scan the entire room before using the app. Note: you will need to manually set the Focus Object for every new scene you create.
3. AR Session Origin (Script) handles coordinate information.
4. AR Session (Script) (auto-enabled at runtime) handles the AR session information, such as whether to process updates.
5. AR Input Manager (Script) (added at runtime) manages motion input (e.g. camera tracking).
6. AR Plane Manager (Script) (added at runtime) handles creation, updates and deletion of GameObjects representing real-world planes.
7. Don’t Destroy On Load (Script) preserves the AR session state across scene transitions.
AR Session Origin Object

ARCamera Object

This represents the real-world (mobile phone) AR camera and makes the Unity scene camera match its position.

Description Inspector
1. Transform locates the AR camera in Unity coordinates; values here will be driven by the AR Pose Driver script.
2. Camera (Script) handles rendering of Unity objects.
3. AR Pose Driver (Script) keeps this Unity camera aligned with the real-world camera (when the app is running on a mobile device)
4. AR Camera Manager (Script) (auto-enabled at runtime) Handles camera texture and light estimation.
5. AR Camera Background (Script) handles ‘passthrough’ of the camera video stream to the Unity camera buffer, allowing Unity objects to be rendered in front of real-world objects.
AR Camera Object

ARController Object

The AR Controller object represents your AR Controller device in the scene (Only 1 copy of this object/ script should exist in your scene.) The laser pointer is cast from this object, which is automatically positioned relative to the camera. The AR Controller object prefab can be found in the demo scene and should be a child of the ARSessionOrigin object. When building your own AR Controller scene, make the AR Controller prefab a child of the ARSessionOrigin object, and ensure you provide the AR Controller object with a reference to the main AR camera object in your scene. Further details can be found here

Description Inspector
1. Transform represents the real-world position of your connected AR Controller in game world/AR coordinates. Do not modify this manually or in other scripts as it is overridden by the AR Controller script.
2. AR Controller (Script) needs a reference to the main AR camera to function (if not set, any object tagged with MainCamera will be used). Code in this script should not be modified, as it communicates directly with the AR Controller Plugin. However, you can set the default AR Controller handedness and grip here using the Unity Inspector window, and override the defaults whilst in play mode.
3. Pointer (Script) controls the behaviour of the laser pointer and uses the Unity Line Renderer to visualize it.
4. Ignore Layers lets you select the layers the pointer should ignore
5. Release Range determines how far a Manipulable may move from where this Pointer wants it to be before it is automatically dropped.
6. Pointer Properties provides a set of advanced controls for how AR Controller touches and rotations map to object depth and yaw.
7. Line Renderer is a standard Unity component that renders the laser pointer. Modify the properties and materials here to change how the laser pointer looks.
8. Game View Controller implements the AR Controller emulator and explains its controls in the Inspector window.
AR Controller Object

Floor Object

The Floor object represents the height of the ground in AR space, which is updated by the World Interpreter script (via the Ground Plane Unity Inspector field). Objects that rest on or interact with the floor should have the Floor object as their parent - this will ensure they don’t get occluded (visually or physically) by the Ground Plane object.

Ground Plane Object

The Ground Plane object hosts a large box collider, which is positioned as a child of the Floor object to prevent objects from falling through the floor - this simplifies AR scanning of the floor, as the entire floor becomes physically present after choosing a single point on the scanned floor.

The Ground Plane object also hosts two different meshes - one for use in the Unity Editor (shows a visible plane), and one for built AR apps (implements AR occlusion and shadows). These are automatically deleted from the Editor/ builds as appropriate.

Showcase Object

The Showcase object collates a variety of interaction prefabs into a small platform that is suitable for manipulation in AR. The interaction prefabs serve as examples of how to implement interactions with the AR Controller Pointer. The examples can be navigated by using the AR Controller pointer to click the arrow buttons on the showcase platform. Inspect these objects in the Unity Hierarchy window to learn more about how to implement different interactions, and look here for more details.

Note: the Showcase object is set as the Focus Object of the ARManager on the ARControllerARSessionOrigin object - this ensures it is positioned correctly when a ground plane is selected.

Game View Hierarchy and Inspector
Scene overview Scene overview

More information about how these showcase objects work is provided here.

ARController Event Helper Prefab

The ARController Event Helper object can be added to your scene to help you understand [AR Controller global events(UnityScripting.md#arcontroller-events) prints AR Controller global events (and their parameters) to the Unity Console as they happen. This event logging can be toggled on or off using the Log Global AR Controller Events field.

The ARController Event Helper object is not critical to the AR Controller system - you can delete this object without any issues occurring, or simply disable the AR Controller Global Event Logger script (uncheck the Log Global AR Controller Events field) if the logging becomes obtrusive.

The code in the AR Controller Global Event Logger script can also be viewed as an example of how to access the events exposed by the AR Controller script - other code samples for AR Controller events can be found here.

ARController Event Helper Object