feat(vector3d): add SnapSmallComponentsToZero and improve epsilon-based vector guards

Author: mrdav30

src/FixedMathSharp/Numerics/Extensions/Fixed64.Extensions.cs

@@ -236,7 +236,7 @@ public static bool FuzzyComponentEqual(this Fixed64 a, Fixed64 b, Fixed64 percen
             var allowedErr = a.Abs() * percentage;
             // Compare directly to percentage if a is zero
             // Otherwise, use percentage of a's magnitude
-            return a == Fixed64.Zero ? diff <= percentage : diff <= allowedErr;
+            return a.LessThanEpsilon() ? diff <= percentage : diff <= allowedErr;
         }
 
         #endregion

src/FixedMathSharp/Numerics/Vector2d.cs

@@ -652,7 +652,7 @@ public static Vector2d GetNormalized(Vector2d value)
             return new Vector2d(Fixed64.Zero, Fixed64.Zero);
 
         // If already normalized, return as-is
-        if (mag == Fixed64.One)
+        if (FixedMath.Abs(mag - Fixed64.One) <= Fixed64.Epsilon)
             return value;
 
         // Normalize it exactly
@@ -1011,7 +1011,7 @@ public bool NotZero()
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public bool AllComponentsGreaterThanEpsilon()
     {
-        return x > Fixed64.Epsilon && y > Fixed64.Epsilon;
+        return x.Abs() > Fixed64.Epsilon && y.Abs() > Fixed64.Epsilon;
     }
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]

src/FixedMathSharp/Numerics/Vector3d.cs

@@ -449,7 +449,30 @@ public bool IsNormalized()
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public bool AllComponentsGreaterThanEpsilon()
     {
-        return x > Fixed64.Epsilon && y > Fixed64.Epsilon && z > Fixed64.Epsilon;
+        return x.Abs() > Fixed64.Epsilon && y.Abs() > Fixed64.Epsilon && z.Abs() > Fixed64.Epsilon;
+    }
+
+    /// <summary>
+    /// Returns a new vector with components whose absolute values are less than the specified threshold set to zero.
+    /// </summary>
+    /// <remarks>
+    /// This method is useful for eliminating insignificant floating-point errors by zeroing out very small vector components. 
+    /// The default threshold is suitable for most cases where near-zero values are considered noise.
+    /// </remarks>
+    /// <param name="threshold">
+    /// The minimum absolute value a component must have to be retained. 
+    /// If null, a default epsilon value is used.
+    /// </param>
+    /// <returns>A new Vector3d instance with small components snapped to zero based on the specified threshold.</returns>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public Vector3d SnapSmallComponentsToZero(Fixed64? threshold = null)
+    {
+        Fixed64 effectiveThreshold = threshold ?? Fixed64.Epsilon;
+        return new Vector3d(
+            x.Abs() < effectiveThreshold ? Fixed64.Zero : x,
+            y.Abs() < effectiveThreshold ? Fixed64.Zero : y,
+            z.Abs() < effectiveThreshold ? Fixed64.Zero : z
+        );
     }
 
     /// <summary>
@@ -622,7 +645,7 @@ public static Vector3d GetNormalized(Vector3d value)
             return new Vector3d(Fixed64.Zero, Fixed64.Zero, Fixed64.Zero);
 
         // If already normalized, return as-is
-        if (mag == Fixed64.One)
+        if (FixedMath.Abs(mag - Fixed64.One) <= Fixed64.Epsilon)
             return value;
 
         // Normalize it exactly           
