feat(geometry): certify exact segment contacts

Author: mrdav30

src/FixedMathSharp/Geometry/Primitives/Segments/FixedSegment.cs

@@ -121,6 +121,19 @@ public FixedBoundBox Bounds
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     public Vector3d ClosestPoint(Vector3d point) => Vector3d.ClosestPointOnLineSegment(point, Start, End);
 
+    /// <summary>
+    /// Determines whether the supplied point lies exactly on this finite segment.
+    /// </summary>
+    /// <remarks>
+    /// Collinearity and finite bounds use the complete fixed-point raw domain and
+    /// do not compare a rounded closest-point projection.
+    /// </remarks>
+    public readonly bool Contains(Vector3d point)
+    {
+        Signed192 lengthSquared = GetDifferenceDot(End, Start, End, Start);
+        return PointOnSegment(point, this, lengthSquared);
+    }
+
     /// <summary>
     /// Computes the squared distance from the supplied point to this finite segment.
     /// </summary>

src/FixedMathSharp/Geometry/Primitives/Segments/FixedSegment2d.cs

@@ -398,6 +398,37 @@ public readonly bool TryGetUniqueIntersection(
         return TryGetUniqueIntersection(other, out thisParameter, out _);
     }
 
+    /// <summary>
+    /// Attempts to enclose the unique intersection parameter on this segment.
+    /// </summary>
+    /// <remarks>
+    /// The exact rational intersection is enclosed by expanding the nearest
+    /// representable parameter by one raw unit and clamping to [0, 1]. Collinear
+    /// positive-length overlaps retain the unique-intersection failure behavior.
+    /// </remarks>
+    public readonly bool TryGetUniqueIntersectionParameterEnclosure(
+        FixedSegment2d other,
+        out Fixed64 nearestParameter,
+        out Fixed64 lowerParameter,
+        out Fixed64 upperParameter)
+    {
+        if (!TryGetUniqueIntersection(other, out nearestParameter))
+        {
+            nearestParameter = default;
+            lowerParameter = default;
+            upperParameter = default;
+            return false;
+        }
+
+        lowerParameter = nearestParameter > Fixed64.Zero
+            ? Fixed64.FromRaw(nearestParameter.m_rawValue - 1L)
+            : Fixed64.Zero;
+        upperParameter = nearestParameter < Fixed64.One
+            ? Fixed64.FromRaw(nearestParameter.m_rawValue + 1L)
+            : Fixed64.One;
+        return true;
+    }
+
     /// <summary>
     /// Returns the closest finite points on this segment and another segment.
     /// </summary>

tests/FixedMathSharp.Tests/Geometry/Primitives/FixedSegment.Tests.cs

@@ -1,3 +1,4 @@
+using System;
 using System.Numerics;
 using System.Text.Json;
 using FixedMathSharp.Geometry;
