Migrate to ARToolKit6 from ARToolKit5

Tutorials July 17, 2017 Thor_Bux

ARToolKit5, ARToolKit6, Tutorial, Unity, Unity3D

From the SolarSystem example

I have created this amazing SolarSystem example using ARToolKit5. It is a great way to show how to bring Augmented Reality to life. With the release of ARToolKit6, I felt the need to update the example from ARToolKit5 to ARToolKit6. Let’s see what effort is involved in migrating the project. While developing on desktop you should use a good webcam.

Import the ARToolKit6.unitypackage

Let us just give it a try and import the ARToolKit6.unitypackage into the same project and see how it goes.

It seems like the package is going to be installed into the ARToolKit5-Unity directory. I’d have expected it to be installed into something named ARToolKit6

Let’s just hit Import

Yes, it looks like the ARToolKit6 scripts and libraries are imported next to the ARToolKit5 scripts and libraries. To be honest that seems to be a bit messy.

In addition to that we get a lot of errors:

I won’t continue that path. Let’s restart and clean out the ARToolKit5 assets and import ARToolKit6 into an ARToolKit5 free project.

Remove ARToolKit5 and start over

To clean everything out we remove:

ARToolKit5-Unity directory
Everything inside Plugins

One warning at this point: Any changes to the original ARToolKit5 scripts will be lost after that!

I won’t remove the linkage of the scripts to the GameObjects at the moment. Just because I’d like to see where I had ARToolKit5 scripts attached to. I get some errors as well, but that is expected as I have references to ARToolKit5 scripts from my own scripts. Now let us import the ARToolKit6 plugin again.

2nd try to import ARToolKit6

That looks much better now. ARToolKit6 is going to be imported into a dedicated ARToolKit6 directory. That will give us a clean structure.

To see if the import worked we can quickly load the 2DTrackerTest scene and run it.

Aaarg, because of the usage of ARToolKit5 components in my scripts I cannot run the test scene even if they are not used in the test scene. That is not nice of Unity3D. As a quick workaround, I simply commented out all the code in my scripts and voila, the ARToolKit6 2DTrackerTest example scene runs perfectly.

Migrate the GameObjects

Now we can start to migrate the GameObjects to the new ARToolKit6 components. I open the solarSystem.scene again and start with the ARToolKit-GameObject. As expected we get some errors regarding missing scripts:

These were the ARMarker scripts which are not used any longer in ARToolKit6. As far as I know, these can be safely removed.

While we are inside the ARToolKit-GameObject we can check-out the ARController component which has changed quite a lot. In the section 2D Tracking Options we can set how many 2DTrackables we would like to track . Here I select three (Sun, Moon and Earth).

Next is ARSceneRoot, here we miss the ARToolKit5-script that was called ARSceneRoot . From the example scenes, we can see that ARToolKit6 has nothing like an ARSceneRoot so we can simply remove that component as well.

Now the actual trackables. In my case Sun, Earth and Moon. Each of this misses the AR Tracked Object component. In ARToolKit6 this component is now called ARTrackable2D. So we can go ahead removed this missing component from the Sun, Earth and Moon GameObject and drag an ARTrackable2D onto them.

Actually, on the Earth object, we had two AR Tracked Objects that is because I handle the event when this trackable was detected in two different scripts. But ARToolKit6 handles that differently. I’ll come back to that shortly.

Select the ARTrackable for ARToolKit6

Now that all our GameObjects are changed we need to select the actual trackable for the Sun, Moon and Earth object. To make ARToolKit6 recognize our trackables we need to move them into the StreaminAssets/ARToolKit/Images directory. (Recap: In ARToolKit5 the trackables were located directly in the StreamingAssets directory.)

Now we can select the trackable image for each GameObject from the dropDown in the ARTrackable component. All pretty straight forward so far.

Additional cleanup for ARToolKit6

ARToolKit6 does provide its own ARCamera because of that we need to remove the Main Camera from the scene.

Also, we need to drag the ARStaticARCamera script onto the ARToolKit-GameObject.

Event receiver system in ARToolKit6

Looks like the last missing link is to wire up the event receiver system so that our distance scripts can get into action when a trackable is in the camera’s field of view.

Selecting the Sun GameObject we can see a field for Event Receivers we set that to 1 and press enter. Now a selection field appears that lets us choose an event receiver script. So far so good, but how do we make our scripts be ARToolKit6-EventReceiver scripts?

Looking around in the available scripts we can see that there is something called AAREventReceiver looking at the script code of that component we see that this is an abstract class. Meaning that each script that implements AAREventReceiver is considered to be an event receiver for an ARTrackable script.

Let’s try that:

Open the distanceLine.cs script and make it inherit AAREventReceiver. While doing that we also rename all ARMarker classifiers to ARTrackable.

After compiling that script I only get the warning that we hide the inherited member functions. But we can get rid of that very easy by adding override public in front of that functions.

Removed properties from ARToolKit6

Tag property

Trying to build now leads to the error ARTrackable does not contain a definition for Tag … . Which is a bit of a nutcracker as I used this Tag to identify each specific marker.

The quickest solution I could come up with for that is to add a string property to the ARTrackable script (and to the ARTrackableEditor to make it visible) called trackableTag which I’m going to use in the same fashion.

Go ahead and replace all Tag occurrences with trackableTag in the distanceLine.cs

TrackedObject

The next challenge is the ARTrackedObject which was a property of the ARMarker script in ARToolKit5 but is not available in the ARTrackable script of ARToolKit6.

It looks like that got easier to use now because we can simply remove ARTrackedObject and use transform directly.

Running the project with ARToolKit6

As everything compiles now we can go ahead and press Play to actually run the scene.

Bang: The camera does not start Unable to start AR tracking… and we get an error about a missing Optical parameters directory (Error: can’t locate StreamingAssets/ARToolKit/Optical parameters’).

The second one is an easy fix. Just create an empty StreamingAssets/ARToolKit/Optical parameters directory.

The first issue troubled me a bit because I couldn’t come up with an idea what the cause could be. Finally, I compared the ARToolKit5 project with the ARToolKit6 project. Especially the ARToolKit-GameObject. There I found that the Video Configuration is completely different from ARToolKit5 to ARToolKit6 but somehow my project kept the ARToolKit5 settings. I replaced these settings with the settings from the ARToolKit6 example project and voila everything works.

Unity Layers

ARToolKit5 used different Layers to render AR-content. That is different for ARToolKit6. Make sure that after the migration all your AR-objects are rendered to Default-Layer.

You can have a look at the Unity project on GitHub

Summary of the migration steps from ARToolKit5 to ARToolKit6

Remove ARToolKit5 assets from your project
Import ARToolKit6
Remove MainCamera and add ARStaticCamera
Rework your event receiver and user AAREventReceiver
Use ARTrackedObject instead of ARMarker
Maybe you need to add a ‘Tag’ property to ARTrackable
Fix the video configuration
Make sure your 3D models are on the ‘Default’-Layer

That is about it. Thanks for reading that far and I hope it helps. Let me know your feedback and ask any questions in the comments below.