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 LibraryInfo
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({ "TRACK_QR_Code_000", "TRACK_IMAGE_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 callwhereVIRNECT::TOOLS::activateImageSourceUSBCamera(ID);
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.The referencedVIRNECT::TOOLS::activateImageSourceFileSequence(imageSequencePath);
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 |
|