Add 2D tracker threading support.

Author: philip-lamb

Release Notes.md

@@ -1,6 +1,11 @@
 # artoolkitX for Unity Release Notes
 ------------------------------------
 
+## Version 1.1.10
+### 2023-05-18
+
+* Support for asynchronous tracking (on a secondary thread) has been added to the 2D tracker. When enabled, the tracking rate can run slower than the video capture frame rate. This results in increased smoothness of the display of video frames, at the expense of some memory usage and a possible lag on lower-powered devices between the displayed frame and the tracking results. It has been enabled by default, and can be adjusted using the control on ARController under "2D tracking options".
+
 ## Version 1.1.9
 ### 2023-05-15
 

Source/Extras/artoolkitx

@@ -375,8 +375,12 @@ public struct ARVideoSourceInfoT
     private bool currentUseVideoBackground = true;
     [SerializeField]
     private bool currentNFTMultiMode = false;
+    [Tooltip("The max. number of markers to track simultaneously. If fewer than this number are found, then detection will run each frame, as well as tracking for any detected markers.")]
     [SerializeField]
     private int currentTwoDMaxMarkersToTrack = 1;
+    [Tooltip("If set, detection and tracking will run independently from frame capture and display on a separate thread.")]
+    [SerializeField]
+    private bool currentTwoDThreaded = true;
     [SerializeField]
     private AR_LOG_LEVEL currentLogLevel = AR_LOG_LEVEL.AR_LOG_LEVEL_INFO;
     [SerializeField]
@@ -775,6 +779,7 @@ public IEnumerator StartAR()
             ImageProcMode = currentImageProcMode;
             NFTMultiMode = currentNFTMultiMode;
             TwoDMaxMarkersToTrack = currentTwoDMaxMarkersToTrack;
+            TwoDThreaded = currentTwoDThreaded;
             SquareMatrixModeAutocreateNewTrackables = currentSquareMatrixModeAutocreateNewTrackables;
             SquareMatrixModeAutocreateNewTrackablesDefaultWidth = currentSquareMatrixModeAutocreateNewTrackablesDefaultWidth;
 
@@ -1300,6 +1305,27 @@ public bool NFTMultiMode
         }
     }
 
