This section describes the VIRNECT Track package setup for the Unity game engine.
1. Project Setup
To compile and run your application with the Track framework, you must set your Unity environment to meet the platform-dependent build configuration requirements. Set the following build configurations in the player settings. Note that running the editor preview still requires you to set the PC settings, even if you are developing a mobile application.
PC - Native
|Auto Graphics API
|C++ Compiler Configuration
|Auto Graphics API
|Minimum API Level
|SDK 24 (Android 7.0)
|C++ Compiler Configuration
These build settings are automatically checked before the build starts. If any of these settings do not match, an error message will be logged and the build will stop.
2. Install Unity Package
- Download the VIRNECT Track Unity package here.
- Extract the package to your local disk and open the Unity package manager under Window | Package Manager.
- Press the
+button on the top left of the package manager and select Add package from disk....
- Navigate to the downloaded
\VIRNECT_Track\package.jsonto import the VIRNECT Track package.
- Once the
package.jsonis imported successfully, you should be able to see the screen as the below image.
3. Register the License Key
Please navigate to VIRNECT Track | Track Settings to register the license key.
This will create and open a new
track.settings object in the Resources/Track folder.
Do not move or rename the
track.settings file, since it is needed to automatically check the license key on the application start.
Input your API key in the provided field and press the "Set license key" button. This will perform a network request to check your license key.
Internet access required
The license key validation requires access to the internet. Please keep in mind that the built application also requires internet access to validate the license key.
How to improve key security
track.settingsfile is managed via version control software (e.g. git), the saved license key might be exposed.
Also, when the application is compiled without further code obfuscation, the API key may be exposed to reverse engineering attacks.
To protect your license key from being extracted, we strongly encourage you to encrypt your license key.
TrackManager provides an interface to set the unencrypted license key at runtime:
// Custom component to set License Key dynamically
public class SetLicenseKey : MonoBehaviour
// Ensure execution before TrackManager.Start() is called
string key = CustomEncryption.GetDecryptedLicenseKey();
4. Preparing Resource Files
Before starting the Track Framework, the following files need to be added:
Trained Target Files:
Download or train one or multiple trackable targets. Place your
.tracktarget files in the folder Assets/StreamingAssets/trackAssets/trackTargets/
See Section Target Trainer for more detail.
Generate a calibration file for your camera. See Section Camera Calibration for more detail. Place your
calibration.jsonin the folder Assets/StreamingAssets/trackAssets/
For mobile platforms like Android, the usage of this calibration file is not needed.
It still might be beneficial for editor testing.
5. Prepare Scene Objects
Add two prefabs from the VIRNECT Track | GameObjects menu:
Specify the ID of the used USB camera in the field
USB Camera IDof the TrackManager script.
Select a target name from the
Targetdrop-down menu of the Target script.
See Section Scene Prefabs for more details about this GameObjects.
6. Test your application
To test your scene, save your scene and press play in Unity. The built-in scene sanitizer ensures that all of the configurations above are correct before starting the PlayMode. Log messages of the Track framework will appear in the editor console.
7. Build your application
Add your scene to the build configuration. The Track framework will automatically check the build settings described in the Project Setup. If any of these settings do not match, an error message will be logged and the build is stopped.
The Track framework also performs a scene configuration sanitization. This means that all scenes registered in the build configuration will be checked for correct configuration. If any of the scenes is not configured correctly, an error message will be logged and the build is stopped.
This scene sanitization can be deactivated in the framework settings VIRNECT Track | Track Settings by deactivating the option
Perform PreBuild check for all scenes.
It is recommended to always keep this option on. Yet it can be deactivated since it might interfere with your custom build pipeline modifications.