@@ -8,6 +9,51 @@ namespace FixedMathSharp.Tests.Bounds;
 
 public class FixedSegmentTests
 {
+    [Fact]
+    public void Contains_UsesExactFiniteCollinearityInsteadOfRoundedProjection()
+    {
+        const long scale = 65_536L;
+        var segment = new FixedSegment(
+            Vector3d.Zero,
+            new Vector3d(
+                Fixed64.FromRaw(3L * scale),
+                Fixed64.FromRaw(2L * scale),
+                Fixed64.Zero));
+        var exactInterior = new Vector3d(
+            Fixed64.FromRaw(3L * scale / 2L),
+            Fixed64.FromRaw(scale),
+            Fixed64.Zero);
+
+        Assert.True(segment.Contains(segment.Start));
+        Assert.True(segment.Contains(exactInterior));
+        Assert.True(segment.Contains(segment.End));
+        Assert.False(segment.Contains(new Vector3d(
+            Fixed64.FromRaw(1L),
+            Fixed64.Zero,
+            Fixed64.Zero)));
+        Assert.False(segment.Contains(new Vector3d(
+            Fixed64.FromRaw(1L),
+            Fixed64.FromRaw(1L),
+            Fixed64.Zero)));
+        Assert.False(segment.Contains(new Vector3d(
+            Fixed64.FromRaw(3L * scale + 3L),
+            Fixed64.FromRaw(2L * scale + 2L),
+            Fixed64.Zero)));
+
+        var point = new FixedSegment(exactInterior, exactInterior);
+        Assert.True(point.Contains(exactInterior));
+        Assert.False(point.Contains(segment.Start));
+
+        long before = GC.GetAllocatedBytesForCurrentThread();
+        bool contains = false;
+        for (int i = 0; i < 256; i++)
+            contains = segment.Contains(exactInterior);
+        long allocated = GC.GetAllocatedBytesForCurrentThread() - before;
+
+        Assert.True(contains);
+        Assert.Equal(0, allocated);
+    }
+
     [Fact]
     public void Constructor_AssignsEndpointsAndDerivedValues()
     {

tests/FixedMathSharp.Tests/Geometry/Primitives/FixedSegment2d.Tests.cs

@@ -1,3 +1,4 @@
+using System;
 using System.Numerics;
 using System.Text.Json;
 using FixedMathSharp.Geometry;
@@ -8,6 +9,57 @@ namespace FixedMathSharp.Tests.Bounds;
 
 public class FixedSegment2dTests
 {
+    [Fact]
+    public void UniqueIntersectionEnclosure_ContainsNonrepresentableCrossingAndClampsEndpoints()
+    {
+        var horizontal = new FixedSegment2d(new Vector2d(0, 0), new Vector2d(3, 0));
+        var interior = new FixedSegment2d(new Vector2d(1, -1), new Vector2d(1, 1));
+        Assert.True(horizontal.TryGetUniqueIntersection(interior, out Fixed64 nearest));
+
+        Assert.True(horizontal.TryGetUniqueIntersectionParameterEnclosure(
+            interior,
+            out Fixed64 enclosedNearest,
+            out Fixed64 lower,
+            out Fixed64 upper));
+        Assert.Equal(nearest, enclosedNearest);
+        Assert.Equal(Fixed64.FromRaw(nearest.m_rawValue - 1L), lower);
+        Assert.Equal(Fixed64.FromRaw(nearest.m_rawValue + 1L), upper);
+        Assert.True(lower.m_rawValue * 3L <= Fixed64.One.m_rawValue);
+        Assert.True(upper.m_rawValue * 3L >= Fixed64.One.m_rawValue);
+
+        var endpoint = new FixedSegment2d(new Vector2d(0, -1), new Vector2d(0, 1));
+        Assert.True(horizontal.TryGetUniqueIntersectionParameterEnclosure(
+            endpoint,
+            out enclosedNearest,
+            out lower,
+            out upper));
+        Assert.Equal(Fixed64.Zero, enclosedNearest);
+        Assert.Equal(Fixed64.Zero, lower);
+        Assert.Equal(Fixed64.MinIncrement, upper);
+
+        var disjoint = new FixedSegment2d(new Vector2d(4, -1), new Vector2d(4, 1));
+        Assert.False(horizontal.TryGetUniqueIntersectionParameterEnclosure(
+            disjoint,
+            out _,
+            out _,
+            out _));
+
+        long before = GC.GetAllocatedBytesForCurrentThread();
+        bool intersects = false;
+        for (int i = 0; i < 256; i++)
+        {
+            intersects = horizontal.TryGetUniqueIntersectionParameterEnclosure(
+                interior,
+                out _,
+                out _,
+                out _);
+        }
+        long allocated = GC.GetAllocatedBytesForCurrentThread() - before;
+
+        Assert.True(intersects);
+        Assert.Equal(0, allocated);
+    }
+
     [Fact]
     public void Constructor_AssignsEndpointsAndDerivedValues()
     {