+    public bool TwoDThreaded
+    {
+        get
+        {
+            if (_running)
+            {
+                currentTwoDThreaded = PluginFunctions.arwGet2DThreaded();
+            }
+            return currentTwoDThreaded;
+        }
+
+        set
+        {
+            currentTwoDThreaded = value;
+            if (_running)
+            {
+                PluginFunctions.arwSet2DThreaded(currentTwoDThreaded);
+            }
+        }
+    }
+
     public int TwoDMaxMarkersToTrack
     {
         get

Source/Package/Assets/artoolkitX-Unity/Scripts/ARController.cs

@@ -67,6 +67,8 @@ public class ARControllerEditor : Editor
     protected SerializedProperty ContentFlipH;
     protected SerializedProperty NearPlane;
     protected SerializedProperty FarPlane;
+    protected SerializedProperty TwoDMaxMarkersToTrack;
+    protected SerializedProperty TwoDThreaded;
 
     private readonly static Dictionary<ARController.ARToolKitThresholdMode, string> thresholdModeDescriptions = new Dictionary<ARController.ARToolKitThresholdMode, string>
     {
@@ -92,6 +94,8 @@ protected virtual void OnEnable()
         ContentFlipH = serializedObject.FindProperty("ContentFlipH");
         NearPlane = serializedObject.FindProperty("NearPlane");
         FarPlane = serializedObject.FindProperty("FarPlane");
+        TwoDMaxMarkersToTrack = serializedObject.FindProperty("currentTwoDMaxMarkersToTrack"); ;
+        TwoDThreaded = serializedObject.FindProperty("currentTwoDThreaded"); ;
     }
 
     public override void OnInspectorGUI()
@@ -299,12 +303,8 @@ public override void OnInspectorGUI()
         show2DTrackingOptions = EditorGUILayout.Foldout(show2DTrackingOptions, "2D Tracking Options");
         if (show2DTrackingOptions)
         {
-            int n = EditorGUILayout.IntField("Max. number of markers to track", arcontroller.TwoDMaxMarkersToTrack);
-            if (n != arcontroller.TwoDMaxMarkersToTrack)
-            {
-                Undo.RecordObject(arcontroller, "Set max. number of markers to track");
-                arcontroller.TwoDMaxMarkersToTrack = n;
-            }
+            EditorGUILayout.PropertyField(TwoDMaxMarkersToTrack, new GUIContent("Max. number of markers to track"), null);
+            EditorGUILayout.PropertyField(TwoDThreaded, new GUIContent("Threaded"), null);
         }
 
         EditorGUILayout.Separator();

Source/Package/Assets/artoolkitX-Unity/Scripts/Editor/ARControllerEditor.cs

@@ -81,6 +81,8 @@ public struct ARWTrackableStatus
     abstract public bool arwGetNFTMultiMode();
     abstract public void arwSet2DMaxMarkersToTrack(int maxMarkersToTrack);
     abstract public int arwGet2DMaxMarkersToTrack();
+    abstract public bool arwGet2DThreaded();
+    abstract public void arwSet2DThreaded(bool threaded);
     abstract public int arwGetPatternDetectionMode();
     abstract public bool arwGetProjectionMatrix(float nearPlane, float farPlane, float[] matrix);
     abstract public bool arwGetProjectionMatrixStereo(float nearPlane, float farPlane, float[] matrixL, float[] matrixR);

Source/Package/Assets/artoolkitX-Unity/Scripts/IPluginFunctions.cs

@@ -73,7 +73,8 @@ public class PluginFunctionsARX : IPluginFunctions
                        /*ARW_TRACKER_OPTION_2D_TRACKER_FEATURE_TYPE = 11,*/           ///< Feature detector type used in the 2d Tracker - 0 AKAZE, 1 ORB, 2 BRISK, 3 KAZE
                        ARW_TRACKER_OPTION_2D_MAXIMUM_MARKERS_TO_TRACK = 12,           ///< Maximum number of markers able to be tracked simultaneously. Defaults to 1. Should not be set higher than the number of 2D markers loaded.
                        ARW_TRACKER_OPTION_SQUARE_MATRIX_MODE_AUTOCREATE_NEW_TRACKABLES = 13, ///< If true, when the square tracker is detecting matrix (barcode) markers, new trackables will be created for unmatched markers. Defaults to false. bool.
-                       ARW_TRACKER_OPTION_SQUARE_MATRIX_MODE_AUTOCREATE_NEW_TRACKABLES_DEFAULT_WIDTH = 14; ///< If ARW_TRACKER_OPTION_SQUARE_MATRIX_MODE_AUTOCREATE_NEW_TRACKABLES is true, this value will be used for the initial width of new trackables for unmatched markers. Defaults to 80.0f. float.
+                       ARW_TRACKER_OPTION_SQUARE_MATRIX_MODE_AUTOCREATE_NEW_TRACKABLES_DEFAULT_WIDTH = 14, ///< If ARW_TRACKER_OPTION_SQUARE_MATRIX_MODE_AUTOCREATE_NEW_TRACKABLES is true, this value will be used for the initial width of new trackables for unmatched markers. Defaults to 80.0f. float.
+                       ARW_TRACKER_OPTION_2D_THREADED = 15;                           ///< bool, If false, 2D tracking updates synchronously, and arwUpdateAR will not return until 2D tracking is complete. If true, 2D tracking updates asychronously on a secondary thread, and arwUpdateAR will not block if the track is busy. Defaults to true.
 
     override public bool IsConfigured()
     {
@@ -383,6 +384,16 @@ override public void arwSet2DMaxMarkersToTrack(int maxMarkersToTrack)
         ARX_pinvoke.arwSetTrackerOptionInt(ARW_TRACKER_OPTION_2D_MAXIMUM_MARKERS_TO_TRACK, maxMarkersToTrack);
     }
 
+    override public bool arwGet2DThreaded()
+    {
+        return ARX_pinvoke.arwGetTrackerOptionBool(ARW_TRACKER_OPTION_2D_THREADED);
+    }
+
+    override public void arwSet2DThreaded(bool threaded)
+    {
+        ARX_pinvoke.arwSetTrackerOptionBool(ARW_TRACKER_OPTION_2D_THREADED, threaded);
+    }
+
     override public int arwGet2DMaxMarkersToTrack()
     {
         return ARX_pinvoke.arwGetTrackerOptionInt(ARW_TRACKER_OPTION_2D_MAXIMUM_MARKERS_TO_TRACK);

Source/Package/Assets/artoolkitX-Unity/Scripts/PluginFunctionsARX.cs

@@ -1 +1 @@
-1.1.8
+1.1.9