Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add face-domain query contract with planar trim classification

Yuechen Li884c1d1ff0f2
diff --git a/Aetheris.Kernel.Core.Tests/Brep/Queries/FaceDomainQueryTests.cs b/Aetheris.Kernel.Core.Tests/Brep/Queries/FaceDomainQueryTests.cs
new file mode 100644
index 00000000..d3cd951f
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Brep/Queries/FaceDomainQueryTests.cs
@@ -0,0 +1,65 @@
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Brep.Queries;
+using Aetheris.Kernel.Core.Geometry;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+
+namespace Aetheris.Kernel.Core.Tests.Brep.Queries;
+
+public sealed class FaceDomainQueryTests
+{
+ [Fact]
+ public void PlanarFace_Inside_ReturnsInsideWithDiagnostics()
+ {
+ var box = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var faceId = box.Topology.Faces.OrderBy(f => f.Id.Value).First().Id;
+
+ var result = FaceDomainQuery.TryClassifyPointOnFace(box, faceId, new Point3D(0d, 0d, -1d), ToleranceContext.Default);
+
+ Assert.True(result.IsSuccess);
+ Assert.Equal(FaceDomainClassification.Inside, result.Classification);
+ Assert.Equal("FaceDomainQuery.Planar", result.Source);
+ Assert.NotNull(result.ProjectedUv);
+ }
+
+ [Fact]
+ public void PlanarFace_Outside_ReturnsOutside()
+ {
+ var box = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var faceId = box.Topology.Faces.OrderBy(f => f.Id.Value).First().Id;
+
+ var result = FaceDomainQuery.TryClassifyPointOnFace(box, faceId, new Point3D(2d, 0d, -1d));
+
+ Assert.True(result.IsSuccess);
+ Assert.Equal(FaceDomainClassification.Outside, result.Classification);
+ }
+
+ [Fact]
+ public void PlanarFace_Boundary_ReturnsOnBoundaryAndNearEdgeFlag()
+ {
+ var box = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var faceId = box.Topology.Faces.OrderBy(f => f.Id.Value).First().Id;
+
+ var result = FaceDomainQuery.TryClassifyPointOnFace(box, faceId, new Point3D(1d, 0d, -1d));
+
+ Assert.True(result.IsSuccess);
+ Assert.Equal(FaceDomainClassification.OnBoundary, result.Classification);
+ Assert.True(result.NearEdge);
+ Assert.True(result.BoundaryDistance <= ToleranceContext.Default.Linear + 1e-12d);
+ }
+
+ [Fact]
+ public void CurvedFace_Unsupported_ReturnsStructuredReason()
+ {
+ var cylinder = BrepPrimitives.CreateCylinder(2d, 6d).Value;
+ var faceId = cylinder.Topology.Faces.Single(f => cylinder.GetFaceSurface(f.Id).Kind == SurfaceGeometryKind.Cylinder).Id;
+
+ var result = FaceDomainQuery.TryClassifyPointOnFace(cylinder, faceId, new Point3D(2d, 0d, 0d));
+
+ Assert.False(result.IsSuccess);
+ Assert.Equal(FaceDomainClassification.Unsupported, result.Classification);
+ Assert.True(result.UnsupportedSurface);
+ Assert.Contains("not implemented", result.Reason, StringComparison.OrdinalIgnoreCase);
+ Assert.Equal("FaceDomainQuery.UnsupportedCylinder", result.Source);
+ }
+}
diff --git a/Aetheris.Kernel.Core/Brep/Queries/AnalyticPlanarFaceDomain.cs b/Aetheris.Kernel.Core/Brep/Queries/AnalyticPlanarFaceDomain.cs
index 93f6f124..650d8630 100644
--- a/Aetheris.Kernel.Core/Brep/Queries/AnalyticPlanarFaceDomain.cs
+++ b/Aetheris.Kernel.Core/Brep/Queries/AnalyticPlanarFaceDomain.cs
@@ -166,6 +166,70 @@ internal sealed class AnalyticPlanarFaceDomain
return true;
}
+
+ public bool IsNearBoundary(Point3D point, ToleranceContext tolerance, out double boundaryDistance, out bool nearVertex)
+ {
+ boundaryDistance = double.PositiveInfinity;
+ nearVertex = false;
+ var sqTol = tolerance.Linear * tolerance.Linear;
+
+ if (_outerPolygon.Count > 0)
+ {
+ var uv = ProjectToPlane(point, _plane);
+ foreach (var polygon in EnumerateAllPolygons())
+ {
+ for (var i = 0; i < polygon.Count; i++)
+ {
+ var a = polygon[i];
+ var b = polygon[(i + 1) % polygon.Count];
+ var d2 = DistancePointToSegmentSquared(uv, a, b);
+ if (d2 < boundaryDistance * boundaryDistance)
+ {
+ boundaryDistance = double.Sqrt(d2);
+ }
+
+ if (d2 <= sqTol)
+ {
+ nearVertex = nearVertex || DistancePointToPointSquared(uv, a) <= sqTol || DistancePointToPointSquared(uv, b) <= sqTol;
+ return true;
+ }
+ }
+ }
+
+ if (!double.IsFinite(boundaryDistance))
+ {
+ boundaryDistance = double.PositiveInfinity;
+ }
+
+ return false;
+ }
+
+ if (_singleCircularBoundary.HasValue)
+ {
+ var radial = point - _singleCircularBoundary.Value.Center;
+ var height = radial.Dot(_plane.Normal.ToVector());
+ var inPlaneRadial = radial - (_plane.Normal.ToVector() * height);
+ var distance = double.Abs(double.Sqrt(inPlaneRadial.Dot(inPlaneRadial)) - _singleCircularBoundary.Value.Radius);
+ boundaryDistance = distance;
+ return distance <= tolerance.Linear;
+ }
+
+ return false;
+ }
+
+ private IEnumerable<IReadOnlyList<(double U, double V)>> EnumerateAllPolygons()
+ {
+ if (_outerPolygon.Count > 0)
+ {
+ yield return _outerPolygon;
+ }
+
+ foreach (var hole in _innerPolygons)
+ {
+ yield return hole;
+ }
+ }
+
private static bool TryBuildPolygonLoops(
BrepBody body,
Face face,
@@ -417,6 +481,13 @@ internal sealed class AnalyticPlanarFaceDomain
return (dU * dU) + (dV * dV);
}
+ private static double DistancePointToPointSquared((double U, double V) a, (double U, double V) b)
+ {
+ var du = a.U - b.U;
+ var dv = a.V - b.V;
+ return (du * du) + (dv * dv);
+ }
+
private static double SignedArea(IReadOnlyList<(double U, double V)> polygon)
{
var area = 0d;
diff --git a/Aetheris.Kernel.Core/Brep/Queries/FaceDomainQuery.cs b/Aetheris.Kernel.Core/Brep/Queries/FaceDomainQuery.cs
new file mode 100644
index 00000000..208a6f17
--- /dev/null
+++ b/Aetheris.Kernel.Core/Brep/Queries/FaceDomainQuery.cs
@@ -0,0 +1,110 @@
+using Aetheris.Kernel.Core.Geometry;
+using Aetheris.Kernel.Core.Geometry.Surfaces;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+using Aetheris.Kernel.Core.Topology;
+
+namespace Aetheris.Kernel.Core.Brep.Queries;
+
+public enum FaceDomainClassification
+{
+ Inside,
+ OnBoundary,
+ Outside,
+ Ambiguous,
+ Unsupported
+}
+
+public sealed record FaceDomainQueryResult(
+ bool IsSuccess,
+ FaceId FaceId,
+ SurfaceGeometryKind? SurfaceKind,
+ FaceDomainClassification Classification,
+ (double U, double V)? ProjectedUv,
+ double? BoundaryDistance,
+ bool NearEdge,
+ bool NearVertex,
+ bool SeamDuplicateRisk,
+ bool TrimUnavailable,
+ bool UnsupportedSurface,
+ string Source,
+ string Reason);
+
+public static class FaceDomainQuery
+{
+ public static FaceDomainQueryResult TryClassifyPointOnFace(
+ BrepBody body,
+ FaceId faceId,
+ Point3D point,
+ ToleranceContext? tolerance = null)
+ {
+ var tol = tolerance ?? ToleranceContext.Default;
+ if (!body.TryGetFaceSurfaceGeometry(faceId, out var surface) || surface is null)
+ {
+ return Unsupported(faceId, null, "FaceDomainQuery.MissingSurface", "Face has no bound surface geometry.", trimUnavailable: true);
+ }
+
+ return surface.Kind switch
+ {
+ SurfaceGeometryKind.Plane when surface.Plane is PlaneSurface plane => ClassifyPlanar(body, faceId, plane, point, tol),
+ SurfaceGeometryKind.Cylinder => Unsupported(faceId, surface.Kind, "FaceDomainQuery.UnsupportedCylinder", "Surface projection/trim classification for cylindrical faces is not implemented in this milestone.", seamDuplicateRisk: true),
+ SurfaceGeometryKind.Sphere => Unsupported(faceId, surface.Kind, "FaceDomainQuery.UnsupportedSphere", "Surface projection/trim classification for spherical faces is not implemented in this milestone.", seamDuplicateRisk: true),
+ SurfaceGeometryKind.Cone => Unsupported(faceId, surface.Kind, "FaceDomainQuery.UnsupportedCone", "Surface projection/trim classification for conical faces is not implemented in this milestone.", seamDuplicateRisk: true),
+ SurfaceGeometryKind.Torus => Unsupported(faceId, surface.Kind, "FaceDomainQuery.UnsupportedTorus", "Surface projection/trim classification for toroidal faces is not implemented in this milestone.", seamDuplicateRisk: true),
+ SurfaceGeometryKind.BSplineSurfaceWithKnots => Unsupported(faceId, surface.Kind, "FaceDomainQuery.UnsupportedBSpline", "Surface projection/trim classification for bspline faces is not implemented in this milestone.", trimUnavailable: true),
+ _ => Unsupported(faceId, surface.Kind, "FaceDomainQuery.UnsupportedSurface", "Surface kind is unsupported for face-domain query.")
+ };
+ }
+
+ private static FaceDomainQueryResult ClassifyPlanar(BrepBody body, FaceId faceId, PlaneSurface plane, Point3D point, ToleranceContext tolerance)
+ {
+ var uv = ProjectToPlane(point, plane);
+ if (!AnalyticPlanarFaceDomain.TryCreate(body, faceId, plane, out var domain))
+ {
+ return new FaceDomainQueryResult(
+ IsSuccess: false,
+ faceId,
+ SurfaceGeometryKind.Plane,
+ FaceDomainClassification.Ambiguous,
+ uv,
+ BoundaryDistance: null,
+ NearEdge: false,
+ NearVertex: false,
+ SeamDuplicateRisk: false,
+ TrimUnavailable: true,
+ UnsupportedSurface: false,
+ Source: "FaceDomainQuery.Planar.TrimUnavailable",
+ Reason: "Planar face exists but trim/domain loops could not be resolved for classification.");
+ }
+
+ var inside = domain.Contains(point, tolerance);
+ var nearBoundary = domain.IsNearBoundary(point, tolerance, out var boundaryDistance, out var nearVertex);
+ var classification = nearBoundary
+ ? FaceDomainClassification.OnBoundary
+ : inside ? FaceDomainClassification.Inside : FaceDomainClassification.Outside;
+
+ return new FaceDomainQueryResult(
+ IsSuccess: true,
+ faceId,
+ SurfaceGeometryKind.Plane,
+ classification,
+ uv,
+ boundaryDistance,
+ NearEdge: nearBoundary,
+ NearVertex: nearVertex,
+ SeamDuplicateRisk: false,
+ TrimUnavailable: false,
+ UnsupportedSurface: false,
+ Source: "FaceDomainQuery.Planar",
+ Reason: classification.ToString());
+ }
+
+ private static FaceDomainQueryResult Unsupported(FaceId faceId, SurfaceGeometryKind? kind, string source, string reason, bool seamDuplicateRisk = false, bool trimUnavailable = false)
+ => new(false, faceId, kind, FaceDomainClassification.Unsupported, null, null, false, false, seamDuplicateRisk, trimUnavailable, true, source, reason);
+
+ private static (double U, double V) ProjectToPlane(Point3D point, PlaneSurface plane)
+ {
+ var local = point - plane.Origin;
+ return (local.Dot(plane.UAxis.ToVector()), local.Dot(plane.VAxis.ToVector()));
+ }
+}
diff --git a/docs/analyze-p1f-ray-hit-handoff.md b/docs/analyze-p1f-ray-hit-handoff.md
new file mode 100644
index 00000000..c6714b4b
--- /dev/null
+++ b/docs/analyze-p1f-ray-hit-handoff.md
@@ -0,0 +1,56 @@
+# ANALYZE-P1f ray-hit handoff (post P1e)
+
+Date: 2026-05-05
+
+## What landed in P1e
+
+`FaceDomainQuery.TryClassifyPointOnFace(...)` now provides a query-layer contract to classify a point projected onto a face as:
+
+- `Inside`
+- `OnBoundary`
+- `Outside`
+- `Ambiguous`
+- `Unsupported`
+
+For each query, it also returns structured diagnostics needed by P1f (`SurfaceKind`, projected UV when available, boundary distance, ambiguity flags, and stable source/reason strings).
+
+## P1f consumption pattern
+
+For each ray/surface candidate hit in generic provider:
+
+1. Compute geometric hit on candidate surface.
+2. Call `FaceDomainQuery.TryClassifyPointOnFace(body, faceId, hitPoint, tolerance)`.
+3. Accept/reject candidate using result classification:
+ - **Admissible:** `Inside`
+ - **Conditionally admissible:** `OnBoundary` (keep with boundary ambiguity flag and dedupe handling)
+ - **Inadmissible:** `Outside`
+ - **Inadmissible / needs fallback:** `Ambiguous`, `Unsupported`
+4. Feed `NearEdge`, `NearVertex`, `SeamDuplicateRisk`, and `BoundaryDistance` into duplicate-hit collapse and tie-breaking.
+5. Carry `Source`/`Reason` into containment diagnostics for `multi_axis_ray_consensus` traceability.
+
+## Current implementation bounds
+
+- **Implemented:** planar faces (`SurfaceGeometryKind.Plane`), with trimmed-domain evaluation via `AnalyticPlanarFaceDomain`.
+- **Deferred:** cylinder/sphere/cone/torus/bspline face trim-domain classification.
+
+Deferred reasons are explicit and returned as `Unsupported` with stable source values:
+
+- `FaceDomainQuery.UnsupportedCylinder`
+- `FaceDomainQuery.UnsupportedSphere`
+- `FaceDomainQuery.UnsupportedCone`
+- `FaceDomainQuery.UnsupportedTorus`
+- `FaceDomainQuery.UnsupportedBSpline`
+
+## Planar behavior details relied on by P1f
+
+- Hit point is projected to plane local UV.
+- Classification is against the trimmed face domain (not infinite plane).
+- Multi-loop planar domains include outer + hole exclusions where `AnalyticPlanarFaceDomain` can resolve loops.
+- Near-boundary hits are promoted to `OnBoundary` (not inside/outside).
+- If planar trim loops cannot be resolved, result is `Ambiguous` with `TrimUnavailable=true` and source `FaceDomainQuery.Planar.TrimUnavailable`.
+
+## Remaining work in P1f/P1g
+
+1. Add robust per-surface projection + trim-space membership for cylindrical/spherical (then cone/torus).
+2. Add seam-aware UV canonicalization and duplicate collapse rules for periodic surfaces.
+3. Wire `FaceDomainQuery` results into generic ray provider and then activate `multi_axis_ray_consensus` candidate in `BrepSpatialQueries.ClassifyPoint`.