Merge pull request #472 from open-ephys/tait-bryan

Add TaitBryanAngles type

Author: jonnew

OpenEphys.Onix1.Design/TaitBryanAnglesVisualizer.cs

@@ -0,0 +1,32 @@
+using System;
+using Bonsai;
+using Bonsai.Design.Visualizers;
+using OpenEphys.Onix1.Design;
+
+[assembly: TypeVisualizer(typeof(TaitBryanAnglesVisualizer), Target = typeof(OpenEphys.Onix1.TaitBryanAngles))]
+
+namespace OpenEphys.Onix1.Design
+{
+    /// <summary>
+    /// Provides a type visualizer that displays a sequence of <see cref="TaitBryanAngles"/>
+    /// values as a time series.
+    /// </summary>
+    public class TaitBryanAnglesVisualizer : TimeSeriesVisualizer
+    {
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TaitBryanAnglesVisualizer"/> class.
+        /// </summary>
+        public TaitBryanAnglesVisualizer()
+            : base(numSeries: 3)
+        {
+        }
+
+        /// <inheritdoc/>
+        public override void Show(object value)
+        {
+            var v = (TaitBryanAngles)value;
+            AddValue(DateTime.Now, v.Yaw, v.Pitch, v.Roll);
+        }
+    }
+}

OpenEphys.Onix1/Bno055DataFrame.cs

