Getting Started with ARToolKit for Unity

From ARToolworks support library

Main Page > ARToolKit for Unity > Getting Started with ARToolKit for Unity

Installation

ARToolKit for Unity is distributed as a Unity package. A package is an archive of files which can be imported and unpacked into your Unity project. In this case, the package contains the plugin, scripts and resources necessary to integrate ARToolKit with your Unity application.

The ARToolKit for Unity package is available to customers for download from ARToolworks. Download and store this package on your machine.

You can import the package into a fresh or existing project. Select menu Assets -> Import Package -> Custom Package... and browse to the location where you have stored the ARToolKit package. Select the package, and Unity will ask which files to import. Simply import all files at this stage.

Assets -> Import Package -> Custom Package...

Use the default (Import all)

Your Unity project now contains the necessary files for augmented reality with ARToolKit.

Package Overview

The package contains:

• ARToolKit plugin: The native plugin implementation. There are various versions for different supported platforms, such as Windows, Mac OS X, Android and iOS. This is stored in the Assets/Plugin directory (and subdirectories).
• Unity Library: A set of C# scripts that handle communication between Unity and the native plugin. These are the scripts that developers will use to access ARToolKit functionality.
• Unity Editor Library: A second set of C# scripts that extend the Unity editor itself to simplify development with customised editor panels and 3D gizmos.
• ARToolKit data files: The default camera parameters file and two sample patterns are included in the Resources/ardata directory. A sample NFT dataset is included in the Assets/StreamingAssets directory.
• Android Activity: A customised version of the Unity player for Android (packaged as a JAR file). Also required is a custom Manifest.xml file.
• Simple example: A very basic example scene which you can use to test for correct installation.

Scene Setup

Basic Setup

The key script inside the package is called simply ARToolKit, and it manages the overall initialisation, setup, running and shutdown of ARToolKit. One instance of this script should be added to the scene. For simplicity, it is recommended to add it to an empty GameObject in the root of the scene.

Dragging an instance of the "ARToolKit" script from the Asset browser onto an empty GameObject.

The ARToolKit script will handle the creation and management of the video background. All the developer needs to provide is the Unity layer in which to display the video. Layers are used to separate out parts of the scene so only certain parts are visible to certain cameras. In this case, the video background will be in its own background layer. In the same way, each marker's content will also have its own layer.

To start with, create a new layer Background and one for a single marker Foreground.

Choose "Edit layers..." in Unity.

Choose two of the User layers and give them appropriate names.

Set the "Layer" property on the "ARToolKit" object to "AR background" (or whatever you named it).

You should now be able to run the scene and see the live video.

Tracking

Tracking requires markers, so drag the Marker script onto the ARToolKit GameObject. The script will automatically locate pattern files that have been placed in the project's Resources/ardata/markers directory. The default installation will include the standard Hiro and Kanji patterns. These will appear in the dropdown list in the Marker's properties. Select the pattern you want to track. Give this marker a tag (a unique name to identify it within your project).

At this point you can run the scene again. Although no content appears on the marker yet, you should notice console messages appearing to notify that the marker has been found or lost.

To add content to the marker, add a new GameObject to the root. This object will act as a group to contain the sub-scene that will appear on the marker. Into this group, add:

• A Camera: This camera will actually render the sub-scene. (You can reuse the default camera if it exists, or otherwise delete it).
• A Cube: This will be the initial simple scene. Set the scale to 0.08, 0.08, 0.08, and position to 0, 0.04, 0, to sit on the marker correctly.

Drag a TrackedCamera script onto the new camera. This script will update the camera's pose to match your webcam, thus producing augmented reality. To link the TrackedCamera to a particular marker, enter the matching tag in the TrackedCamera's properties.

Select the new group you created and assign it to the Foreground layer created earlier (applying the change to all children when prompted). Finally, select the new camera, and set its Culling Mask property to the Foreground layer also. This step will ensure that the camera only displays the sub-scene. If you add more markers later on, you would repeat this process, but using a different layer (e.g. Foreground2).

A note on units: By default the plugin operates in meters. The default marker size is therefore 0.08 (8cm) and the camera has near and far planes of 0.1 and 1.0 respectively (10cm - 1m). These can be changed in the ARToolKit and Marker properties.

Data Files

In a standard ARToolKit application, there are several data files required, such as camera calibrations and patterns. When working with the Unity plugin, these files are included in the projects Assets directory, under the Resources/ardata directory. In order to be recognised by Unity, the files must follow a particular naming scheme.

• The camera parameters file, camera_para.dat, should be stored in Assets/Resources/ardata/ as camera_para.bytes
• Pattern files should be stored in Assets/Resources/ardata/ with a .txt extension (e.g. patt.hiro.txt)

These files can still be generated using the standard ARToolKit utilities, it is simply the filenames and locations that are important for the Unity plugin.