documentation

Configuration Files
Model Tracking | Level: Basic
UnderstandingTrackingParameters_banner.jpg

Tracking Configuration Files, or short config files, are a declarative JSON files with an .vl file-ending. They are used to setup and control VisionLib tracking. The config files define the tracking technique, set parameters and sources to tell the VisionLib tracking engine how to behave:

  • they are used to set the tracking target reference (e.g. the file of a 3D model or an image)
  • to specify an input source, which can be a live video from one or multiple cameras, or an image stream
  • to define a particular starting point (initial pose) for model tracking, or to setup auto-initialisation.

Configuration Files are mandatory to setup a tracker, at least, in their minimal configuration. That said, they don't need to be physical files: it's also possible encode and load a tracking configuration from a string variable.

The files are usually stored in Unity's StreamingAssets/VisionLib/ folder. They can therefore be deployed to any mobile device as well. They are set in Unity at the VLTrackingConfiguration component (located at the VLTracking game object in the example scenes), or via the VLWorkerBehaviour component.

We clearly recommend using the VLTrackingConfiguration component, as it has convenience functions to let you toggle autostart of the tracking, quickly extend tracking with SLAM, or handle input selection – which all is handy during development.

Configuration File Parameters

In order to get a feeling on the structure and common (model) tracking parameters, have a look at the config file from the SimpleModel Tracking example, car.vl (stripped):

{
"$schema": "https://docs.visionlib.com/v20.10.1/vl.schema.json",
"tracker": {
"type": "modelTracker",
"version": 1,
"parameters": {
"modelURI": "project_dir:VLMiniCar.obj",
"metric": "m",
"initPose": {
"type": "visionlib",
"t": [0.003671, 0.014688, 0.309386 ],
"q": [ -0.279770, -0.357981, 0.886556, 0.087149 ]
},
"showLineModel": true,
"laplaceThreshold": 1,
"normalThreshold": 0.3,
"minInlierRatioInit": 0.7,
"minInlierRatioTracking": 0.6
}
}
}

Declaring Config Files

Editing config files manually is error prone, we therefore recommend using VisLab to setup config files and optimize tracking.

While you could declare a config file from scratch, we strongly recommend using our example config files as starter plates. They are part of our example scenes and are located at StreamingAssets/VisionLib/Examples.

Two steps to setup tracking: Initial & Optional Tracking Parameters

There are many parameters available to configure tracking, but typically you only come across a subset in everyday use.

As such, we can distinguish (mandatory) parameters for initial setup, which are part of the core setup and tracking parameters, which influence tracking results and -quality in particular.

While Initial Parameters need to be set each time you are going to track a new object, Optional Tracking Parameters, e.g. such as laplaceThreshold or normalThreshold, only need to be modified in few situations.

Using Tracking Reference 3D Models for Visualization

Using the same 3D files for visualization, which are used for tracking, facilitates testing the basic tracking setup in Unity, is good practice and helps finding (initial) errors quickly.

In doing so, you are basically augmenting the tracking reference of the physical object onto itself. For more details, read the section on Debugging Options.

Controlling & Manipulating Parameters

While some parameters are initialize-only, many can be manipulated at runtime. You can control the parameters API-wise, or overwrite values (in advance) by using an URI query string.

Have a look at the AdvancedModel Tracking example scene: in this scene, we not only have more than the basic VL-prefabs in appliance (see e.g. the child objects of the VLTracking game object in the Hierarchy). Here you can also see, how you would control tracking parameters at runtime; both, as a user via our demo UI elements, and as developer by the way UI and tracking components are connected in the Hierarchy.

In general, we recommend to read the Configuration file reference, which has a quite good overview and explains when and how parameters and be influenced, or set anagrammatically.

Next

› Continue reading: (Mandatory) Initial Parameters