Scene Prefabs

This section describes the Unity prefabs of the VIRNECT Track package. These prefabs can be added with the VIRNECT Track | GameObject menu:

TrackManager

• Scene Camera

  When the TrackManager is added, the main scene camera will be referenced automatically. Also, a TrackCamera component will be added to this main camera. If this cannot be done automatically the framework will notify you to reference the main camera manually.

• Image Source

  VIRNECT Track supports 3 different image sources:

  • Camera

    You can use a USB camera in the Unity editor or native platform applications.

    If multiple cameras are attached to your device, you can select the camera of your choice from the USB Camera ID field in the TrackManager. This field contains the camera device IDs, which refers to the index of all available cameras, starting from index 0. Note that this does not reflect the camera ID in the calibration file since the USB device order is not guaranteed to be stable. The calibration file readout will always use cam0 as a key.

    The Resolution field allows to select one of the supported input resolutions. The selected resolution must be specified in the calibration file.

    Attention

    When you build your Unity project for Android platforms, the device-embedded back-facing camera will be used.

  • File Sequence

    A file sequence can be used instead of the camera to ease development or debug your application with reproducible movements. When the file sequence is selected, the File Sequence Path needs to be provided. Optionally a calibration file can be specified that represents the intrinsic parameters of the camera used for recording the sequence.

    To record such sequences, the Recorder UI can be used.

  • External Image Source

    Any script implementing the ExternalImageSourceInterface can be specified as an image source. This allows to utilize any camera, network stream, even rendered images, as an input for the Track framework.

    Implementation Details

    The input image needs to be rendered onto a GL-texture. The GetTexturePointer() method will be called during initialization of the framework. Calling GL.IssuePluginEvent(LibraryInterface.GetPrepareExternalInputTextureEventFunc(), 0); will sync the current content of the Texture buffer with the Framework input.

    The following sample implementation shows the correct usage of the ExternalImageSourceInterface with a Unity RenderTexture.

    using System.Collections;
    using UnityEngine;
    using VIRNECT;
    
    /// <summary>
    /// This is a sample implementation to showcase the correct usage of the ExternalImageSourceInterface
    /// It utilizes a Unity RenderTexture as TRACK Framework input.
    /// In this case an in-scene camera provides the source image. Important: This must not be the main camera!
    /// This script adds a render texture to the camera component it is attached to.
    /// On Framework start, the GetTexturePointer() initializes the Texture reference.
    /// 
    /// The content of the render texture is updated in the OnPostRender() method. It calls the GetPrepareExternalInputTextureEventFunc()
    /// This method can not be invoked by the TrackManager since it needs to be called after rendering of this camera instance is done.
    /// </summary>
    [DefaultExecutionOrder(-100)]
    [RequireComponent(typeof(Camera))]
    public class ExternalImageSourceRenderTexture : MonoBehaviour, ExternalImageSourceInterface
    {
        /// <summary>
        /// Width of render texture
        /// IMPORTANT: The resolution needs to be equal to the resolution specified in the used calibration file
        /// </summary>
        const int width = 640;
    
        /// <summary>
        /// Height of render texture
        /// IMPORTANT: The resolution needs to be equal to the resolution specified in the used calibration file
        /// </summary>
        const int height = 480;
    
        /// <summary>
        /// Render texture holding the input of the framework
        /// </summary>
        RenderTexture renderTexture;
    
        /// <summary>
        /// Pointer to GL update function fetching the framework input image form the texture pointer
        /// </summary>
        System.IntPtr updateMethodPointer;
    
        /// <summary>
        /// Return the native texture pointer of the Texture which will be used as a Track-Framework input.
        /// Actual synchronization of content will happen when calling GL.IssuePluginEvent(LibraryInterface.GetPrepareExternalInputTextureEventFunc(), 0);
        /// </summary>
        /// <returns>Native texture pointer</returns>
        public System.IntPtr GetTexturePointer()
        {
            return renderTexture.GetNativeTexturePtr();
        }
    
        /// <summary>
        /// OnPostRender cycle, call GetPrepareExternalInputTextureEventFunc in order to buffer the render texture as a input texture in the native plug-in
        /// </summary>
        IEnumerator OnPostRender()
        {
            yield return new WaitForEndOfFrame();
            GL.IssuePluginEvent(updateMethodPointer, 0);
            yield return null;
        }
    
        /// <summary>
        /// Setup and connect required components
        /// </summary>
        void Start()
        {
            // Instantiate render texture
            renderTexture = new RenderTexture(width, height, 16, RenderTextureFormat.ARGB32, RenderTextureReadWrite.sRGB);
    
            // Assign texture to camera
            GetComponent<Camera>().targetTexture = renderTexture;
    
            // Get reference to update function
            updateMethodPointer = LibraryInterface.GetPrepareExternalInputTextureEventFunc();
        }
    }
    

Target

All targets that you want to track in a scene need to be referenced by a Target prefab before building the application. Targets can be added by using the Menu VIRNECT Track | GameObject | Target.

The Target prefab provides several different options:

• Target
  To associate the GameObject with a physical target you can select the appropriate target name from the Target dropdown. This list will only show targets that are present in the Assets/StreamingAssets/trackAssets/trackTargets/ folder. The selected value cannot be changed during runtime.

• Hide target visualization
  A tracked physical target is visualized with a virtual cube. The initial size of this cube is 0.1 units in unity which represents 10 cm. At runtime, this cube will represent the actual physical size of the target, which was defined during target training. Changing this option will show or hide this cube accordingly.

• Ignore target during tracking
  This option can be used to dynamically exclude targets from tracking. If there is no need to track a specific target, the computational load can be reduced by applying this option. To test the dynamic exclusion, the Active Target Manager UI can be used.

To change the standard appearance of a target, simply attach any GameObject as a child to this Target in the scene graph.

Info

Since the Track framework uses real-world scale reference, you might need to scale your GameObjects accordingly. 1 unit in Unity = 1 meter in real-world
The default target placeholder has a size of 10 by 10 cm in the editor. During runtime, it will scale according to the settings defined during target training.

Warning

Currently, the Track framework does not support the dynamic spawning of Target GameObjects. Dynamic loading of sub-scenes will only work correctly if all Track related GameObjects are present in one scene.