Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add bounded counterbore HoleRecoveryPlan executor
Yuechen Li6ed87a45c1c3
diff --git a/Aetheris.Kernel.Firmament.Tests/CounterboreRecoveryExecutorTests.cs b/Aetheris.Kernel.Firmament.Tests/CounterboreRecoveryExecutorTests.csnew file mode 100644index 00000000..2a15df98--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/CounterboreRecoveryExecutorTests.cs@@ -0,0 +1,77 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Geometry;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Firmament.Materializer;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class CounterboreRecoveryExecutorTests+{+ [Fact]+ public void CounterboreExecutor_CanonicalPlan_ProducesBrepBody()+ {+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildCanonicalCounterbore()));+ var plan = Assert.IsType<HoleRecoveryPlan>(eval.Plan);++ var result = HoleRecoveryExecutor.Execute(plan);++ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, result.Status);+ Assert.NotNull(result.Body);+ Assert.Contains(result.Diagnostics, d => d.Contains("First subtract succeeded", StringComparison.Ordinal));+ Assert.Contains(result.Diagnostics, d => d.Contains("Second subtract succeeded", StringComparison.Ordinal));+ }++ [Fact]+ public void CounterboreExecutor_Rematerializer_ProducesBrepBody()+ {+ var result = FrepSemanticRecoveryRematerializer.TryRecover(BuildCanonicalCounterbore());+ Assert.True(result.Succeeded);+ Assert.NotNull(result.Body);+ Assert.Contains(result.Diagnostics, d => d.Contains("rematerializer executing hole-family plan", StringComparison.Ordinal));+ }++ [Fact]+ public void CounterboreExecutor_RejectsUnsupportedPlanShape()+ {+ var plan = new HoleRecoveryPlan(HoleHostKind.RectangularBox, HoleAxisKind.Z, HoleKind.Counterbore, HoleDepthKind.ThroughWithEntryRelief, HoleEntryFeatureKind.Counterbore, HoleExitFeatureKind.Plain, 10, 20, 20, 10, Vector3D.Zero, Vector3D.Zero,+ [new(HoleProfileSegmentKind.Cylindrical, 2,2,0,4)], [], [], FrepMaterializerCapability.ExactBRep, []);+ var result = HoleRecoveryExecutor.Execute(plan);+ Assert.Equal(HoleRecoveryExecutionStatus.UnsupportedPlan, result.Status);+ Assert.Contains(result.Diagnostics, d => d.Contains("shape mismatch", StringComparison.Ordinal));+ }++ [Fact]+ public void CounterboreExecutor_ThroughHoleStillWorks()+ {+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(3, 20))));+ var plan = Assert.IsType<HoleRecoveryPlan>(eval.Plan);+ var result = HoleRecoveryExecutor.Execute(plan);+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, result.Status);+ Assert.NotNull(result.Body);+ Assert.Contains(result.Diagnostics, d => d.Contains("delegated", StringComparison.Ordinal));+ }++ [Fact]+ public void CounterboreExecutor_BodyHasExpectedSanity()+ {+ var plan = Assert.IsType<HoleRecoveryPlan>(new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildCanonicalCounterbore())).Plan);+ var result = HoleRecoveryExecutor.Execute(plan);+ var body = Assert.IsType<Aetheris.Kernel.Core.Brep.BrepBody>(result.Body);+ Assert.True(body.Topology.Faces.Any());+ Assert.Contains(body.Topology.Faces, face => body.TryGetFaceSurfaceGeometry(face.Id, out var s) && s?.Kind == SurfaceGeometryKind.Cylinder);+ Assert.Contains(body.Topology.Faces, face => body.TryGetFaceSurfaceGeometry(face.Id, out var s) && s?.Kind == SurfaceGeometryKind.Plane);+ }++ [Fact]+ public void CounterboreExecutor_DoesNotExportStep()+ {+ var plan = Assert.IsType<HoleRecoveryPlan>(new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildCanonicalCounterbore())).Plan);+ var result = HoleRecoveryExecutor.Execute(plan);+ Assert.Contains(result.Diagnostics, d => d.Contains("No STEP export attempted", StringComparison.Ordinal));+ }++ private static CirNode BuildCanonicalCounterbore()+ => new CirSubtractNode(+ new CirSubtractNode(new CirBoxNode(20, 20, 10), new CirCylinderNode(2, 20)),+ new CirTransformNode(new CirCylinderNode(4, 4), Transform3D.CreateTranslation(new Vector3D(0, 0, -3))));+}diff --git a/Aetheris.Kernel.Firmament.Tests/CounterboreVariantTests.cs b/Aetheris.Kernel.Firmament.Tests/CounterboreVariantTests.csindex 873897c7..8da22511 100644--- a/Aetheris.Kernel.Firmament.Tests/CounterboreVariantTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/CounterboreVariantTests.cs@@ -41,14 +41,14 @@ public sealed class CounterboreVariantTests}[Fact]- public void Rematerializer_CounterborePlan_DoesNotFalseSucceedWithoutExecutor()+ public void Rematerializer_CounterborePlan_ExecutesWithHoleRecoveryExecutor(){var result = FrepSemanticRecoveryRematerializer.TryRecover(BuildCanonicalCounterbore());- Assert.False(result.Succeeded);- Assert.Null(result.Body);- Assert.Equal(ThroughHoleRecoveryExecutionStatus.UnsupportedPlan, result.ExecutionStatus);+ Assert.True(result.Succeeded);+ Assert.NotNull(result.Body);+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, result.ExecutionStatus);Assert.Contains(result.Diagnostics, d => d.Contains("selected policy: HoleRecoveryPolicy", StringComparison.Ordinal));- Assert.Contains(result.Diagnostics, d => d.Contains("non-executable", StringComparison.Ordinal));+ Assert.Contains(result.Diagnostics, d => d.Contains("Second subtract succeeded", StringComparison.Ordinal));}diff --git a/Aetheris.Kernel.Firmament/Materializer/FrepSemanticRecoveryRematerializer.cs b/Aetheris.Kernel.Firmament/Materializer/FrepSemanticRecoveryRematerializer.csindex efebb1a3..d686f9db 100644--- a/Aetheris.Kernel.Firmament/Materializer/FrepSemanticRecoveryRematerializer.cs+++ b/Aetheris.Kernel.Firmament/Materializer/FrepSemanticRecoveryRematerializer.cs@@ -9,7 +9,7 @@ internal sealed record FrepSemanticRecoveryResult(bool Succeeded,string? SelectedPolicy,HoleRecoveryPlan? Plan,- ThroughHoleRecoveryExecutionStatus ExecutionStatus,+ HoleRecoveryExecutionStatus ExecutionStatus,BrepBody? Body,IReadOnlyList<string> Diagnostics,FrepMaterializerDecision Decision);@@ -34,14 +34,14 @@ internal static class FrepSemanticRecoveryRematerializerif (decision.Status != FrepMaterializerDecisionStatus.Selected){diagnostics.Add("no admissible policy");- return new(true, false, null, null, ThroughHoleRecoveryExecutionStatus.Failed, null, diagnostics, decision);+ return new(true, false, null, null, HoleRecoveryExecutionStatus.Failed, null, diagnostics, decision);}diagnostics.Add($"selected policy: {decision.SelectedPolicyName}");if (!string.Equals(decision.SelectedPolicyName, nameof(HoleRecoveryPolicy), StringComparison.Ordinal)){diagnostics.Add("selected policy was not HoleRecoveryPolicy");- return new(true, false, decision.SelectedPolicyName, null, ThroughHoleRecoveryExecutionStatus.Failed, null, diagnostics, decision);+ return new(true, false, decision.SelectedPolicyName, null, HoleRecoveryExecutionStatus.Failed, null, diagnostics, decision);}var selectedEval = decision.Evaluations.Single(e => string.Equals(e.PolicyName, decision.SelectedPolicyName, StringComparison.Ordinal));@@ -49,21 +49,15 @@ internal static class FrepSemanticRecoveryRematerializer{diagnostics.Add("selected policy did not provide hole-recovery plan");diagnostics.Add("selected policy is non-executable for exact BRep recovery");- return new(true, false, decision.SelectedPolicyName, null, ThroughHoleRecoveryExecutionStatus.Failed, null, diagnostics, decision);+ return new(true, false, decision.SelectedPolicyName, null, HoleRecoveryExecutionStatus.Failed, null, diagnostics, decision);}diagnostics.Add("hole-recovery plan extracted");- if (!ThroughHoleRecoveryPlanAdapter.TryConvert(plan, out var throughPlan) || throughPlan is null)- {- diagnostics.Add("hole plan conversion to through-hole executor contract failed");- diagnostics.Add("selected hole variant is currently non-executable");- return new(true, false, decision.SelectedPolicyName, plan, ThroughHoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics, decision);- }-- diagnostics.Add("hole plan converted to through-hole executor contract");- var execution = ThroughHoleRecoveryExecutor.Execute(throughPlan);+ diagnostics.Add("hole-family plan extracted");+ diagnostics.Add("rematerializer executing hole-family plan via HoleRecoveryExecutor");+ var execution = HoleRecoveryExecutor.Execute(plan);diagnostics.AddRange(execution.Diagnostics);- if (execution.Status != ThroughHoleRecoveryExecutionStatus.Succeeded || execution.Body is null)+ if (execution.Status != HoleRecoveryExecutionStatus.Succeeded || execution.Body is null){diagnostics.Add("executor failed");return new(true, false, decision.SelectedPolicyName, plan, execution.Status, null, diagnostics, decision);diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.csnew file mode 100644index 00000000..22a564fc--- /dev/null+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs@@ -0,0 +1,144 @@+using Aetheris.Kernel.Core.Brep;+using Aetheris.Kernel.Core.Brep.Boolean;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Firmament.Execution;++namespace Aetheris.Kernel.Firmament.Materializer;++public enum HoleRecoveryExecutionStatus+{+ Succeeded,+ UnsupportedPlan,+ PrimitiveConstructionFailed,+ BooleanFailed,+ InvalidResult,+ Failed+}++public sealed record HoleRecoveryExecutionResult(+ HoleRecoveryExecutionStatus Status,+ BrepBody? Body,+ IReadOnlyList<string> Diagnostics);++public static class HoleRecoveryExecutor+{+ public static HoleRecoveryExecutionResult Execute(HoleRecoveryPlan plan)+ {+ ArgumentNullException.ThrowIfNull(plan);++ var diagnostics = new List<string>+ {+ "HoleRecoveryExecutor started.",+ "No STEP export attempted by hole executor."+ };++ diagnostics.Add($"Plan kind inspection: holeKind={plan.HoleKind}, depthKind={plan.DepthKind}.");+ if (plan.HoleKind == HoleKind.Through)+ {+ diagnostics.Add("Plan kind accepted: through-hole delegated to ThroughHoleRecoveryExecutor.");+ if (!ThroughHoleRecoveryPlanAdapter.TryConvert(plan, out var throughPlan) || throughPlan is null)+ {+ diagnostics.Add("Through-hole adapter conversion failed.");+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);+ }++ var through = ThroughHoleRecoveryExecutor.Execute(throughPlan);+ diagnostics.AddRange(through.Diagnostics);+ return new((HoleRecoveryExecutionStatus)through.Status, through.Body, diagnostics);+ }++ if (plan.HoleKind != HoleKind.Counterbore || plan.DepthKind != HoleDepthKind.ThroughWithEntryRelief)+ {+ diagnostics.Add("Plan rejected: only bounded counterbore ThroughWithEntryRelief is supported.");+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);+ }++ diagnostics.Add("Counterbore plan accepted for bounded execution.");+ if (plan.HostKind != HoleHostKind.RectangularBox || plan.Axis != HoleAxisKind.Z || plan.ProfileStack.Count != 2)+ {+ diagnostics.Add("Plan rejected: host/axis/profile shape mismatch for bounded counterbore.");+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);+ }++ var large = plan.ProfileStack[0];+ var small = plan.ProfileStack[1];+ if (large.SegmentKind != HoleProfileSegmentKind.Cylindrical || small.SegmentKind != HoleProfileSegmentKind.Cylindrical)+ {+ diagnostics.Add("Plan rejected: both profile segments must be cylindrical.");+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);+ }++ var tolerance = Aetheris.Kernel.Core.Numerics.ToleranceContext.Default.Linear;+ if (Math.Abs(small.DepthEnd - plan.ThroughLength) > tolerance || large.RadiusStart <= small.RadiusStart + tolerance)+ {+ diagnostics.Add("Plan rejected: profile stack does not match counterbore (large shallow + small through).");+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);+ }++ diagnostics.Add("Profile stack validated.");++ var boxResult = BrepPrimitives.CreateBox(plan.HostSizeX, plan.HostSizeY, plan.HostSizeZ);+ if (!boxResult.IsSuccess)+ {+ diagnostics.Add("Box primitive construction failed.");+ return new(HoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);+ }++ var boxBody = TranslateBody(boxResult.Value, plan.HostTranslation);++ var throughHeight = double.Max(plan.ThroughLength, plan.HostSizeZ);+ var smallResult = BrepPrimitives.CreateCylinder(small.RadiusStart, throughHeight);+ if (!smallResult.IsSuccess)+ {+ diagnostics.Add("Small through cylinder primitive construction failed.");+ return new(HoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);+ }++ var smallBody = TranslateBody(smallResult.Value, plan.ToolTranslation);+ diagnostics.Add("Small through cylinder constructed.");++ var firstSubtract = BrepBoolean.Subtract(boxBody, smallBody);+ if (!firstSubtract.IsSuccess || firstSubtract.Value is null)+ {+ diagnostics.Add("First subtract failed (host - through cylinder).");+ return new(HoleRecoveryExecutionStatus.BooleanFailed, null, diagnostics);+ }++ diagnostics.Add("First subtract succeeded.");++ var shallowDepth = large.DepthEnd - large.DepthStart;+ if (shallowDepth <= tolerance)+ {+ diagnostics.Add("Plan rejected: counterbore shallow depth must be positive.");+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);+ }++ var entryFaceZ = plan.HostTranslation.Z - (plan.HostSizeZ * 0.5d);+ var largeCenterZ = entryFaceZ + (shallowDepth * 0.5d);+ var largeToolTranslation = new Vector3D(plan.ToolTranslation.X, plan.ToolTranslation.Y, largeCenterZ);++ var largeResult = BrepPrimitives.CreateCylinder(large.RadiusStart, shallowDepth);+ if (!largeResult.IsSuccess)+ {+ diagnostics.Add("Large counterbore cylinder primitive construction failed.");+ return new(HoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);+ }++ var largeBody = TranslateBody(largeResult.Value, largeToolTranslation);+ diagnostics.Add("Large counterbore cylinder constructed.");++ var secondSubtract = BrepBoolean.Subtract(firstSubtract.Value, largeBody);+ if (!secondSubtract.IsSuccess || secondSubtract.Value is null)+ {+ diagnostics.Add("Second subtract failed (through result - counterbore relief).");+ return new(HoleRecoveryExecutionStatus.BooleanFailed, null, diagnostics);+ }++ diagnostics.Add("Second subtract succeeded.");+ diagnostics.Add("Result BRep body produced.");+ return new(HoleRecoveryExecutionStatus.Succeeded, secondSubtract.Value, diagnostics);+ }++ private static BrepBody TranslateBody(BrepBody body, Vector3D translation)+ => translation == Vector3D.Zero ? body : FirmamentPrimitiveExecutionTranslation.TranslateBody(body, translation);+}diff --git a/docs/cir-recovery-v7b-counterbore-executor.md b/docs/cir-recovery-v7b-counterbore-executor.mdnew file mode 100644index 00000000..18e3989a--- /dev/null+++ b/docs/cir-recovery-v7b-counterbore-executor.md@@ -0,0 +1,62 @@+# CIR-RECOVERY-V7B: Counterbore executor for bounded HoleRecoveryPlan++## Scope++V7B adds bounded execution for `HoleRecoveryPlan` counterbores only:++- `HoleKind.Counterbore`+- `DepthKind.ThroughWithEntryRelief`+- `HostKind.RectangularBox`+- `Axis=Z`+- exactly two cylindrical profile segments:+ - entry relief (larger, shallow)+ - through core (smaller, through)++Non-goals: countersink, blind-hole, generic profile-stack execution, STEP behavior changes, new topology builders.++## Execution route++`HoleRecoveryExecutor.Execute(plan)` now executes hole-family plans.++- Through-hole plans are delegated to `ThroughHoleRecoveryExecutor` via `ThroughHoleRecoveryPlanAdapter`.+- Counterbore plans are validated then executed by exact boolean route:+ 1. `CreateBox`+ 2. `CreateCylinder` for small through core+ 3. `BrepBoolean.Subtract(box, small)`+ 4. `CreateCylinder` for large shallow relief+ 5. `BrepBoolean.Subtract(result, large)`++## Geometry mapping and entry-side convention++Current bounded convention is **entry on host min-Z face** (topological entry face at `hostCenterZ - hostSizeZ/2`), matching the canonical V7A counterbore output.++- Small through cylinder+ - radius = smaller profile segment radius+ - height = `max(ThroughLength, HostSizeZ)`+ - center translation = `ToolTranslation`+- Large counterbore cylinder+ - radius = larger profile segment radius+ - height = shallow segment depth (`DepthEnd - DepthStart`)+ - center z = `entryFaceMinZ + shallowDepth/2`+ - x/y = tool translation x/y++Unsupported entry-side conventions are rejected explicitly.++## Diagnostics++Executor diagnostics include:++- executor started+- no STEP export attempted+- plan kind inspection and acceptance/rejection+- through-hole delegation+- counterbore profile validation+- small tool build + first subtract outcome+- large tool build + second subtract outcome+- body produced++Rematerializer now records that hole-family plan execution was attempted through `HoleRecoveryExecutor`.++## V7C recommendation++Add counterbore STEP smoke coverage without changing exporter behavior; keep execution bounded and exact-BRep first.