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.csnew file mode 100644index 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.csindex 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 AnalyticPlanarFaceDomainreturn 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 AnalyticPlanarFaceDomainreturn (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.csnew file mode 100644index 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.mdnew file mode 100644index 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`.