Merge branch 'develop'

Author: mrdav30

docs/wiki/bounds-and-geometry.md

@@ -218,6 +218,13 @@ Choose the represented boundary carefully:
 This distinction is why the API exposes named sweep methods instead of treating
 every query as an expanded axis-aligned bound.
 
+`FixedConvexPrismRelations.IntersectsSweptUprightCylinderStrict` answers the
+joint continuous relation between a translated upright cylinder and a rotated
+vertical convex prism. It keeps one exact parameter domain for both footprint
+and height overlap, so planar tangency, vertical tangency, and intervals that
+meet only at one boundary parameter do not become false positive volume
+intersections through independently rounded roots.
+
 ## Triangles and contacts
 
 Triangles preserve vertex order. `FixedTriangle2d` exposes planar barycentric
@@ -277,6 +284,7 @@ physics-response API.
 | Swept sphere versus cylinder or box                        | `FixedSegment`                                                            |
 | Centered shape support, containment, or materialization    | `FixedSegment2d`, `FixedSegment` static helpers                           |
 | Shape support inside a world-Y layer                       | `FixedSlabProjection`                                                     |
+| Swept upright cylinder versus a vertical convex prism      | `FixedConvexPrismRelations`                                               |
 | Triangle contacts or finite-shape relations                | `FixedTriangle`                                                           |
 | Relative witnesses outside ordinary world-coordinate range | `FixedPointAnchor`, `FixedPointAnchor2d`, contact-anchor types            |
 

src/FixedMathSharp/Geometry/Primitives/Relations/FixedConvexPrismRelations.cs

@@ -16,6 +16,59 @@ namespace FixedMathSharp;
 /// </summary>
 public static class FixedConvexPrismRelations
 {
+    /// <summary>
+    /// Determines whether an upright cylinder translated between two
+    /// bottom-center points has strict positive-volume overlap with a rotated
+    /// vertical convex prism at any shared continuous parameter in [0, 1].
+    /// </summary>
+    /// <remarks>
+    /// Planar tangency, vertical tangency, and contact that exists only where
+    /// the planar and vertical strict intervals meet at one boundary parameter
+    /// return <see langword="false"/>. A zero radius requires the swept axis
+    /// point to enter the strict prism footprint. The joint parameter relation
+    /// is evaluated with exact wide intermediates and does not publish rounded
+    /// interval endpoints.
+    /// </remarks>
+    /// <param name="bottomStart">The cylinder bottom center at parameter zero.</param>
+    /// <param name="bottomEnd">The cylinder bottom center at parameter one.</param>
+    /// <param name="radius">The nonnegative cylinder radius.</param>
+    /// <param name="height">The positive full cylinder height.</param>
+    /// <param name="prismOrigin">The center of the vertical convex prism.</param>
+    /// <param name="prismRotation">The prism footprint rotation about world Y.</param>
+    /// <param name="prismLocalOffsets">At least three ordered convex-footprint offsets.</param>
+    /// <param name="prismHalfThickness">The positive prism half-thickness along world Y.</param>
+    /// <exception cref="ArgumentOutOfRangeException">
+    /// <paramref name="radius"/> is negative, <paramref name="height"/> is not
+    /// positive, or <paramref name="prismHalfThickness"/> is not positive.
+    /// </exception>
+    /// <exception cref="ArgumentException">
+    /// Fewer than three ordered prism offsets were supplied.
+    /// </exception>
+    public static bool IntersectsSweptUprightCylinderStrict(
+        Vector3d bottomStart,
+        Vector3d bottomEnd,
+        Fixed64 radius,
+        Fixed64 height,
+        Vector3d prismOrigin,
+        Fixed64 prismRotation,
+        ReadOnlySpan<Vector2d> prismLocalOffsets,
+        Fixed64 prismHalfThickness)
+    {
+        if (height <= Fixed64.Zero)
+            throw new ArgumentOutOfRangeException(nameof(height));
+        ValidatePrism(radius, prismLocalOffsets, prismHalfThickness);
+        return WideConvexPrismRelations
+            .IntersectsSweptUprightCylinderStrict(
+                bottomStart,
+                bottomEnd,
+                radius,
+                height,
+                prismOrigin,
+                prismRotation,
+                prismLocalOffsets,
+                prismHalfThickness);
+    }
+
     /// <summary>
     /// Attempts to construct canonical contact anchors between a rigidly
     /// transformed triangle and a rotated vertical convex prism.

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

@@ -120,6 +120,34 @@ public Fixed64 DistanceSquared(Vector2d point)
         return Vector2d.DistanceSquared(point, ClosestPoint(point));
     }
 