@@ -40,10 +40,10 @@ internal unsafe Bno055DataFrame(ulong clock, Bno055Payload* payload)
         internal unsafe Bno055DataFrame(ulong clock, Bno055DataPayload* payload)
             : base(clock)
         {
-            EulerAngle = new Vector3(
-                x: Bno055.EulerAngleScale * payload->EulerAngle[0],
-                y: Bno055.EulerAngleScale * payload->EulerAngle[1],
-                z: Bno055.EulerAngleScale * payload->EulerAngle[2]);
+            EulerAngle = new TaitBryanAngles(
+                yaw: Bno055.EulerAngleScale * payload->EulerAngle[0],
+                pitch: Bno055.EulerAngleScale * payload->EulerAngle[1],
+                roll: Bno055.EulerAngleScale * payload->EulerAngle[2]);
             Quaternion = new Quaternion(
                 w: Bno055.QuaternionScale * payload->Quaternion[0],
                 x: Bno055.QuaternionScale * payload->Quaternion[1],
@@ -62,17 +62,16 @@ internal unsafe Bno055DataFrame(ulong clock, Bno055DataPayload* payload)
         }
 
         /// <summary>
-        /// Gets the 3D orientation in Euler angle format with units of degrees.
+        /// Gets the 3D orientation in as Euler angles using the Tait-Bryan formalism.
         /// </summary>
         /// <remarks>
-        /// The Tait-Bryan formalism is used:
         /// <list type="bullet">
         /// <item><description>Yaw: 0 to 360 degrees.</description></item>
         /// <item><description>Roll: -180 to 180 degrees</description></item>
         /// <item><description>Pitch: -90 to 90 degrees</description></item>
         /// </list>
         /// </remarks>
-        public Vector3 EulerAngle { get; }
+        public TaitBryanAngles EulerAngle { get; }
 
         /// <summary>
         /// Gets the 3D orientation represented as a Quaternion.

OpenEphys.Onix1/OpenEphys.Onix1.csproj

@@ -13,6 +13,7 @@
   <ItemGroup>
     <PackageReference Include="Bonsai.Core" Version="2.9.0" />
     <PackageReference Include="clroni" Version="6.2.0" />
+    <PackageReference Include="Microsoft.Bcl.Numerics" Version="9.0.7" />
     <PackageReference Include="OpenCV.Net" Version="3.4.2" />
     <PackageReference Include="OpenEphys.ProbeInterface.NET" Version="0.3.0" />
   </ItemGroup>

OpenEphys.Onix1/TaitBryanAngles.cs

@@ -0,0 +1,132 @@
+using System;
+using System.Numerics;
+
+namespace OpenEphys.Onix1
+{
+    /// <summary>
+    /// Represents a vector that describes the orientation of a rigid body using a set of 3 ordered rotations
+    /// about the object's principal axes. 
+    /// </summary>
+    /// <remarks>
+    /// Starting from a ENU (X: East, Y: North, Z: Up) coordinate system:
+    /// <list type="bullet">
+    /// <item><description>Yaw represents the bearing, which is the rotation about Z/Up.</description></item>
+    /// <item><description>Pitch represents the elevation, which is the rotation about Y' after application of Yaw
+    /// to the ENU coordinates.</description></item>
+    /// <item><description>Roll gives the bank angle, which is the rotation about X'' after application of Yaw and
+    /// Pitch to the the ENU coordinates.</description></item>
+    /// </list>
+    /// </remarks>
+    public struct TaitBryanAngles : IEquatable<TaitBryanAngles>
+    {
+        private Vector3 vector;
+
+        /// <summary>
+        /// Gets or sets the Yaw.
+        /// </summary>
+        /// <remarks>Yaw represents the bearing.</remarks>
+        public float Yaw
+        {
+            readonly get => vector.X;
+            set => vector.X = value;
+        }
+
+        /// <summary>
+        /// Gets or sets the Pitch.
+        /// </summary>
+        /// <remarks>Pitch represents the elevation.</remarks>
+        public float Pitch
+        {
+            readonly get => vector.Y;
+            set => vector.Y = value;
+        }
+
+        /// <summary>
+        /// Gets or sets the Roll.
+        /// </summary>
+        /// <remarks>Roll represents the bank angle.</remarks>
+        public float Roll
+        {
+            readonly get => vector.Z;
+            set => vector.Z = value;
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TaitBryanAngles"/> struct with the specified yaw, pitch,
+        /// and roll values.
+        /// </summary>
+        /// <param name="yaw">The yaw angle (bearing/rotation about Z axis).</param>
+        /// <param name="pitch">The pitch angle (elevation/rotation about Y' axis).</param>
+        /// <param name="roll">The roll angle (bank/rotation about X'' axis).</param>
+        public TaitBryanAngles(float yaw, float pitch, float roll)
+        {
+            vector = new Vector3(yaw, pitch, roll);
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TaitBryanAngles"/> struct from an existing <see
+        /// cref="Vector3"/>.
+        /// </summary>
+        /// <param name="other">The vector containing the yaw (X), pitch (Y), and roll (Z) values.</param>
+        public TaitBryanAngles(Vector3 other)
+        {
+            vector = other;
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="TaitBryanAngles"/> struct from an existing
+        /// instance.
+        /// </summary>
+        /// <param name="other">An existing TaitBryanAngles object to copy.</param>
+        public TaitBryanAngles(TaitBryanAngles other)
+        {
+            vector = other;
+        }
+
+        /// <summary>
+        /// Implicitly converts a <see cref="TaitBryanAngles"/> to a <see cref="Vector3"/>.
+        /// </summary>
+        /// <param name="euler">The Tait-Bryan angles to convert.</param>
+        /// <returns>A <see cref="Vector3"/> where X=Yaw, Y=Pitch, Z=Roll.</returns>
+        public static implicit operator Vector3(TaitBryanAngles euler) => euler.vector;
+
+        /// <summary>
+        /// Implicitly converts a <see cref="Vector3"/> to a <see cref="TaitBryanAngles"/>.
+        /// </summary>
+        /// <param name="vector">The vector to convert, where X=Yaw, Y=Pitch, Z=Roll.</param>
+        /// <returns>A <see cref="TaitBryanAngles"/> instance.</returns>
+        public static implicit operator TaitBryanAngles(Vector3 vector) => new(vector);
+
+        /// <summary>
+        /// Determines whether two <see cref="TaitBryanAngles"/> instances are equal.
+        /// </summary>
+        /// <param name="left">The first instance to compare.</param>
+        /// <param name="right">The second instance to compare.</param>
+        /// <returns><c>true</c> if the instances are equal; otherwise, <c>false</c>.</returns>
+        public static bool operator ==(TaitBryanAngles left, TaitBryanAngles right) => left.vector == right.vector;
+
+        /// <summary>
+        /// Determines whether two <see cref="TaitBryanAngles"/> instances are not equal.
+        /// </summary>
+        /// <param name="left">The first instance to compare.</param>
+        /// <param name="right">The second instance to compare.</param>
+        /// <returns><c>true</c> if the instances are not equal; otherwise, <c>false</c>.</returns>
+        public static bool operator !=(TaitBryanAngles left, TaitBryanAngles right) => left.vector != right.vector;
+
+        /// <inheritdoc cref = "Vector3.Equals(Vector3)"/>
+        public bool Equals(TaitBryanAngles other) => vector.Equals(other.vector);
+
+        /// <inheritdoc cref = "Vector3.Equals(object)"/>
+        public override bool Equals(object obj) => obj is TaitBryanAngles other && Equals(other);
+
+        /// <inheritdoc cref = "Vector3.GetHashCode"/>
+        public override int GetHashCode() => vector.GetHashCode();
+
+        /// <summary>
+        /// Returns a string that represents the current object.
+        /// </summary>
+        /// <returns>A string representation of the Tait-Bryan angles in the format "Yaw: {{Yaw}, Pitch: {Pitch},
+        /// Roll: {Roll}".</returns>
+        public override readonly string ToString() => $"Yaw: {Yaw}, Pitch: {Pitch}, Roll: {Roll}";
+    }
+}