Basic Usage

This section describes the general usage of VIRNECT Track for C++ development.

Scope

This guide describes setup instructions to retrieve the raw tracking data of VIRNECT Track.
It does not cover the visualization of such tracking results on an application level.

1. Project Setup

Open or create a C++ project in the IDE of your choice
Download our static library and extract the binaries to your project folder
Reference the \include\ folder and link the Library

Info

For Windows platforms, you need to choose dynamic linking of run-time libraries (Multi-threaded DLL (/MD)) for your project.

After setting up the project configuration, VIRNECT Track can be imported and instantiated with the following statements:

#include <VARAPI/TrackingFramework/TrackingFramework.hpp>

// Instantiate tracking framework
VIRNECT::TrackingFramework trackingFramework;

2. Registering the License Key

To enable usage of the Track framework, your License Key needs to be registered first:

// Register license key
VIRNECT::LICENSE::setLicenseKey(licenseKey);

Calling this method will perform a network request to check the validity of your key.

Info

Your application always needs internet access to validate the license key before running the VIRNECT Track framework.

3. Configure the Framework

To configure the Track framework for your application, several parameters need to be defined:

Trained Target File:
Download or train one or multiple trackable targets. See Section Target Trainer for more detail. Place your targets in a designated targets folder that will only contain target files. Set the path to this directory by calling the following method:
```
// Reference the folder containing all targets
trackingFramework.setTargetDataPath(targetDataPath);
```
You also need to specify which targets you want to use. Use the designated Target name without the .track extension:
```
// Specify targets to track
trackingFramework.setTargetNames({ "VARQR_000", "VARIMG_000" });
```
Camera Calibration:
Specify the intrinsic camera parameters for your specific camera. See Section Camera Calibration for more details about generating the intrinsic camera parameters.

Instantiate a VIRNECT::CameraCalibration object and set the intrinsic calibration values. Then pass the object to the framework:
```
// Instantiate camera calibration object
VIRNECT::CameraCalibration cameraCalibration;

// Apply values
cameraCalibration.mFocalLength[0] = ... ;
...

// Set camera calibration
trackingFramework.setCameraCalibration(cameraCalibration);
```
Alternatively, use the convenient Calibration Reader Tool to load the camera calibration values from a JSON file.

4. Initialize the Framework

After setting up the configuration, the framework can be initialized:

// Initialize Track framework
bool success = trackingFramework.initialize();

The initialize function will return the result of the initialization process. If the initialization returns false, the reason can be determined by retrieving the framework log messages.

5. Setup Image Source

After successful initialization, the image source for the Track framework needs to be set.

You can choose between three different image sources:

USB Camera:
To activate the USB camera, just call
```
VIRNECT::TOOLS::activateImageSourceUSBCamera(ID);
```
where ID is the ID of your USB camera. (e.g. 0,1,2)
Image Sequence:
You can use an image sequence instead of the USB camera, which is convenient during development.
```
VIRNECT::TOOLS::activateImageSourceFileSequence(imageSequencePath);
```
The referenced imageSequencePath should contain:
- multiple consecutive images of the same resolution and format
- PNG, JPG, BMP or PGM files
The Track framework can also be used to record such image sequences.
Custom Source:
You can also use your own image source as described in section Custom Image Source

6. Run the Track framework

The program can now be executed with the Track framework. Once the USB Camera or the Image Sequence have been activated, call the process function:

// Process one frame of the previously set image source
bool success = trackingFramework.process();

The result of the process function will indicate the success or failure of processing the image.

7. Retrieve Tracking Results

The latest tracking results are represented as VIRNECT::ObjectTrackResult and can be retrieved by calling:

auto results = trackingFramework.getTrackingResult()

The tracking result for one target contains:

target name
type of target
tracking status
position as a three-dimensional vector, relative to the camera
rotation as a 3x3 matrix, relative to the camera
frame ID of this result

8. Timing

The processing flow of the Track framework is designed to be in sync with the camera frame rate. By calling the process function, the camera frame is fetched and processed. After processing, the tracking results of this frame are fetched by calling the getTrackingResult function. Since the framework uses asynchronous multi-threading internally, you must not call the process function too fast consecutively. Of course, the maximum speed depends on the hardware used.

Attention

Recommended speed:
    30 FPS
Maximum speed:
    60 - 100 FPS on workstations
    30 - 60 FPS on mobile devices
Note:
    If the frame rate exceeds the processing capabilities of the hardware, tracking may be unstable or fail.

Minimal Working Example

// by VIRNECT CO., LTD.

#include <VARAPI/TrackingFramework/TrackingFramework.hpp>
#include <VARAPI/TrackingFramework/Tools.hpp>
#include <iostream>

int32_t main(int argc, char* argv[])
{
    // Register license key
    VIRNECT::LICENSE::setLicenseKey(licenseKey);

    // Instantiate Track framework
    VIRNECT::TrackingFramework trackingFramework;

    // Setup framework configuration
    trackingFramework.setTargetDataPath(targetDataPath);
    trackingFramework.setTargetNames({ "VARQR_000", "VARIMG_000" });

    // Load camera calibration
    VIRNECT::CameraCalibration cameraCalibration;
    VIRNECT::TOOLS::readCalibrationFile(calibrationFilePath, cameraCalibration);
    trackingFramework.setCameraCalibration(cameraCalibration);

    // Initialize Track framework
    trackingFramework.initialize();

    // Activate ImageSource
    VIRNECT::TOOLS::activateImageSourceUSBCamera(0);

    // Run
    bool processFrames = true;
    while (processFrames)
    {
        processFrames = trackingFramework.process();
        auto results = trackingFramework.getTrackingResult();    

        // TrackingStateNames contains a human readable representation of the Tracking state
        std::cout << "Tracking Status: " << VIRNECT::TrackingStateNames[int32_t(results["VARIMG_000"].mStatus)];

        // Keep a constant frame rate ~30FPS
        std::this_thread::sleep_for(std::chrono::milliseconds(33));
    }

    // Stop Track framework
    trackingFramework.stop();
}