Penguin Smart Terrain Sample

The Penguin sample project provides a fully developed Smart Terrain project in Unity. The project demonstrates recommended development practices and techniques for customizing the app logic of Smart Terrain apps, and also how to integrate digital assets and apply rendering techniques to the artifacts returned by the Smart Terrain tracker.

The Penguin Project is made up of three Unity scenes: a splash screen scene, a loading indicator scene, and the Penguin Smart Terrain scene. The prefabs and assets relevant to Smart Terrain are all within the Penguin scene.

The ARCamera instance represents the device camera in the scene and is responsible for configuring the scene s world center orientation, and render quality along with loading and activating the target dataset used in this scene.

The Penguin project uses a Cylinder Target to initialize the Smart Terrain instance. This initialization target provides a scale reference for the scene and also establishes the position and orientation of the scene s Primary Surface plane.

The UIStateManager object is responsible for managing the lifecycle of the Smart Terrain tracker and presenting GUI elements in response to changes in the state of the app.
The Smart Terrain instance is enabled and associated with its initialization target through the target s Smart Terrain component in the Unity Inspector.

Each Smart Terrain instance includes the Primary Surface plane and a Prop Template as child objects by default. Any content that should be rendered when the terrain is being tracked should be added as a child of the Smart Terrain instance. This is why the Penguin model is a child of the Smart Terrain instance, rather than the initializing Cylinder Target.

Enabling Smart Terrain

Smart Terrain has been enabled for the Cylinder Target instance by selecting the Smart Terrain option on the target's Cylinder Target Behaviour component in the Inpector. This causes a Smart Terrain instance to be added to the scene that is configured to use the Cylinder Target as its initialization target. The Occluder Bounds for the Smart Terrain instance will also be defined to match the dimensions of the Cylinder Target.

Penguin Project Prefabs Configuration Explained

This article will walk you through how the prefabs have been configured and explain why.

ARCamera

The ARCamera prefab s Data Set Load Behaviour is configured to Load and Activate the sodacan dataset in the Streaming Assets / QCAR folder.

The World Center for the scene is defined using the Smart Terrain instance and the SPECIFIC_TARGET World Center Mode. These settings establish the origin of the Terrain mesh as the world origin for the scene. This point will correspond to the center of the Primary Surface.

Cylinder Target

The Cylinder Target prefab has been configured to provide an accurate scale measurement of the real-world target. The printable target provided with the project is intended to be wrapped around a standard 12oz soda can, which is 66 mm in diameter. Because the Cylinder Target was defined with a 0.66 diameter in the Target Manager, a scale factor has been defined to convert this dimension to to the true scale of the target. The Scale Facor to mm field defines this value, as 100 ( 0.66 x 100 = 66 mm ).

The Cylinder Target will initialize the Smart Terrain prefab instance identified in the Smart Terrain Instance field. When the Smart Terrain option is check on a target, a Smart Terrain instance will be added to the scene that is preconfigured to use that target for initialization.

Smart Terrain

The Smart Terrain prefab instance is set to start mesh updates automatically once the Cylinder Target is detected using the Automatic Start checkbox on the Smart Terrain Behaviour component.

Smart Terrain instance customization using prefab component in the Unity Inspector
The Smart Terrain instance is using two custom event handlers:

  • Smart Terrain Trackable Event Handler, implementing ITrackableEventHandler, enables and disables the Primary Surface mesh and its children in response to tracking events.
  • Smart Terrain Event Handler, implementing ISmartTerrainEventHandler, is responsible for associating prop instance with PropBehaviours, and managing the lifecycle of prop instances.

How An Animated Model was Added to the Penguin Sample

The sample provides a textured penguin model in the Penguin Assets folder. A Prefab of the Penguin that incorporates this model along with an animation and character controller can be found in PenguinAssets/ Prefabs. The Penguin prefab is added as a child of the Smart Terrain prefab instance in the scene. This enables the Penguin prefab and its components to be enabled and disabled programmatically by the Smart Terrain Trackable Event Handler in reponse to tracking events.

Configuring

The Penguin Prefab is configured with a default set of physics and Character Controller properties. You can adjust these to modify the movement characteristics of the Penguin model in response to touches on the device screen. These touches are raycast onto the Primary Surface mesh so that the pengiun will move to the correct corresponding point in the scene.

The Penguin.cs script handles these touches, and calls the Character Controller s Move method with the movement vector necessary to direct the Penguin to the tapped position. The speed of the Penguin s movement is defined by the public Movement Speed property, which you can set in the Inspector.

How To Deploy the Penguin Sample

Follow these steps to build and deploy the Penguin sample project. The Penguin sample is a Best Practices sample for Smart Terrain that demonstrates how to design an effective user experience for Smart Terrain apps.

Building the app

1. Set your platform build target for either IOS or Android in File > Build Settings.
2. Add your scenes to Scenes in Build in the following order.

The Penguin app's scene order in Scenes In Build

3. Define a unique Bundle ID in Player Settings > Other Settings.
4. Define a unique Product Name to serve as the name of the app when installed on a device.
5. Select Build to generate an executable or Build & Run to both generate an executable and deploy it to a connected device.

Setting the stage

Select a visually distinct area with apparent borders, such as a table top. The stage area should be well lit and the lighting conditions should remain consistent throughout the play session. Indoor settings are recommended.

Place the Cylinder target on the stage, away from the stage border.

Use props that have detailed patterns. The Smart Terrain tracker looks for the same types of contrast based features that are used for other trackable types.

See: Smart Terrain Workflow in Unity for additional information and recommendations on staging a Smart Terrain scene.

Scanning the stage

The recommended practice for scanning the stage, is to start with the device camera close to the initializing target so that it nearly fills the camera image. Once the target is recognized, slowly pull the device back until the entire stage is within the field of view of the camera. You can then move side to side to generate box meshes. Avoid erratic camera motion during the scanning phase as this will negatively affect the ability of the tracker to generate an accurate reconstruction of the stage. It s best to move the device in a smooth continuous trajectory when you are scanning the stage area.

How To Play the Penguin App

The Penguin sample implements stage scanning and game play as distinct stages of the app's execution. These phases are acknowledged through GUI elements which instruct the user and provide buttons to complete the scanning phase and to refresh the scene. When the app is first launched, the user is presented with a visual guide of in the shape of a can and the instruction to point their device at the target. Aligning the guide to the can will bring the Cylinder Target into view, enabling it to be recognized. This will cause the Smart Terrain Tracker to initialize.

Once the initializing target is recognized, the user will be prompted to pull back slowly this behavior will enables them to scan the stage surface most effectively. Their progress in scanning the stage and reconstructing the props they ve placed will be indicated by a growing ice surface and white boxes on the props. The boxes indicate that the props have been detected and that their volumes are being reconstructed.

The user can indicate when they have completed scanned the stage by clicking the Done button. This will activate the Play phase in which the penguin will appear and the reconstructed props will be rendered as icebergs.

The user can then tap on the icey stage surface to navigate the penguin across the stage and around the icebergs. This action demonstrates use of a character controller and Unity physics on the reconstructed stage and props.