documentation
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:
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 TrackingConfiguration component (located at the VLTracking game object in the example scenes), or via the TrackingManager component.
We clearly recommend using the TrackingConfiguration 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.
In order to get a feeling on the structure and common (model) tracking parameters, have a look at the tracking configuration file from the SimpleModel Tracking example, SimpleModelTrackingConfiguration.vl (stripped):
Editing config files manually is error prone, we therefore recommend using the tracking setup scene 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 package and are located at StreamingAssets/VisionLib/Examples.
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.
It is good practice to begin with using the same 3D files for tracking and visualization. In doing so, the exact geometry used to track the physical object is also augmented over it in the camera stream. This facilitates testing the basic tracking setup in Unity and helps quickly finding errors with the initial setup.
For more details, read the section on Debugging Options.
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 ModelTrackingSetup 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.