Skip to content

Package Setup

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
Configuration Setting
Platform x64
Auto Graphics API OFF
Graphics API OpenGLCore
Scripting Backend IL2CPP
C++ Compiler Configuration Release

Unity Native Settings

Android
Configuration Setting
Auto Graphics API OFF
Graphics API OpenGLES3
Minimum API Level SDK 24 (Android 7.0)
Scripting Backend IL2CPP
C++ Compiler Configuration Release
Target Architecture ARM64
Internet Access Required​
Write Permission External (SDCard)​

Unity Android Settings

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.json to import the VIRNECT Track package.
  • Once the package.json is 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.

Warning

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

When the 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. The 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
    void Start()
    {
        string key = CustomEncryption.GetDecryptedLicenseKey();
        VIRNECT.TrackManager.SetRuntimeLicenseKey(key);
    }
}

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 .track target files in the folder Assets/StreamingAssets/trackAssets/trackTargets/
    See Section Target Trainer for more detail.

  • Camera Calibration:
    Generate a calibration file for your camera. See Section Camera Calibration for more detail. Place your calibration.json in the folder Assets/StreamingAssets/trackAssets/

    Note

    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:

  • TrackManager
    Specify the ID of the used USB camera in the field USB Camera ID of the TrackManager script.

  • Target
    Select a target name from the Target drop-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.