UDP connection through stateful firewall; fixing GitHub issue #6

Author: ka-ART

CHANGELOG.md

@@ -1,6 +1,11 @@
 
 # List of ART DTRACK Plugin for Unity Game Engine releases
 
+## v1.1.3 (2024-05-03)
+
+- (Optionally) enables UDP connection through stateful firewall
+- Fixing DTrack1 parsing error (cf. GitHub issue #6)
+
 ## v1.1.2 (2023-04-01)
 
 - Some reorganization to allow release as UPM package, esp. in OpenUPM

Documentation~/images/dtrack-fingertracking-administration.png

@@ -1,6 +1,6 @@
 # ART DTRACK Plugin for Unity Game Engine 2019 or later
 
-**Version v1.1.2**
+**Version v1.1.3**
 
 This is a component for Unity 2019 or later with the purpose of
 native integration of the Advanced Realtime Tracking (ART) DTRACK
@@ -18,28 +18,30 @@ supports the DTRACK Standard Body ('6d'), Flystick ('6df2') and Fingertracking (
 
 ## Features <a name="features"></a>
 
-- Validated with Unity Editors 2019.4 to 2022.3
+- Validated with Unity Editors 2019.4 to 2023.2 (but should work with any later Unity)
 - Supports DTRACK room calibration modes 'Powerwall' and 'Normal'
 - Supports tracking of 6DOF Standard Bodies and Flystick2, Flystick2+ and Flystick3
 - Supports Flystick buttons and joystick/trigger (emitting Unity events)
 - Supports Fingertracking, with 'Leap Motion Realistic Male/Female Hands' (by Storkplay)
+- (Optionally) enables UDP connection through stateful firewall
 
 ## Installing the ART DTRACK Plugin <a name="installing"></a>
 
 There are several ways to get the ART DTRACK Plugin.
 
-### GitHub <a name="github"></a>
+### Unity Asset Store <a name="assetstore"></a>
 
-You can download a ready-to-use custom Unity package ( UnityDTrackPlugin-vX.X.X.unitypackage ) at<br>
-[https://github.com/ar-tracking/UnityDTrackPlugin/releases](https://github.com/ar-tracking/UnityDTrackPlugin/releases).
+The plugin is available (for free) in the Unity Asset Store 
+[https://assetstore.unity.com/packages/tools/integration/art-dtrack-plugin-246990](https://assetstore.unity.com/packages/tools/integration/art-dtrack-plugin-246990).
 
-In order to install the package, follow the steps below.
+After 'purchasing' you can install it via the Unity Package Manager:
 
 1. Launch Unity Hub
 - Create/Open Unity project
-- Import package ( *Assets* &rarr; *Import Package...* &rarr; *Custom Package...* )
+- Open Package Manager ( *Window* &rarr; *Package Manager* &rarr; *Packages: My Assets* )
+- Download the package (button *Download* ), then install it (button *Install* )
 
-The plugin will be installed in your project's assets folder:<br>
+The plugin will be installed in your project's Assets folder:<br>
 /path/to/unity/projects/*MyUnityProject*/**Assets/ARTDTrackPlugin**/ .
 
 ### OpenUPM <a name="openupm"></a>
@@ -51,6 +53,7 @@ The ART DTRACK plugin is available (for free) via
 To install it, follow the instructions mentioned at the above website; roughly:
 
 1. Launch Unity Hub
+- Create/Open Unity project
 - Open *Edit* &rarr; *Project Settings...* &rarr; *Package Manager*
 - Add a new Scoped Registry (corresponding to the above OpenUPM link), then click *Save* or *Apply*
 - Open Package Manager ( *Window* &rarr; *Package Manager* &rarr; *Packages: My Registries* )
@@ -59,6 +62,20 @@ To install it, follow the instructions mentioned at the above website; roughly:
 The plugin will be installed in your project's Packages folder:<br>
 /path/to/unity/projects/*MyUnityProject*/**Packages/ART DTRACK Plugin**/ .
 
+### GitHub <a name="github"></a>
+
+You can download a ready-to-use custom Unity package ( UnityDTrackPlugin-vX.X.X.unitypackage ) at<br>
+[https://github.com/ar-tracking/UnityDTrackPlugin/releases](https://github.com/ar-tracking/UnityDTrackPlugin/releases).
+
+In order to install the package, follow the steps below.
+
+1. Launch Unity Hub
+- Create/Open Unity project
+- Import package ( *Assets* &rarr; *Import Package...* &rarr; *Custom Package...* )
+
+The plugin will be installed in your project's Assets folder:<br>
+/path/to/unity/projects/*MyUnityProject*/**Assets/ARTDTrackPlugin**/ .
+
 ### Plain Sources <a name="plainsources"></a>
 
 You can download or clone sources for this plugin at
@@ -203,6 +220,14 @@ this prefix must be removed.
 <br>
 
 
+### Fingertracking <a name="dtrackfingertracking"></a>
+
+When configuring ART Fingertracking hand devices with 3 thimbles, be sure to activate the _Simulate 5 fingers_ setting.
+
+![Figure: DTRACK3 Fingertracking administration dialog](Documentation~/images/dtrack-fingertracking-administration.png)
+<br>
+
+
 ## Plugin Configuration <a name="pluginconfiguration"></a>
 
 Streaming position, rotation and button events data from DTRACK
@@ -214,6 +239,9 @@ it a name, e.g. **DTrackSource**. To this object attach the
 
 - Set *Listen Port* number matching the
   setting for DTRACK (see section [**Setting Outputs**](#dtracksettingoutputs))
+- Optionally set *Controller Host* with hostname or IP address of your ART Controller, if there is a
+  'stateful firewall' installed between Controller and Unity; normally that's sufficient to pass UDP packets
+  with tracking data to the plugin
 - Set *DTrack Coordinates* matching the calibration mode used in DTRACK
   (see section [**Room Calibration**](#dtrackroomcalibration))
 

Documentation~/images/unity-dtrack-source.png

@@ -0,0 +1,56 @@
+/* DTrackSDK in C#: DTrackMeaTool.cs
+ * 
+ * Data object containing DTRACK output data of one Measurement Tool.
+ * 
+ * Copyright (c) 2024 Advanced Realtime Tracking GmbH & Co. KG
+ * 
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ * 
+ * 1. Redistributions of source code must retain the above copyright
+ *    notice, this list of conditions and the following disclaimer.
+ * 2. Redistributions in binary form must reproduce the above copyright
+ *    notice, this list of conditions and the following disclaimer in the
+ *    documentation and/or other materials provided with the distribution.
+ * 3. Neither the name of copyright holder nor the names of its contributors
+ *    may be used to endorse or promote products derived from this software
+ *    without specific prior written permission.
+ * 
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+ * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ */
+
+using DTrackSDK.Interfaces;
+
+namespace DTrackSDK
+{
+
+
+public class DTrackMeaTool : DTrackBody
+{
+	public float TipRadius  { get; }
+	public int NumButtons  { get; }
+	public bool[] Buttons  { get; }
+
+	public DTrackMeaTool( int id, float quality, float sx, float sy, float sz,
+	                       float r0, float r1, float r2, float r3, float r4, float r5, float r6, float r7, float r8,
+	                       float tipradius, bool[] buttons, int numButtons )
+			: base( id, quality, sx, sy, sz, r0, r1, r2 ,r3, r4, r5, r6, r7, r8 )
+	{
+		this.TipRadius = tipradius;
+		this.NumButtons = numButtons;
+		this.Buttons = buttons;
+	}
+}
+
+
+}  // namespace DTrackSDK
+

README.md

@@ -2,7 +2,7 @@
  * 
  * Data object containing DTRACK output data of one frame.
  *
- * Copyright (c) 2019-2022 Advanced Realtime Tracking GmbH & Co. KG
+ * Copyright (c) 2019-2024 Advanced Realtime Tracking GmbH & Co. KG
  * 
  * Redistribution and use in source and binary forms, with or without
  * modification, are permitted provided that the following conditions are met:
@@ -39,21 +39,88 @@ public class Frame
 	// frame counter, timestamp
 	public uint FrameCounter  { get; set; }
 	public double TimeStamp  { get; set; }
+	public uint TimeStampSec  { get; set; }
+	public uint TimeStampUsec  { get; set; }
+	public uint LatencyUsec  { get; set; }
 
 	// Standard Bodies
 	public Dictionary< int, DTrackBody > Bodies  { get; set; }
+	public int NumBodies  { get; set; }  // number of calibrated Standard Bodies (as far as known)
 
 	// Flysticks
 	public Dictionary< int, DTrackFlystick > Flysticks  { get; set; }
+	public int NumFlysticks  { get; set; }  // number of calibrated Flysticks
+
+	// Measurement Tools
+	public Dictionary< int, DTrackMeaTool > MeaTools  { get; set; }
+	public int NumMeaTools  { get; set; }  // number of calibrated Measurement Tools
 
 	// Fingertracking hands
 	public Dictionary< int, DTrackHand > Hands  { get; set; }
+	public int NumHands  { get; set; }  // number of calibrated Fingertracking hands (as far as known)
 
 
 	public Frame()
 	{
 		this.FrameCounter = 0;
 		this.TimeStamp = -1.0;
+		this.TimeStampSec = 0;
+		this.TimeStampUsec = 0;
+		this.LatencyUsec = 0;
+
+		this.NumBodies = 0;
+		this.NumFlysticks = 0;
+		this.NumMeaTools = 0;
+		this.NumHands = 0;
+	}
+
+
+	// Get Standard Body data.
+
+	public DTrackBody GetBody( int id )
+	{
+		if ( this.Bodies == null )  return null;
+
+		DTrackBody body;
+		if ( this.Bodies.TryGetValue( id, out body ) )  return body;
+
+		return null;
+	}
+
+	// Get Flystick data.
+
+	public DTrackFlystick GetFlystick( int id )
+	{
+		if ( this.Flysticks == null )  return null;
+
+		DTrackFlystick flystick;
+		if ( this.Flysticks.TryGetValue( id, out flystick ) )  return flystick;
+
+		return null;
+	}
+
+	// Get Measurement Tool data.
+
+	public DTrackMeaTool GetMeaTool( int id )
+	{
+		if ( this.MeaTools == null )  return null;
+
+		DTrackMeaTool meatool;
+		if ( this.MeaTools.TryGetValue( id, out meatool ) )  return meatool;
+
+		return null;
+	}
+
+	// Get Fingertracking hand data.
+
+	public DTrackHand GetHand( int id )
+	{
+		if ( this.Hands == null )  return null;
+
+		DTrackHand hand;
+		if ( this.Hands.TryGetValue( id, out hand ) )  return hand;
+
+		return null;
 	}
 }