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
![](../img/1.png)
- Change embed setting to
Embed & Sign
in the General setting tab
![](../img/2.png)
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 keyOUTGOING CONNECTIONS
needed to check the license keyCAMERA
needed to access the back-facing camera
![](../img/3.png)
- Add a
Privacy – Camera Usage Description
in info.plist
![](../img/4.png)
3. Include Track Framework
- Rename the Objective-C file extension from .m to .mm to change to C++ mode.
![](../img/5.png)
- 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.The referenced#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);
imageSequencePath
should contain: * multiple consecutive images of the same resolution and format * PNG, JPG, BMP or PGM filesThe 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