Integrate Litho into your Unity scene

Litho beta release 0.5.1 (02/12/2019)

Augmented Reality and Litho Interaction
Litho Showcase Scene
LithoARSessionOrigin Object
ARCamera Object
Litho Object
Showcase Object
Litho Event Helper Prefab

Augmented Reality and Litho Interaction

Below is a brief overview of the recommended augmented reality (AR) interaction flow to use with Litho. The AR side of the system is handled by Unity's AR Foundation, which is explained briefly here. The Litho 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 Litho interaction system. The Litho showcase scene provides a smorgasbord of example implementation of the components described below.

Litho Showcase Scene

The easiest way to get started with Litho is to take a look at the Litho showcase scene: it illustrates some basic types of interaction that can be achieved using Litho. 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/Litho/Demo/LithoShowcase/LithoShowcase.unity Ensure you have set up your project first.

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

Description	Hierarchy
*LithoUI* hosts a canvas for managing connection to Litho and other Litho features. *LithoARSessionOrigin* handles scaling and positioning of the AR session and trackables (including Litho). *ARCamera* handles the AR session information, such as whether to process updates. *Litho* represents the position of Litho in AR space. *Floor* represents the position of the ground in AR space. *LithoShowcase* demonstrates some basic interaction capabilities of Litho.

Description

Hierarchy

LithoUI hosts a canvas for managing connection to Litho and other Litho features.
LithoARSessionOrigin handles scaling and positioning of the AR session and trackables (including Litho).
ARCamera handles the AR session information, such as whether to process updates.
Litho represents the position of Litho in AR space.
Floor represents the position of the ground in AR space.
LithoShowcase demonstrates some basic interaction capabilities of Litho.

LithoARSessionOrigin Object

To make Litho work in AR, the project relies on the AR Foundation package. This prefab contains the other Litho 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 Litho's interactions work in Unity is covered in more detail here.

Description	Inspector
*Transform* represents spatial properties of the AR session *AR Manager (Script)* is essential for Litho 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. AR Session Origin (Script)** handles coordinate information. AR Session (Script) (auto-enabled at runtime) handles the AR session information, such as whether to process updates. AR Input Manager (Script) (added at runtime) manages motion input (e.g. camera tracking). AR Plane Manager (Script) (added at runtime) handles creation, updates and deletion of GameObjects representing real-world planes. *Don't Destroy On Load (Script)* preserves the AR session state across scene transitions.

Description

Inspector

Transform represents spatial properties of the AR session
AR Manager (Script) is essential for Litho 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.
AR Session Origin (Script) handles coordinate information.
AR Session (Script) (auto-enabled at runtime) handles the AR session information, such as whether to process updates.
AR Input Manager (Script) (added at runtime) manages motion input (e.g. camera tracking).
AR Plane Manager (Script) (added at runtime) handles creation, updates and deletion of GameObjects representing real-world planes.
Don't Destroy On Load (Script) preserves the AR session state across scene transitions.

ARCamera Object

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

Description	Inspector
*Transform* locates the AR camera in Unity coordinates; values here will be *driven by the AR Pose Driver* script. Camera (Script) handles rendering of Unity objects. AR Pose Driver (Script)** keeps this Unity camera aligned with the real-world camera (when the app is running on a mobile device) AR Camera Manager (Script) (auto-enabled at runtime) Handles camera texture and light estimation. *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.

Description

Inspector

Transform locates the AR camera in Unity coordinates; values here will be driven by the AR Pose Driver script.
Camera (Script) handles rendering of Unity objects.
AR Pose Driver (Script) keeps this Unity camera aligned with the real-world camera (when the app is running on a mobile device)
AR Camera Manager (Script) (auto-enabled at runtime) Handles camera texture and light estimation.
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.

Litho Object

The Litho object represents your Litho 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 Litho object prefab can be found in the demo scene and should be a child of the ARSessionOrigin object. When building your own Litho scene, make the Litho prefab a child of the ARSessionOrigin object, and ensure you provide the Litho object with a reference to the main AR camera object in your scene. Further details can be found here

Description Inspector

Description	Inspector
*Transform* represents the real-world position of your connected Litho in game world/AR coordinates. Do not modify this manually or in other scripts as it is overridden by the Litho script. *Litho (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 Litho Plugin. However, you can set the default Litho handedness and grip here using the Unity Inspector window, and override the defaults whilst in play mode. *Pointer (Script)* controls the behaviour of the laser pointer and uses the Unity Line Renderer to visualize it. Ignore Layers lets you select the layers the pointer should ignore Release Range determines how far a `Manipulable` may move from where this `Pointer` wants it to be before it is automatically dropped. Pointer Properties provides a set of advanced controls for how Litho touches and rotations map to object depth and yaw. *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. *Game View Controller* implements the Litho emulator and explains its controls in the Inspector window.

Transform represents the real-world position of your connected Litho in game world/AR coordinates. Do not modify this manually or in other scripts as it is overridden by the Litho script.
Litho (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 Litho Plugin. However, you can set the default Litho handedness and grip here using the Unity Inspector window, and override the defaults whilst in play mode.
Pointer (Script) controls the behaviour of the laser pointer and uses the Unity Line Renderer to visualize it.
- Ignore Layers lets you select the layers the pointer should ignore
- Release Range determines how far a Manipulable may move from where this Pointer wants it to be before it is automatically dropped.
- Pointer Properties provides a set of advanced controls for how Litho touches and rotations map to object depth and yaw.
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.
Game View Controller implements the Litho emulator and explains its controls in the Inspector window.

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 Litho Pointer. The examples can be navigated by using the Litho pointer to click the arrow buttons on the showcase platform. Inspect these 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 LithoARSessionOrigin object - this ensures it is positioned correctly when a ground plane is selected.

Game View	Hierarchy and Inspector

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

Litho Event Helper Prefab

The Litho Event Helper object can be added to your scene to help you understand [Litho global events(UnityScripting.md#litho-events) prints Litho 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 Litho Events field.

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

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