Getting started with the C-API

Level: Basic

Creating a new project

Requirements

In order to use the VisionLib SDK on Windows, you need to have the Microsoft C Runtime installed. If you are using Visual Studio 2019 for C++ development, it should already be installed on your computer. Otherwise you can download a separate installer for your target architecture directly from Microsoft:

• x86 (32-Bit): vc_redist.x86.exe
• x64 (64-Bit): vc_redist.x64.exe

Setup

The VisionLib SDK can be included just like any other library:

1. Add the VisionLibSdk/include directory to the list of include directories.
2. Add the VisionLibSdk/lib directory to the list of library directories.
3. Add the vlSDK.lib to the list of dependencies.
4. Windows only: You must make sure that the included DLLs can be found. This can be achieved either by copying all DLLs from the VisionLibSdk/bin folder into the executable directory of your application or by adding VisionLibSdk/bin to the beginning of the PATH environment variable.
5. iOS only: You need to perform the following modifications to your Xcode project
   • Restrict build to only use 64-bit: arm64
   • Enable Bitcode=NO
   • Link binary with dynamic libraries
     • libxml2.dylib
     • libz.dylib
   • Link with frameworks
     • Metal.framework
     • Accelerate.framework

Usage

The following steps are necessary to start the tracking process:

1. Add

   #include <vlSDK.h>

   to your source file.
2. Create a tracking configuration file and store it somewhere where your application can access it.
3. Create the Worker (vlNew_Worker).
4. Register listeners for the tracking events (vlWorker_AddImageListener, vlWorker_AddExtrinsicDataListener, vlWorker_AddIntrinsicDataListener).
5. Start the tracking thread (vlWorker_Start).
6. Load the previously created configuration file (vlWorker_PushJsonCommand with

   "{\"name\": \"createTracker\", \"param\": {\"uri\": \"<trackingConfigFile>\"}}"

   as parameter).
7. Start the tracking (vlWorker_PushJsonCommand with

   "{\"name\":\"runTracking\"}"

   as parameter).
8. Process callbacks and retrieve events from the tracking thread (vlWorker_ProcessCallbacks, vlWorker_PollEvents, vlWorker_WaitEvents).
9. Copy the event data into your renderers data structures (vlImageWrapper_CopyToBuffer, vlExtrinsicDataWrapper_GetModelViewMatrix, vlIntrinsicDataWrapper_GetProjectionMatrix).
10. Go to step 8.

Examples

In the VisionLib.SDK-Native.zip you can find examples for the different platforms using the C-API. Currently, there are examples for iOS, MacOS, Windows, and UWP.

Windows

For Windows you can find two examples. We provide a CMakeLists.txt which can be used with CMake to generate the solutions to build the examples. One example requires OpenCV to provide a window for displaying the (debug) video stream. The other example just uses std functions but thus does not provide any visualization.

Find detailed information here: Building the Windows Examples

UWP

For UWP you can find one example. We provide a CMakeLists.txt to generate the solutions to build the example. The example can work with Assimp to load a model and display it with DirectX. This will render the model at the tracked position (contours in red: Tracking is lost, contours in green: object is tracked, contours in yellow: tracking is critical). Alternatively, you can use the example without Assimp. This will just show the debug image in which you can find the position of the model to track.

Find detailed information here: Building the UWP Example

Limitations

iOS

• Using the VisionLib SDK in the iOS simulator in Xcode does not work

Android

• No known issues. Found one? Please tell and write us at suppo.nosp@m.rt@v.nosp@m.ision.nosp@m.lib..nosp@m.com