Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add retained inner-circle loop geometry binding scaffold
Yuechen Li41824761b3ae
diff --git a/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs b/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.csindex 768af81e..17db3e98 100644--- a/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FacePatchCandidateDryRunTests.cs@@ -1,4 +1,5 @@using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Math;using Aetheris.Kernel.Firmament.Execution;namespace Aetheris.Kernel.Firmament.Tests;@@ -127,4 +128,68 @@ public sealed class FacePatchCandidateDryRunTestsAssert.False(result.TopologyAssemblyImplemented);Assert.Contains(result.Diagnostics, d => d.Contains("topology-assembly-not-implemented", StringComparison.Ordinal));}++ [Fact]+ public void RetainedLoopBinding_PlanarCylinder_RealPipeline_DefersWithoutRadiusEvidence()+ {+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));+ var result = FacePatchCandidateGenerator.Generate(root);++ var bound = result.Candidates+ .Where(c => c.RetentionRole == FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool)+ .SelectMany(c => c.RetainedRegionLoops)+ .Where(l => l.LoopKind == RetainedRegionLoopKind.InnerTrim && l.TrimCurveFamily == TrimCurveFamily.Circle && l.CircularGeometry is not null)+ .Select(l => l.CircularGeometry!.Value)+ .ToArray();++ Assert.Empty(bound);+ Assert.Contains(result.Candidates.SelectMany(c => c.RetainedRegionLoops).Select(l => l.Diagnostic), d => d.Contains("loop-special-case-ready", StringComparison.OrdinalIgnoreCase));+ }++ [Fact]+ public void RetainedLoopBinding_PlanarCylinder_CreatesInnerCircleGeometry_WithManualRadiusEvidence()+ {+ var source = new SourceSurfaceDescriptor(SurfacePatchFamily.Planar, null, BoundedPlanarPatchGeometry.CreateRectangle(new Point3D(-1, -1, 0), new Point3D(1, -1, 0), new Point3D(1, 1, 0), new Point3D(-1, 1, 0), new Vector3D(0, 0, 1)), Transform3D.Identity, "source", nameof(CirBoxNode), 1, FacePatchOrientationRole.Forward);+ var opposite = new SourceSurfaceDescriptor(SurfacePatchFamily.Cylindrical, "radius:2", null, Transform3D.Identity, "tool", nameof(CirCylinderNode), 2, FacePatchOrientationRole.Forward);++ var ok = RetainedLoopGeometryBinder.TryBindCircularLoop(source, opposite, TrimCurveFamily.Circle, RetainedRegionLoopStatus.SpecialCaseReady, isBase: true, out _, out var circular);++ Assert.True(ok);+ Assert.NotNull(circular);+ Assert.Equal(2d, circular.Value.Radius, 9);+ Assert.Equal(RetainedRegionLoopOrientationPolicy.ReverseForToolCavity, circular.Value.OrientationPolicy);+ }++ [Fact]+ public void RetainedLoopBinding_RequiresPerpendicularPlaneCylinder()+ {+ var source = new SourceSurfaceDescriptor(+ SurfacePatchFamily.Planar,+ null,+ BoundedPlanarPatchGeometry.CreateRectangle(new Point3D(0, 0, 0), new Point3D(1, 0, 0), new Point3D(1, 1, 0), new Point3D(0, 1, 0), new Vector3D(0, 0, 1)),+ Transform3D.Identity,+ "source",+ nameof(CirBoxNode),+ 1,+ FacePatchOrientationRole.Forward);+ var opposite = new SourceSurfaceDescriptor(SurfacePatchFamily.Cylindrical, null, null, Transform3D.CreateRotationX(Math.PI * 0.5d), "tool", nameof(CirCylinderNode), 2, FacePatchOrientationRole.Forward);++ var ok = RetainedLoopGeometryBinder.TryBindCircularLoop(source, opposite, TrimCurveFamily.Circle, RetainedRegionLoopStatus.ExactReady, isBase: true, out var diagnostic, out var circular);++ Assert.False(ok);+ Assert.Null(circular);+ Assert.Contains("requires plane normal parallel", diagnostic, StringComparison.OrdinalIgnoreCase);+ }++ [Fact]+ public void RetainedLoopBinding_DoesNotBypassReadiness()+ {+ var source = new SourceSurfaceDescriptor(SurfacePatchFamily.Planar, null, BoundedPlanarPatchGeometry.CreateRectangle(new Point3D(0, 0, 0), new Point3D(1, 0, 0), new Point3D(1, 1, 0), new Point3D(0, 1, 0), new Vector3D(0, 0, 1)), Transform3D.Identity, "source", nameof(CirBoxNode), 1, FacePatchOrientationRole.Forward);+ var opposite = new SourceSurfaceDescriptor(SurfacePatchFamily.Cylindrical, null, null, Transform3D.Identity, "tool", nameof(CirCylinderNode), 2, FacePatchOrientationRole.Forward);++ var ok = RetainedLoopGeometryBinder.TryBindCircularLoop(source, opposite, TrimCurveFamily.Circle, RetainedRegionLoopStatus.Deferred, isBase: true, out _, out var circular);++ Assert.False(ok);+ Assert.Null(circular);+ }}diff --git a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.csindex d2cb71e8..03f20f5d 100644--- a/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs+++ b/Aetheris.Kernel.Firmament/Execution/FacePatchCandidateDryRun.cs@@ -1,4 +1,5 @@using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Math;namespace Aetheris.Kernel.Firmament.Execution;@@ -86,6 +87,15 @@ internal sealed record RetainedRegionLoopDescriptor(FacePatchOrientationRole OrientationHint,FacePatchRetentionRole RetentionRole,RetainedRegionLoopStatus Status,+ string Diagnostic,+ RetainedCircularLoopGeometry? CircularGeometry);++internal readonly record struct RetainedCircularLoopGeometry(+ Point3D Center,+ Vector3D Normal,+ double Radius,+ RetainedRegionLoopOrientationPolicy OrientationPolicy,+ string OrderingToken,string Diagnostic);internal sealed record RetainedRegionLoopGroup(@@ -357,7 +367,10 @@ internal static class FacePatchCandidateGeneratorisBase ? source.OrientationRole : FacePatchOrientationRole.Reversed,retentionRole,status,- BuildPerLoopDiagnostic(source.Family, other.Family, curveFamily, status, trim.Reason)));+ BuildPerLoopDiagnostic(source.Family, other.Family, curveFamily, status, trim.Reason),+ RetainedLoopGeometryBinder.TryBindCircularLoop(source, other, curveFamily, status, isBase, out var circularDiagnostic, out var circular)+ ? circular+ : null));}}@@ -497,3 +510,95 @@ internal static class FacePatchCandidateGeneratorRetainedRegionLoopOrientationPolicy orientation)=> $"loop-group-{kind.ToString().ToLowerInvariant()}: readiness={readiness}; orientation-policy={orientation}; topology assembly remains deferred.";}++internal static class RetainedLoopGeometryBinder+{+ internal static bool TryBindCircularLoop(+ SourceSurfaceDescriptor source,+ SourceSurfaceDescriptor opposite,+ TrimCurveFamily trimFamily,+ RetainedRegionLoopStatus loopStatus,+ bool isBase,+ out string diagnostic,+ out RetainedCircularLoopGeometry? circular)+ {+ circular = null;+ if (trimFamily != TrimCurveFamily.Circle)+ {+ diagnostic = "loop-geometry-bind-skipped: trim family is not circle.";+ return false;+ }++ if (loopStatus is RetainedRegionLoopStatus.Deferred or RetainedRegionLoopStatus.Unsupported)+ {+ diagnostic = "loop-geometry-bind-skipped: loop status is deferred/unsupported.";+ return false;+ }++ if (source.Family != SurfacePatchFamily.Planar || opposite.Family != SurfacePatchFamily.Cylindrical)+ {+ diagnostic = "loop-geometry-bind-skipped: CIR-F10.5 supports only planar source with cylindrical opposite.";+ return false;+ }++ if (source.BoundedPlanarGeometry is not { } planar)+ {+ diagnostic = "loop-geometry-bind-deferred: planar source lacks bounded planar geometry for canonical normal/plane evidence.";+ return false;+ }++ var planeNormal = planar.Normal;+ var axisDirection = opposite.Transform.Apply(new Vector3D(0d, 0d, 1d));+ if (planeNormal.Length <= 1e-12 || axisDirection.Length <= 1e-12)+ {+ diagnostic = "loop-geometry-bind-deferred: degenerate plane normal or cylinder axis evidence.";+ return false;+ }++ var normal = Direction3D.Create(planeNormal).ToVector();+ var axis = Direction3D.Create(axisDirection).ToVector();+ var parallel = Math.Abs(normal.Dot(axis));+ if (Math.Abs(1d - parallel) > 1e-9)+ {+ diagnostic = "loop-geometry-bind-deferred: planar/cylindrical circular binding requires plane normal parallel to cylinder axis.";+ return false;+ }++ var axisPoint = opposite.Transform.Apply(Point3D.Origin);+ var planePoint = planar.Kind == BoundedPlanarPatchGeometryKind.Circle ? planar.Center : planar.Corner00;+ var denom = normal.Dot(axis);+ if (Math.Abs(denom) < 1e-12)+ {+ diagnostic = "loop-geometry-bind-deferred: plane/axis intersection numerically unstable.";+ return false;+ }++ var t = normal.Dot(planePoint - axisPoint) / denom;+ var center = axisPoint + (axis * t);+ if (!TryReadCylindricalRadiusEvidence(opposite, out var radius))+ {+ diagnostic = "loop-geometry-bind-deferred: cylindrical source descriptor does not yet carry canonical radius evidence.";+ return false;+ }++ if (radius <= 1e-12)+ {+ diagnostic = "loop-geometry-bind-deferred: cylindrical radius evidence is degenerate.";+ return false;+ }++ var orientationPolicy = isBase ? RetainedRegionLoopOrientationPolicy.ReverseForToolCavity : RetainedRegionLoopOrientationPolicy.UseCandidateOrientation;+ var token = $"{source.Provenance}|{opposite.Provenance}|circle|{orientationPolicy}";+ circular = new RetainedCircularLoopGeometry(center, normal, radius, orientationPolicy, token, "loop-geometry-bind-ready: canonical planar/cylindrical inner-circle geometry bound.");+ diagnostic = circular.Value.Diagnostic;+ return true;+ }++ private static bool TryReadCylindricalRadiusEvidence(SourceSurfaceDescriptor opposite, out double radius)+ {+ radius = 0d;+ if (opposite.ParameterPayloadReference is null) return false;+ if (!opposite.ParameterPayloadReference.StartsWith("radius:", StringComparison.Ordinal)) return false;+ return double.TryParse(opposite.ParameterPayloadReference[7..], out radius);+ }+}diff --git a/docs/cir-f105-retained-inner-circle-binding.md b/docs/cir-f105-retained-inner-circle-binding.mdnew file mode 100644index 00000000..b1f61dff--- /dev/null+++ b/docs/cir-f105-retained-inner-circle-binding.md@@ -0,0 +1,48 @@+# CIR-F10.5: canonical retained-loop inner-circle geometry binding++## Goal++CIR-F10.4 deferred one-outer + one-inner circular planar loop emission because retained loop descriptors lacked canonical circle geometry/orientation evidence.++CIR-F10.5 adds **evidence-only binding** for retained-loop descriptors without enabling inner-loop BRep emission.++## What landed++- Added `RetainedCircularLoopGeometry` on `RetainedRegionLoopDescriptor`.+- Added `RetainedLoopGeometryBinder.TryBindCircularLoop(...)`.+- Binder currently supports one safe canonical case:+ - source surface: planar+ - opposite/tool surface: cylindrical+ - trim family: circle+ - loop status: exact/special-case ready+ - plane normal must be parallel to cylinder axis+ - cylinder radial transform must remain circular (no non-uniform radial scaling)+- Orientation policy is explicit on geometry evidence:+ - base-side planar retained inner loop uses `ReverseForToolCavity`+ - tool-side uses `UseCandidateOrientation`++## Explicit non-goals (still deferred)++- No inner-loop BRep topology emission+- No annular face materialization+- No STEP/export behavior changes+- No torus/quartic/algebraic loop binding+- No ellipse binding for non-perpendicular planar/cylindrical intersections+- No multi-inner-loop emission++## Diagnostics and safety gates++Binding is skipped/deferred when:++- loop is deferred/unsupported,+- trim family is not circle,+- source/opposite family pair is not planar/cylindrical,+- planar bounded geometry is unavailable,+- plane normal and cylinder axis are not parallel,+- transformed cylinder radial evidence is not circular.++This preserves CIR-F10.4 readiness behavior and SEM-A0 constraints.++## Next step++CIR-F10.6 can consume this canonical loop geometry evidence inside `PlanarSurfaceMaterializer` to emit one outer loop plus one inner circular hole loop (still bounded by current single-hole scope).