+    /// <summary>
+    /// Determines whether the exact minimum distance to another finite segment
+    /// is at least the supplied threshold.
+    /// </summary>
+    /// <remarks>
+    /// The comparison uses wide rational distances and does not materialize a
+    /// rounded closest point or square root. Equality is accepted.
+    /// </remarks>
+    /// <exception cref="ArgumentOutOfRangeException">
+    /// Thrown when <paramref name="minimumDistance"/> is negative.
+    /// </exception>
+    public readonly bool IsDistanceAtLeast(
+        FixedSegment2d other,
+        Fixed64 minimumDistance)
+    {
+        if (minimumDistance < Fixed64.Zero)
+            throw new ArgumentOutOfRangeException(nameof(minimumDistance));
+        if (minimumDistance == Fixed64.Zero)
+            return true;
+        if (TryGetUniqueIntersection(other, out _, out _))
+            return false;
+
+        return WidePlanarProjection.AreSegmentEndpointDistancesAtLeast(
+            this,
+            other,
+            minimumDistance);
+    }
+
     /// <summary>
     /// Finds the closed parameter interval where this segment intersects a capsule.
     /// </summary>
@@ -143,6 +171,41 @@ public readonly bool TryGetCapsuleIntersectionInterval(
             out entryParameter,
             out exitParameter);
 
+    /// <summary>
+    /// Finds a conservative parameter enclosure for the closed interval where
+    /// this segment intersects an endpoint-authored capsule.
+    /// </summary>
+    /// <remarks>
+    /// The exact finite-axis solve rounds its representable interval bounds to
+    /// nearest. This method expands each returned bound outward by one raw
+    /// quantum, clamped to [0, 1], so the mathematical interval is enclosed.
+    /// A zero-length capsule axis is treated as a circle.
+    /// </remarks>
+    /// <exception cref="ArgumentOutOfRangeException">
+    /// Thrown when <paramref name="radius"/> is negative.
+    /// </exception>
+    public readonly bool TryGetCapsuleIntersectionParameterEnclosure(
+        FixedSegment2d capsuleAxis,
+        Fixed64 radius,
+        out Fixed64 entryParameter,
+        out Fixed64 exitParameter)
+    {
+        if (!TryGetCapsuleIntersectionInterval(
+                capsuleAxis,
+                radius,
+                out entryParameter,
+                out exitParameter))
+        {
+            return false;
+        }
+
+        if (entryParameter > Fixed64.Zero)
+            entryParameter = Fixed64.FromRaw(entryParameter.m_rawValue - 1L);
+        if (exitParameter < Fixed64.One)
+            exitParameter = Fixed64.FromRaw(exitParameter.m_rawValue + 1L);
+        return true;
+    }
+
     /// <summary>
     /// Finds the closed parameter interval where this segment intersects a radially
     /// expanded capsule.
@@ -335,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>

src/FixedMathSharp/Geometry/Wide/Common/WidePlanarProjection.cs

@@ -52,6 +52,53 @@ internal RationalDistance(
 
     #endregion
 
+    internal static bool AreSegmentEndpointDistancesAtLeast(
+        FixedSegment2d first,
+        FixedSegment2d second,
+        Fixed64 minimumDistance)
+    {
+        Signed192 denominator = Signed192.Signed(1L);
+        RationalPoint firstStart = GetRawPoint(first.Start);
+        RationalPoint firstEnd = GetRawPoint(first.End);
+        RationalPoint secondStart = GetRawPoint(second.Start);
+        RationalPoint secondEnd = GetRawPoint(second.End);
+        Signed192 minimumRaw = Signed192.Raw(minimumDistance);
+
+        return CompareDistanceToRaw(
+                GetSegmentDistance(
+                    first.Start,
+                    denominator,
+                    secondStart,
+                    secondEnd),
+                minimumRaw) >= 0
+            && CompareDistanceToRaw(
+                GetSegmentDistance(
+                    first.End,
+                    denominator,
+                    secondStart,
+                    secondEnd),
+                minimumRaw) >= 0
+            && CompareDistanceToRaw(
+                GetSegmentDistance(
+                    second.Start,
+                    denominator,
+                    firstStart,
+                    firstEnd),
+                minimumRaw) >= 0
+            && CompareDistanceToRaw(
+                GetSegmentDistance(
+                    second.End,
+                    denominator,
+                    firstStart,
+                    firstEnd),
+                minimumRaw) >= 0;
+    }
+
+    private static RationalPoint GetRawPoint(Vector2d point) =>
+        new(
+            Signed320.ExtendValue(Signed192.Raw(point.X)),
+            Signed320.ExtendValue(Signed192.Raw(point.Y)));
+
     internal static bool TryGetSphereRelation(
         Vector2d circleCenter,
         Fixed64 circleRadius,

src/FixedMathSharp/Geometry/Wide/Convex/WideConvex2dRelations.ProjectionMath.cs

@@ -468,7 +468,7 @@ private static void GetWorldPoint(
             secondRotatedY);
     }
 
-    private static void GetRotatedOffset(
+    internal static void GetRotatedOffset(
         RotationFrame2d rotation,
         Vector2d localPoint,
         out Signed192 x,

src/FixedMathSharp/Geometry/Wide/Convex/WideConvex2dRelations.cs

@@ -33,7 +33,7 @@ internal WideAxis2d(Signed192 x, Signed192 y)
             new(WideArithmetic.Negate(value.X), WideArithmetic.Negate(value.Y));
     }
 
-    private readonly struct RotationFrame2d
+    internal readonly struct RotationFrame2d
     {
         internal static readonly RotationFrame2d Identity = new(
             Signed192.One,