Skip to content

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.cs
index 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 FacePatchCandidateDryRunTests
Assert.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.cs
index 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 FacePatchCandidateGenerator
isBase ? 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 FacePatchCandidateGenerator
RetainedRegionLoopOrientationPolicy 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.md
new file mode 100644
index 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).