Level: Intermediate

Debugging Augmented- and Mixed Reality projects with VisionLib can include several levels, such as checking errors in the configuration file setup, troubleshoot runtime issues related to scripting, or debugging and tweaking of the tracking results. As such, debugging, troubleshooting and optimization can involve:

to check the basic setup of the tracking configuration
to check and assess the tracking quality,
to assess the suitability of a 3D file as reference for Model Tracking,
to check, whether the Line Model of a given 3D files is working as desired and delivers good tracking results.
to modify or tweak several Tracking Parameters and immediately check the results

Useful Configuration File Parameters for Debugging

For any debugging related to the tracking, make sure to set these parameters in the configuration file:

Name	Description	Examples
debugLevel	Parameter to enable debug functionality. Should be declared and set to ´1´	`"debugLevel": 1`
showLineModel	Parameter to render and display the Line Model.	`"showLineModel": true`

Using debugLevel you're able to access the debug image and display it e.g. inside your Unity project. For details to the debugLevel look it up in the detail reference.

With showLineModel you can control, whether or not VisionLib will render the line model it uses for tracking. Displaying it is very handy, when you use a pre-defined initialization pose (which is the default setup).

The line model will be displayed in different colors according to the current tracking state.

During development, the line model helps to find errors in your tracking setup, e.g. when your Tracking Parameters or the metric you've used in your configuration setup aren't appropriate to track your object.

On a UX level, listening to tracking states is a good practice and increases your app's UX, as you can either trigger custom massages and events that guide your users.

While the line model rendering is primarily designed for debugging purposes, you can also use it as part of your UI and e.g. change the appearance of it, or only show it when tracking is lost by using showLineModelLost instead of showLineModel, and you can change the line model's color (there is a brief how-to on this in the tracking states article).

Testing the Debugging Options

You can explore and test all mentioned options using VisionLib's do-it-yourself tracking target kit. With it, you can create a physical 3D object from paper and download a corresponding 3D model as tracking reference.

Debugging with VisLab

In general, we recommend to use VisLab for the debugging of tracking objectives. It helps finding errors in the configuration files, enables to tweak essential tracking parameters in real-time, and is a good tool to quickly track custom objects and test their suitability for model tracking.

For a quick test use the do-it-yourself target, run the tool on your desktop, connect a USB or use the built-in camera (if available) and reference your license file:

Download the do-it-yourself target and the corresponding 3D file, then print & build the papercraft car. * Select Model Tracking from the Splash screen.
Next, select a camera input from the left panel.
Drop the tracking reference 3D file onto the canvas, or press the "Plus" button at the Target panel.
In Pipeline Settings, check Expert Mode and select the Debug option.
The RGB image will turn into a grey image.
If you haven't done yet, press the "Start" button in right panel and point your camera at the do-it-yourself test target to track it.
Note, how the line model rendering turns from red to green after the object has been tracked successfully.
Next, start to modifying some of the [tracking parameters](vlUnitySDK_Article_UnderstandingTrackingParams) that influence the tracking, such as the normal or laPlace threshold.
- modify the normalThreshold: slide it slowly all the way up from its default 0.3 to see how the Line Model changes accordingly.
- next, slide up the laplaceThreshold and slide it slowly all the way up from its default 1.0.
- as a result, you should now see a thinned-out Line Model with only outline-like lines around our demo tracking target.

Debugging in Unity

When debugging in Unity, we recommend to use the VisionLib's example scenes from the Unity SDK.

Download, print and build the do-it-yourself target.
Create a new project and import the current vlUnitySDK.
Open the AdvancedModelTracking scene and reference your license file in the VLTrackingConfiguration component on the VLTracking GameObject.
From the UI, press the "Debug" button.
You should see a gray image now and the Line Model (if not, make sure to have the debugLevel and showLineModelset in the config file as mentioned earlier).
Press the "Parameters on" button.
Next, make yourself familiar with tweaking some parameters like illustrated in the prior paragraph.

Troubleshooting the configuration file setup

When you load configuration files in Unity, VisionLib will raise issues and give hints, if errors occur. Also, watch the output on the console.

Notifications on Tracking Events & Tracking States

If you look for the VLTracking GameObject in the hierarchy of the AdvancedModelTracking example scene, you can find a VLNotifications GameObject. Here, we have three components that listen to tracking events and -states during runtime.

Since they are part of the demo UI of the scene, they will be built with your app and give helpful information, once you've deployed and run it on a mobile device:

VL Init Issue Notifications – will emit initialization-related issues like stated above.
VL Log Events Behaviour – notifies about general information on tracking events, such as whether the model tracker is initialized, started or paused.
VL Log Tracking Info Behaviour – when activated at runtime (e.g. by pressing the Debug On button in the AdvancedModelTracking scene), VisionLib will render a UI element plotting realtime information of the tracking engine, such as the tracking state or Quality.

(Debug) Scripts, Prefabs & Components from the Unity SDK

While we use the VLNotifications GameObject in all example scenes, not all of the prior mentioned components are present everywhere. In case of debuggig functionality, the AdvancedModelTracking is the most elaborate one, where you can either load and test your custom tracking configuration, or as a developer, learn how VisionLib's VL components, scripts and prefabs are connected and used.

Feel free to add these elements to your own scenes as you see fit. Please note, that if you don't want to use VisionLib's notifications in your final, release-ready, application, make sure to disable these debug components, set debugLevel: 0 and remove other development-relevant items before deployment.