Skip to content

Basic Usage

This section describes the VIRNECT Track setup for macOS & iOS development with Xcode.

Scope

This guide describes the essential module integration and initialization of VIRNECT Track for an existing Application. For a guide on accessing the camera or visualization of tracking results, please refer to the Sample Project implementation.

1. Import Library

  • Open or create a Xcode project
  • Download the TrackFramework and extract the binaries.
  • Copy Track library into you project folder
  • Change embed setting to Embed & Sign in the General setting tab

2. Set Permissions

  • If you are targeting macOS application you need to enable the following permissions in the Signing & Capabilities setting tab.

    • INCOMING CONNECTIONS needed to check the license key
    • OUTGOING CONNECTIONS needed to check the license key
    • CAMERA needed to access the back-facing camera
  • Add a Privacy – Camera Usage Description in info.plist

3. Include Track Framework

  • Rename the Objective-C file extension from .m to .mm to change to C++ mode.
  • Import and instantiate the Track Framework with the following statements:
#import <VARAPI/TrackingFramework/TrackingFramework.hpp>

@property (nonatomic) VIRNECT::TrackingFramework* mTrackingFramework;

4. Register the License Key

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

// Set license key
VIRNECT::LICENSE::setLicenseKey(licenseKey)

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

Internet access required

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

5. Configure the Framework

  • Trained Target File:
    Download or train one or multiple trackable targets. See Section Target Trainer for more detail.

    Place the target files in a designated targets folder in your project: 

    // Setup Target configuration for framework
std::string rootPath = [[[NSBundle mainBundle] resourcePath] UTF8String];
self.mTrackingFramework->setTargetDataPath(rootPath + "/TargetResources");

    To specify which targets should be tracked, use the designated Target name without the TRACK_ prefix: 

    // Setup Target configuration for framework
self.mTrackingFramework->setTargetNames({"VARIMG_000","VARQR_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
self.mTrackingFramework->setCameraCalibration(cameraCalibration);

    Alternatively you can use the convenient Calibration Reader Tool to load the camera calibration values from a JSON file or you can fetch intrinsic parameter from your device using codes.

6. Initialize the Framework

// Initialize Track framework
bool isInitialized = self.mTrackingFramework->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.

7. Setup Image Source

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

You can choose between three different image sources:

  • Internal Camera:
    To use a internal camera as an image source please refer to Sample project's code

  • Image Sequence:
    You can use an image sequence instead of the USB camera, which is convenient during development.

    #if TARGET_OS_IPHONE
NSString* documentPath = [[[NSFileManager defaultManager] URLsForDirectory:NSDocumentDirectory
                                                         inDomains:NSUserDomainMask] lastObject].path;
#else
NSString* documentPath = @"ROOT PATH";
#endif

VIRNECT::TOOLS::activateImageSourceFileSequence(documentPath.UTF8String);
    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.

8. Run the Track framework

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

// Create custom ImageRGBA
VIRNECT::ImageRGBA image;
image.mWidth = static_cast<uint32_t>(width);
image.mHeight = static_cast<uint32_t>(height);
image.mStride = imageGray.mWidth * 4;
image.mBuffer = std::vector<uint8_t>(&baseAddress[0], &baseAddress[width * height * 4]);

self.mTrackingFramework->process(image);

self.mTrackingFramework->process();

9. Retrieve Target Results

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

auto results = self.mTrackingFramework->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
Back to top