@@ -643,8 +666,8 @@ public static Fixed64 GetMagnitude(Vector3d vector)
     {
         Fixed64 mag = (vector.x * vector.x) + (vector.y * vector.y) + (vector.z * vector.z);
 
-        // If rounding error pushed magnitude slightly above 1, clamp it
-        if (mag > Fixed64.One && mag <= Fixed64.One + Fixed64.Epsilon)
+        // Clamp tiny drift around 1 in either direction.
+        if (FixedMath.Abs(mag - Fixed64.One) <= Fixed64.Epsilon)
             return Fixed64.One;
 
         return mag != Fixed64.Zero ? FixedMath.Sqrt(mag) : Fixed64.Zero;
@@ -817,9 +840,15 @@ public static (Vector3d, Vector3d) ClosestPointsOnTwoLines(Vector3d line1Start,
     }
 
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
-    private static (Fixed64 sc, Fixed64 tc) SolveClosestLineParameters(Fixed64 a, Fixed64 b, Fixed64 c, Fixed64 d, Fixed64 e, Fixed64 determinant)
+    private static (Fixed64 sc, Fixed64 tc) SolveClosestLineParameters(
+        Fixed64 a,
+        Fixed64 b,
+        Fixed64 c,
+        Fixed64 d,
+        Fixed64 e,
+        Fixed64 determinant)
     {
-        if (determinant < Fixed64.Epsilon)
+        if (determinant.Abs() < Fixed64.Epsilon)
             return (Fixed64.Zero, b > c ? d / b : e / c);
 
         return ((b * e - c * d) / determinant, (a * e - b * d) / determinant);
@@ -903,7 +932,7 @@ public static Fixed64 CrossProduct(Vector3d lhs, Vector3d rhs)
     public static Vector3d Project(Vector3d vector, Vector3d onNormal)
     {
         Fixed64 sqrMag = Dot(onNormal, onNormal);
-        if (sqrMag < Fixed64.Epsilon)
+        if (sqrMag.Abs() < Fixed64.Epsilon)
             return Zero;
         else
         {
@@ -923,7 +952,7 @@ public static Vector3d Project(Vector3d vector, Vector3d onNormal)
     public static Vector3d ProjectOnPlane(Vector3d vector, Vector3d planeNormal)
     {
         Fixed64 sqrMag = Dot(planeNormal, planeNormal);
-        if (sqrMag < Fixed64.Epsilon)
+        if (sqrMag.Abs() < Fixed64.Epsilon)
             return vector;
         else
         {

tests/FixedMathSharp.Tests/Vector3d.Tests.cs

@@ -111,6 +111,32 @@ public void AllComponentsGreaterThanEpsilon_ReturnsFalse_WhenAComponentIsAtOrBel
         Assert.False(vector.AllComponentsGreaterThanEpsilon());
     }
 
+    [Fact]
+    public void SnapSmallComponentsToZero_UsesDefaultEpsilonThreshold()
+    {
+        var halfEpsilon = Fixed64.FromRaw(Fixed64.Epsilon.m_rawValue / 2);
+        var vector = new Vector3d(halfEpsilon, -halfEpsilon, Fixed64.Epsilon);
+
+        var result = vector.SnapSmallComponentsToZero();
+
+        Assert.Equal(Fixed64.Zero, result.x);
+        Assert.Equal(Fixed64.Zero, result.y);
+        Assert.Equal(Fixed64.Epsilon, result.z); // Boundary: abs(z) == threshold is retained
+    }
+
+    [Fact]
+    public void SnapSmallComponentsToZero_UsesCustomThreshold_AndKeepsBoundaryValues()
+    {
+        var threshold = new Fixed64(0.1);
+        var vector = new Vector3d(new Fixed64(0.05), new Fixed64(-0.1), new Fixed64(0.2));
+
+        var result = vector.SnapSmallComponentsToZero(threshold);
+
+        Assert.Equal(Fixed64.Zero, result.x);      // abs(x) < threshold -> snapped
+        Assert.Equal(new Fixed64(-0.1), result.y); // abs(y) == threshold -> retained
+        Assert.Equal(new Fixed64(0.2), result.z);  // abs(z) > threshold -> retained
+    }
+
     #endregion
 
     #region Test: Arithmetic