Command Reference

Json commands

For controlling the behaviour of VisionLib during runtime, we provide a variety of different commands. Some commands can be used in every pipeline, others depend on the used tracker. The commands are expressed in json and have the following structure:

{
    "name": "COMMAND_NAME",
    "param": 
    {
        LIST_OF_PARAMETER
    }
}

To send such a command one has to call the vlWorker_PushJsonCommand function. Apart from the command string, this function receives a worker object and optionally a callback function and a pointer to client data. This callback function will be called after the command has been processed. The client data will be propagated to this callback together with a possible result or error string (see vlCallbackJsonString).

Commands are usually not executed immediately after calling the vlWorker_PushJsonCommand function since they interact with a background thread. They will be executed after the processing of the current image has been finished. To trigger the callbacks one has to call the vlWorker_ProcessCallbacks function. This way, executing the callbacks will be done in the same thread that calls vlWorker_ProcessCallbacks and thus there should be no need for thread save implementations.

If a command fails, the callback will called with an error string. The error string has the following form:

{
    "name": string,
    "errorCode": int,
    "info": string
    "message": string
}

The name is the command name given in the command json string. The errorCode has a value from Initialization Issues. Depending on this errorCode the meaning of the info string may differ. Additional details in english may be provided via the message string.

The following commands can be executed in every pipeline:

CommandName	Parameter	Result
createTracker	{ "uri": string }	{ "trackerType": string, "deviceType": string, "warnings": { "issues": Issue[] } }
	The createTracker command resets the current state of VisionLib and loads a new Tracking Configuration (see Configuration File Reference) from the specified .vl file. You can overwrite parameters inside the tracking-configuration by adding them after the URI as query string.
createTrackerFromString	{ "str": string, "fakeFilename": string }	{ "trackerType": string, "deviceType": string, "warnings": { "issues": Issue[] } }
	The createTrackerFromString command resets the current state of VisionLib and loads a new Tracking Configuration (see Configuration File Reference) which is given in the str parameter. The fakeFilename parameter should be set to a potentially non-existing file name ending in .vl inside the folder you want to specify as project-dir.
setTargetFPS	{ "targetFPS": int }	None
	The setTargetFPS command sets the target number of frames per seconds of the tracking thread.
setDeviceOrientation	{ "mode": int(0-3) }	None
	The setDeviceOrientation specifies how the image is rotated. This is especially important when using AutoInit. The possible values are: 0: Landscape left (default) 1: Portrait Upside down 2: Landscape right 3: Portrait
runTracking	None	None
	The runTracking command activates the tracking. This command only works, if a tracker is loaded.
runTrackingOnce	None	None
	The runTrackingOnce command activates the tracking for a single frame. This command only works, if a tracker is loaded.
pauseTracking	None	None
	The pauseTracking command deactivates the tracking. This command only works, if a tracker is loaded.
getAttribute	{ "att": string }	{ "value": string, "param": string, }
	The getAttribute command returns a key-value pair of the requested attribute. The param element of the result is the same as the att element of the parameters. This command only works, if a tracker is loaded and the tracker provides the requested attribute.
setAttribute	{ "att": string, "value": string }	None
	The setAttribute command sets the specified attribute to the given value. This command only works, if a tracker is loaded and the tracker provides the requested attribute.

Some commands are only available with specific trackers:

• Model Tracker Command Reference
• Multi Model Tracker Command Reference
• Poster Tracker Command Reference
• Image Recorder Command Reference
• Camera Calibration Command Reference
• UEye Device Command Reference

JsonAndBinary commands

In addition to the commands which are only based on json strings, there are some commands, which consume or return binary data in addition to a json string. The json part of the command has the same structure as the Json commands.

To send such a command one has to call the vlWorker_PushJsonAndBinaryCommand function. Apart from the command string, this function receives a worker object, a const char* containing the binary data, the size of the data and optionally a callback function and a pointer to client data. For some commands, the binary data is expected to be 0. The purpose of these commands is to return binary data in the callback. This callback function will be called after the command has been processed. The client data will be propagated to this callback together with a possible result or error string and binary return data together with the size of the data (see vlCallbackJsonAndBinaryString).

As for json commands, these commands are also not executed immediately after calling the vlWorker_PushJsonAndBinaryCommand function since they interact with a background thread.

There are no general jsonAndBinary commands, which can be executed without a pipeline. They require a loaded tracking configuration of a specific type. Currently only the setGlobalCoordinateSystem can be performed in every pipeline but only on HoloLens if the camera is used.

CommandName	Parameter	BinaryData	Result
setGlobalCoordinateSystem	None	Windows::Perception::Spatial::ISpatialCoordinateSystem^	None
	The setGlobalCoordinateSystem command sets the spatial coordinate system of the HoloLens inside VisionLib. It requires a Windows::Perception::Spatial::ISpatialCoordinateSystem^. This command can only be performed on HoloLens.

Additionally, only the ModelTracker (and the MultiModelTracker which propagates these commands to its anchors) have JsonAndBinary commands:

• Model Tracker Command Reference
• Multi Model Tracker Command Reference