Skip to content

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.cs
new file mode 100644
index 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.cs
index 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.cs
index 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 FrepSemanticRecoveryRematerializer
if (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.cs
new file mode 100644
index 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.md
new file mode 100644
index 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.