In the vlSDK and vlUnitySDK, file references can be passed to VisionLib via URIs. E.g. when passing a tracking configuration as a parameter for the VLWorkerBehaviour.StartTracking function of the vlUnitySDK or when referencing a file in the VLTrackingConfiguration component. Also, a common way to reference files in the tracking configuration is to use schemes, e.g. "modelURI": "project-dir:VLMiniCar.obj".

This pages gives an overview on how VisionLib can use URIs with schemes.

General: URIs and Schemes in VisionLib

All file accesses within VisionLib are Uniform Resource Identifier (URI) driven. URIs in the context of the VisionLib SDK describe the location of a resource, which can be a directory or a file. The SDK relies on the URI specification (RFC3986).

An URI's format is scheme:[//authority]path[?query][#fragment] (components in [ ] are optional). VisionLib uses the following format for queries: query = key0[=value0][&key1[=value1]&...]

Integrated Schemes

VisionLib defines various schemes to maintain the portability of tracking configurations among varying operating systems.

Those schemes are:

General

project-dir: Points to the directory where the original .vl file has been loaded from and is therefore only available while a tracking configuration is loaded.
local-storage-dir: Points to a platform specific directory, where data can be stored persistently.
- Windows: Current user's home directory (e.g. C:\Users\username).
- UWP: The application's local directory in the user folder (C:\\Users\\USER_NAME\\AppData\\Local\\Packages\\PACKAGE_FAMILY_NAME\\LocalState).
- HoloLens: The application's local directory (User Folder\\LocalAppData\\APPLICATION_NAME\\LocalState). You can access this via the Windows Device Portal (section File explorer).
- MacOS: Current user's document directory (e.g. /Users/username/Documents).
- iOS: The application's document directory. If you want to access the files through iTunes or any other tool, you must set the Application supports iTunes file sharing (UIFileSharingEnabled) key in your application's .plist file.
- Android: The application uses 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.
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 capability for the application to grant access to this folder. On all other platforms, this file scheme points to local-storage-dir:/records.
http: Allows access to resources 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.
file: Allows to reference files and directories in the local file system.
data: Allows to embed arbitrary data into an URI. For example, you could specify the camera calibration without an external file. More details can be found here.

More schemes might be added in future releases. Support for more protocols (e.g. HTTPS) is planned.

Unity Specific

streaming-assets-dir: Points to the location of the StreamingAssets folder, which is used by Unity to store assets that need to be accessed after deploying the application.

Advanced: Custom Schemes

You can define custom schemes and use them as symbolic links to your own directory structures. You cannot redefine the internal schemes mentioned above.

There are three ways of defining schemes using the SDK:

Call the vlSDKUtil_registerScheme function
Define it in the tracking configuration
Define it within the tracking configuration URI

Define Schemes using the `vlSDKUtil_registerScheme` function

One way to create a new scheme is to use the vlSDKUtil_registerScheme function. This function tries to register a new scheme relative to a given URI with the given name. The URI can be an absolute path or contain another scheme (e.g. http://192.0.0.1/file). If a scheme with this name already exists, this command will overwrite the old scheme.

For example, after registering the following scheme:

vlSDKUtil_registerScheme("models", "file:///C:/Users/Username/Models");

it will be possible to use it wherever an URI is required (e.g. models:cars/car.obj).

In Unity, you can use the corresponding VLUnitySdk.RegisterScheme(string name, string uri) function.

Define Schemes in the Tracking Configuration

This is an example of how to define a scheme within your tracking configuration.

{
    "type": "VisionLibTrackerConfig",
    "version": 1,
    "meta": {...},
    "tracker":{...},
    "schemes":{
        "my-image-location": "http://server/path",
        "image-dir1": "my-image-location:/ImageSequences/current/"
        "image-dir2": "project-dir:/ImageSequences/record_2/"
    },
    "input": {
        "useImageSource": "imageSequence",
        "imageSources": [{
            "name": "imageSequence",
            "type": "imageSequence",
            "data": {
                "deviceID": "SurfacePro4",
                "uri": "image-dir1:/*.png"
            }
        }]
    }
}

This example defines three custom schemes. my-image-location references an HTTP address, while image-dir1 indirectly refers to this address. The custom scheme image-dir2 refers to the integrated project-dir location instead. This tracking configuration now uses a sequence of png image files as input, which reside in http://server/path/ImageSequences/current/.

Note:: An image sequence on a remote server can be useful for testing purposes. Currently this might only work correctly, if hosted on an Apache2 server with Indexes option turned on.

Defining Schemes through the Tracking Configuration URI

An other way to define a scheme, is through the tracking configuration URI.

http://mySever/path/myCoolTrackingConfig.vl?schemes.image-dir1=project-dir:/ImageSequences/record_2/&schemes.image-dir2=my-image-location:/other/dir

Schemes defined via the tracking configuration URI take precedence over schemes defined inside the tracking configuration. All schemes are registered globally, which means, that it's possible to use URI-defined schemes in the tracking configuration and vice versa. This allows you for instance to refer to my-image-location via an URI.

documentation