In order to configure and manage the tracking pipeline, VisionLib uses specific tracking configuration files. For instance, here you can set the reference to the tracking target (e.g. the file of a 3D model), control and tweak initial tracking parameters, specify an image source (which can be a live video or an image stream), or define an init pose for the model tracker. In essence, the configuration files define algorithms, parameters and sources and tell the VisionLib tracking engine what to do.
The tracking configuration file format has a .vl
extension and a similar structure as the JSON text. Including additional support for comments using //
and no support for unicode characters.
NOTE: If you plan to use .vl or .json files within your own code, beware that not all JSON parsers understand the use of comments (//
).
The following sections contain a detailed explanation of the example above.
vl-files contain a header with a file type
and a corresponding file version
:
This allows the tracking system to identify the used file format.
"VisionLibTrackerConfig" files with version 1 contain three sections:
The meta
section is completely optional, but it can be used to describe the content of the file.
The tracker
section is mandatory and describes the tracker. There will be different tracker types in the future, so the tracker section contains a header similar to the file header:
The type
contains a string with the tracker type. The version
contains a version number for the used tracker. This version number makes sure that existing tracking configurations still work the same after updating the VisionLib plugin.
The tracker
section also contains a list with parameters:
The available parameters depend on the tracker type and version:
The input
section is an optional section. It allows you to specify the source of the input images for the tracking:
Each image source in the imageSources
array has the following structure:
The available attributes for data
depend on the type
of the image source:
The example above defines three image sources:
deviceID
, position
and unit
are all optional. If no matching camera was found it will use the first available camera.scale
parameter has also been set. A value of 0.5
has the effect that the input image will get scaled down before processing. This improves the performance but reduces the precision.The useImageSource
attribute contains the name of the image source which should be used. This simplifies switching between image sources.
If the input
section is not defined, the first available camera will be used.
By default, VisionLib uses a quiet low resolution (960x540 on iPhone and 640x480 on iPad/Android devices). In order to change the resolution there is a more generic approach than just setting the resolution fixed. Please add the following lines to your .vl file in order to influence the resolution:
Possible values for resolution
are:
default
- Would be the same as removing the input section at all. (will use the above described resolutions)auto
- Will find the best resolution, which suites the performance of the device. An iPad Air 1/2 will yield in a 640x480 resolution, while devices shipping an A9 processor will use a 1024x768 resolution for example.low
- Will force the lowest resolutionmedium
- Will force not to use a low resolutionhigh
- Will use a very high resolutionIn general, we recommend to set the resolution
to auto
to preserve the transportability character of .vl
files in future. The auto
setting will be defaulted in more future versions and is preserved for unified backwards compatibility right now.
VisionLib tries to separate the image to be displayed and processed. Using high resolution camera images on devices. VisionLib might decide to downsample the image on certain processes. This leads to a more performant user experience on the costs of tracking quality. A high frame rate is usually a good compensator, on the other hand. In order to force VisionLib to NOT allow downsampling on the tracking pipeline, you can set the SmartDownsamplingDisabled
parameter to true
(by default false
) in the input section. Exceptions that do not downsample by default are loading video or image sequences, and any type of camera calibration.
All I/O accesses within VisionLib are Uniform Resource Identifier (URI) driven. URIs in the context of VisionLib SDK describe the location of a resource, which can be a directory or a file at the end of the chain. The SDK strictly relies on the URI specification RFC3986.
A URI's format is `scheme:[//[user@]authority[:port]]/path[?arguments1&arguments...][#fragment]
.
You can take advantage of the URI parameters, when you're passing a .vl
file into the initialization function of the SDK. A very common way to reference files in the tracking configuration is to use schemes.
The VisionLib-SDK defines various schemes to maintain portability of tracking configurations or configurations sets among the borders of varying systems.
You can not overwrite already internally set schemes. Those are reserved for use with VisionLib. Those schemes are:
project_dir:
Points to the directory where the original .vl
file has been loaded from.local_storage_dir:
Points to platform specific directory, where data can be stored persistently. These are:C:\\Users\\username
).C:\\Users\\USER_NAME\\AppData\\Local\\Packages\\PACKAGE_FAMILY_NAME\\LocalState
).User Folder\\LocalAppData\\APPLICATION_NAME\\LocalState
). You can access this via the Windows Device Portal (section File explorer
)./Users/username/Documents
).Application supports iTunes file sharing
(UIFileSharingEnabled
) key in your application's .plist
file.getExternalFilesDir(null)
. The directory location can differ by your phone settings, but it is application specific. Please have a look into the Android developer documentation for more information.file:
is reserved to the filesystem access.http:
is reserved for the access to sources outside the local storage using the http protocol. The usage of the http protocol for accessing files is currently not possible on UWP, which includes HoloLens. If you require this feature, please contact us.capture_dir:
Points to the Videos/Captures
directory in the Internal Storage
of the HoloLens, which can be accessed via USB. You have to enable the Videos Library
capablity for the application to grant access to this folder. On all other platforms, this file scheme points to local_storage_dir:/records
.Other schemes are to come in future releases. Support for more protocols (e.g. https and ftp) is planned.
You can define user defined schemes referring to resources in your context. You cannot redefine the system specific schemes mentioned above.
There are generally two ways of overwriting schemes using the SDK:
.vl
fileThis allows max flexibility in reconfiguring and maintaining the portability.
.vl
fileThis is an example of how to define a scheme within your .vl file.
This example defines three custom schemas. my_image_location
aliases the URL defined, while image_dir1
uses this location to resolve a path. The image input will now be a sequence of images defined in the location:http://server/path/ImageSequences/current/*.png
.
NOTE: An image sequence on a remote server might only be used for testing purposes and should be hosted on an Apache2 server with Indexes
option turned on.
.vl
URI.An other way to pass a scheme definition more generally, is through the calling URI. In our example above, the following scenario is possible:
In this example there are two schemes passed, separated by ;
. The SDK first creates aliases defined by the .vl
file and overwrites the ones defined through the URI. This allows you to refer to ‘my_image_location’ for instance (like described in the example .vl file above).
The VisionLib SDK allows you to overwrite JSON parameters when initializing with a tracking configuration. The original parameters of the .vl file are always used unless they are overwritten in the calling URI of the main file.
Parameters are passed at the end of the URI like in the following example:
scheme:/pathtovl.vl?parameter1=value¶meter2=value
You can address the keys using a dot separated notation or change values inside arrays by using brackets []
(see examples below).
You can overwrite nearly all parameters. Some useful examples are given below:
Show line model and enable extendible tracking:
Open the config file from a web server, select a specified camera and use it:
Please check the tracking configuration file section for more information on the parameters.