Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add bounded blind-hole variant, executor path, and STEP smoke tests

Yuechen Li66893d4df29e
diff --git a/Aetheris.Kernel.Firmament.Tests/BlindHoleVariantAndExecutorTests.cs b/Aetheris.Kernel.Firmament.Tests/BlindHoleVariantAndExecutorTests.cs
new file mode 100644
index 00000000..2b546594
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/BlindHoleVariantAndExecutorTests.cs
@@ -0,0 +1,87 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Step242;
+using Aetheris.Kernel.Firmament.Materializer;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class BlindHoleVariantAndExecutorTests
+{
+ [Fact]
+ public void BlindHoleVariant_AdmitsSimpleBoxBlindHolePlan()
+ {
+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildCanonicalBlindHole()));
+ Assert.True(eval.Admissible);
+ Assert.Contains("selected-variant:BlindHoleVariant", eval.Evidence);
+ var plan = Assert.IsType<HoleRecoveryPlan>(eval.Plan);
+ Assert.Equal(HoleKind.Blind, plan.HoleKind);
+ Assert.Equal(HoleDepthKind.Blind, plan.DepthKind);
+ Assert.Single(plan.ProfileStack);
+ Assert.Contains(plan.ExpectedSurfacePatches, p => p.Role == HoleSurfacePatchRole.CylindricalWall);
+ Assert.Contains(plan.ExpectedSurfacePatches, p => p.Role == HoleSurfacePatchRole.BlindBottomCap);
+ }
+
+ [Fact]
+ public void BlindHoleVariant_RejectsThroughHole()
+ {
+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(new CirSubtractNode(new CirBoxNode(20, 10, 8), new CirCylinderNode(2, 20))));
+ Assert.Contains("selected-variant:ThroughHoleVariant", eval.Evidence);
+ Assert.DoesNotContain("selected-variant:BlindHoleVariant", eval.Evidence);
+ }
+
+ [Fact]
+ public void BlindHoleVariant_RejectsMissOrOutside()
+ {
+ var miss = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirTransformNode(new CirCylinderNode(2, 6), Transform3D.CreateTranslation(new Vector3D(0, 0, 0))));
+ var eval = new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(miss));
+ Assert.False(eval.Admissible);
+ Assert.Contains("UnsupportedMissingEntryFace", string.Join("|", eval.RejectionReasons), StringComparison.Ordinal);
+ }
+
+ [Fact]
+ public void BlindHoleExecutor_CanonicalBlindHole_ProducesBrepBody()
+ {
+ var plan = Assert.IsType<HoleRecoveryPlan>(new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildCanonicalBlindHole())).Plan);
+ var result = HoleRecoveryExecutor.Execute(plan);
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, result.Status);
+ Assert.NotNull(result.Body);
+ Assert.Contains(result.Diagnostics, d => d.Contains("Blind cylinder constructed", StringComparison.Ordinal));
+ Assert.Contains(result.Diagnostics, d => d.Contains("Blind subtract succeeded", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void BlindHoleStepSmoke_CanonicalBlindHole_ExportsStep()
+ {
+ var plan = Assert.IsType<HoleRecoveryPlan>(new HoleRecoveryPolicy().Evaluate(new FrepMaterializerContext(BuildCanonicalBlindHole())).Plan);
+ var execution = HoleRecoveryExecutor.Execute(plan);
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, execution.Status);
+ var step = Step242Exporter.ExportBody(execution.Body!, new Step242ExportOptions { ProductName = "v8-blind-hole" });
+ Assert.True(step.IsSuccess, string.Join(" | ", step.Diagnostics.Select(d => d.Message)));
+ Assert.Contains("ISO-10303-21", step.Value, StringComparison.Ordinal);
+ Assert.Contains("MANIFOLD_SOLID_BREP", step.Value, StringComparison.Ordinal);
+ Assert.Contains("ADVANCED_FACE", step.Value, StringComparison.Ordinal);
+ Assert.Contains("CYLINDRICAL_SURFACE", step.Value, StringComparison.Ordinal);
+ Assert.DoesNotContain("BREP_WITH_VOIDS", step.Value, StringComparison.Ordinal);
+ }
+
+ [Fact]
+ public void BlindHole_Rematerializer_ProducesBrepBody()
+ {
+ var result = FrepSemanticRecoveryRematerializer.TryRecover(BuildCanonicalBlindHole());
+ Assert.True(result.Succeeded);
+ Assert.Equal(HoleRecoveryExecutionStatus.Succeeded, result.ExecutionStatus);
+ Assert.NotNull(result.Body);
+ }
+
+ [Fact]
+ public void BlindHole_Unsupported_DoesNotFalseSucceed()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(6, 4));
+ var result = FrepSemanticRecoveryRematerializer.TryRecover(root);
+ Assert.False(result.Succeeded);
+ Assert.Null(result.Body);
+ }
+
+ private static CirNode BuildCanonicalBlindHole()
+ => new CirSubtractNode(new CirBoxNode(20d, 20d, 10d), new CirTransformNode(new CirCylinderNode(2d, 4d), Transform3D.CreateTranslation(new Vector3D(0d, 0d, 3d))));
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs
index 22a564fc..eb3bf54a 100644
--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs
@@ -47,9 +47,15 @@ public static class HoleRecoveryExecutor
return new((HoleRecoveryExecutionStatus)through.Status, through.Body, diagnostics);
}
+ if (plan.HoleKind == HoleKind.Blind && plan.DepthKind == HoleDepthKind.Blind)
+ {
+ diagnostics.Add("Blind-hole plan accepted for bounded execution.");
+ return ExecuteBlind(plan, diagnostics);
+ }
+
if (plan.HoleKind != HoleKind.Counterbore || plan.DepthKind != HoleDepthKind.ThroughWithEntryRelief)
{
- diagnostics.Add("Plan rejected: only bounded counterbore ThroughWithEntryRelief is supported.");
+ diagnostics.Add("Plan rejected: only bounded blind-hole and counterbore are supported.");
return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);
}
@@ -139,6 +145,64 @@ public static class HoleRecoveryExecutor
return new(HoleRecoveryExecutionStatus.Succeeded, secondSubtract.Value, diagnostics);
}
+
+ private static HoleRecoveryExecutionResult ExecuteBlind(HoleRecoveryPlan plan, List<string> diagnostics)
+ {
+ if (plan.HostKind != HoleHostKind.RectangularBox || plan.Axis != HoleAxisKind.Z || plan.ProfileStack.Count != 1)
+ {
+ diagnostics.Add("Blind plan rejected: host/axis/profile mismatch.");
+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);
+ }
+
+ var seg = plan.ProfileStack[0];
+ if (seg.SegmentKind != HoleProfileSegmentKind.Cylindrical)
+ {
+ diagnostics.Add("Blind plan rejected: profile segment must be cylindrical.");
+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);
+ }
+
+ var depth = seg.DepthEnd - seg.DepthStart;
+ if (depth <= Aetheris.Kernel.Core.Numerics.ToleranceContext.Default.Linear)
+ {
+ diagnostics.Add("Blind plan rejected: depth must be positive.");
+ return new(HoleRecoveryExecutionStatus.UnsupportedPlan, null, diagnostics);
+ }
+
+ var boxResult = BrepPrimitives.CreateBox(plan.HostSizeX, plan.HostSizeY, plan.HostSizeZ);
+ if (!boxResult.IsSuccess)
+ {
+ diagnostics.Add("Blind-hole box primitive construction failed.");
+ return new(HoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);
+ }
+
+ var toolResult = BrepPrimitives.CreateCylinder(seg.RadiusStart, depth);
+ if (!toolResult.IsSuccess)
+ {
+ diagnostics.Add("Blind-hole cylinder primitive construction failed.");
+ return new(HoleRecoveryExecutionStatus.PrimitiveConstructionFailed, null, diagnostics);
+ }
+
+ var boxBody = TranslateBody(boxResult.Value, plan.HostTranslation);
+ var entryTopZ = plan.HostTranslation.Z + (plan.HostSizeZ * 0.5d);
+ var entryBottomZ = plan.HostTranslation.Z - (plan.HostSizeZ * 0.5d);
+ var touchTop = Math.Abs((plan.ToolTranslation.Z + (depth * 0.5d)) - entryTopZ) <= Aetheris.Kernel.Core.Numerics.ToleranceContext.Default.Linear;
+ var centerZ = touchTop ? entryTopZ - (depth * 0.5d) : entryBottomZ + (depth * 0.5d);
+ var toolBody = TranslateBody(toolResult.Value, new Vector3D(plan.ToolTranslation.X, plan.ToolTranslation.Y, centerZ));
+ diagnostics.Add($"Blind cylinder constructed with entry side {(touchTop ? "top(+Z)" : "bottom(-Z)")}.");
+
+ var sub = BrepBoolean.Subtract(boxBody, toolBody);
+ diagnostics.Add("Blind subtract invoked.");
+ if (!sub.IsSuccess || sub.Value is null)
+ {
+ diagnostics.Add("Blind subtract failed.");
+ return new(HoleRecoveryExecutionStatus.BooleanFailed, null, diagnostics);
+ }
+
+ diagnostics.Add("Blind subtract succeeded.");
+ diagnostics.Add("Result BRep body produced.");
+ return new(HoleRecoveryExecutionStatus.Succeeded, sub.Value, diagnostics);
+ }
+
private static BrepBody TranslateBody(BrepBody body, Vector3D translation)
=> translation == Vector3D.Zero ? body : FirmamentPrimitiveExecutionTranslation.TranslateBody(body, translation);
}
diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs
index d693cce2..7c9ad2a8 100644
--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPlan.cs
@@ -4,12 +4,12 @@ namespace Aetheris.Kernel.Firmament.Materializer;
public enum HoleHostKind { RectangularBox, Unsupported }
public enum HoleAxisKind { Z, Unsupported }
-public enum HoleKind { Through, Counterbore, Unsupported }
+public enum HoleKind { Through, Blind, Counterbore, Unsupported }
public enum HoleDepthKind { Through, Blind, ThroughWithEntryRelief, Unsupported }
public enum HoleProfileSegmentKind { Cylindrical, Conical, Chamfer, ThreadDeferred, Unsupported }
public enum HoleEntryFeatureKind { Plain, Counterbore, Unsupported }
-public enum HoleExitFeatureKind { Plain, Unsupported }
-public enum HoleSurfacePatchRole { EntryFace, ExitFace, HostRetainedPlanarFaces, CylindricalWall, CounterboreFloorAnnulus, CounterboreWall }
+public enum HoleExitFeatureKind { Plain, ClosedBottom, Unsupported }
+public enum HoleSurfacePatchRole { EntryFace, ExitFace, HostRetainedPlanarFaces, CylindricalWall, BlindBottomCap, CounterboreFloorAnnulus, CounterboreWall }
public enum HoleTrimCurveRole { CircularRimTrim, Deferred }
public sealed record HoleProfileSegment(HoleProfileSegmentKind SegmentKind, double RadiusStart, double RadiusEnd, double DepthStart, double DepthEnd);
diff --git a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs
index 3ccfc05f..427a0f20 100644
--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryPolicy.cs
@@ -21,7 +21,7 @@ public sealed record HoleRecoveryVariantEvaluation(
public sealed class HoleRecoveryPolicy : IFrepMaterializerPolicy
{
private static readonly JudgmentEngine<FrepMaterializerContext> VariantEngine = new();
- private readonly IReadOnlyList<IHoleRecoveryVariant> _variants = [new ThroughHoleVariant(), new CounterboreVariant()];
+ private readonly IReadOnlyList<IHoleRecoveryVariant> _variants = [new ThroughHoleVariant(), new BlindHoleVariant(), new CounterboreVariant()];
public string Name => nameof(HoleRecoveryPolicy);
public FrepMaterializerPolicyEvaluation Evaluate(FrepMaterializerContext context)
@@ -77,6 +77,131 @@ internal sealed class ThroughHoleVariant : IHoleRecoveryVariant
}
+
+
+internal sealed class BlindHoleVariant : IHoleRecoveryVariant
+{
+ private const double Score = 1050d;
+ public string Name => nameof(BlindHoleVariant);
+
+ public HoleRecoveryVariantEvaluation Evaluate(FrepMaterializerContext context)
+ {
+ var recognition = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(context.Root, context.ReplayLog, context.SourceLabel));
+ if (recognition.Success)
+ {
+ return new(Name, false, 0d, null, ["blind-hole", "rectangular-box-host"], ["UnsupportedThroughHole"], ["BlindHoleVariant rejected: recognizer admitted through-hole span."]);
+ }
+
+ if (recognition.Reason is not CirBoxCylinderRecognitionReason.UnsupportedNotThroughHole)
+ {
+ return new(Name, false, 0d, null, ["blind-hole", "rectangular-box-host"], [recognition.Diagnostic, $"recognizer-reason:{recognition.Reason}"], recognition.Diagnostics);
+ }
+
+ if (!TryBuildBlindPlan(context.Root, out var plan, out var diagnostics, out var rejection))
+ {
+ return new(Name, false, 0d, null, ["blind-hole", "rectangular-box-host"], [rejection], diagnostics);
+ }
+
+ var evidence = new List<string> { "blind-hole", "rectangular-box-host", "cylindrical-profile-segment", "strict-clearance", "z-axis", "closed-bottom" };
+ return new(Name, true, Score, plan, evidence, Array.Empty<string>(), diagnostics);
+ }
+
+ private static bool TryBuildBlindPlan(CirNode root, out HoleRecoveryPlan plan, out List<string> diagnostics, out string rejection)
+ {
+ diagnostics = ["BlindHoleVariant evaluated."];
+ rejection = string.Empty;
+ plan = null!;
+ if (root is not CirSubtractNode subtract)
+ {
+ rejection = "UnsupportedRootNotSubtract";
+ diagnostics.Add("Blind-hole requires Subtract(Box, Cylinder). ");
+ return false;
+ }
+
+ if (subtract.Left is CirSubtractNode or CirUnionNode or CirIntersectNode || subtract.Right is CirSubtractNode or CirUnionNode or CirIntersectNode)
+ {
+ rejection = "UnsupportedNestedOrComposite";
+ diagnostics.Add("Nested/composite booleans are unsupported for blind-hole V8.");
+ return false;
+ }
+
+ if (!CounterboreVariant.TryUnwrapTranslation(subtract.Left, out var left, out var hostT) || left is not CirBoxNode box)
+ {
+ rejection = "UnsupportedHostNotBoxOrTransform";
+ diagnostics.Add("Blind-hole host must be box with translation-only transform.");
+ return false;
+ }
+
+ if (!CounterboreVariant.TryUnwrapTranslation(subtract.Right, out var right, out var toolT) || right is not CirCylinderNode cyl)
+ {
+ rejection = "UnsupportedToolNotCylinderOrTransform";
+ diagnostics.Add("Blind-hole tool must be cylinder with translation-only transform.");
+ return false;
+ }
+
+ var tol = Aetheris.Kernel.Core.Numerics.ToleranceContext.Default.Linear;
+ var boxMinZ = hostT.Z - (box.Depth * 0.5d);
+ var boxMaxZ = hostT.Z + (box.Depth * 0.5d);
+ var cylMinZ = toolT.Z - (cyl.Height * 0.5d);
+ var cylMaxZ = toolT.Z + (cyl.Height * 0.5d);
+
+ var entersTop = Math.Abs(cylMaxZ - boxMaxZ) <= tol;
+ var entersBottom = Math.Abs(cylMinZ - boxMinZ) <= tol;
+ if (!entersTop && !entersBottom)
+ {
+ rejection = "UnsupportedMissingEntryFace";
+ diagnostics.Add("Blind-hole cylinder must intersect exactly one entry face.");
+ return false;
+ }
+
+ if (entersTop && entersBottom)
+ {
+ rejection = "UnsupportedThroughFullDepth";
+ diagnostics.Add("Blind-hole cylinder intersects both entry faces (through-hole). ");
+ return false;
+ }
+
+ var bottomInside = entersTop ? (cylMinZ > boxMinZ + tol) : (cylMaxZ < boxMaxZ - tol);
+ if (!bottomInside)
+ {
+ rejection = "UnsupportedBottomOutsideHost";
+ diagnostics.Add("Blind-hole bottom cap is outside host bounds.");
+ return false;
+ }
+
+ var halfW = box.Width * 0.5d;
+ var halfH = box.Height * 0.5d;
+ var dx = toolT.X - hostT.X;
+ var dy = toolT.Y - hostT.Y;
+ var cxm = dx + halfW - cyl.Radius;
+ var cxp = halfW - dx - cyl.Radius;
+ var cym = dy + halfH - cyl.Radius;
+ var cyp = halfH - dy - cyl.Radius;
+ if (cxm <= tol || cxp <= tol || cym <= tol || cyp <= tol)
+ {
+ rejection = "UnsupportedTangentOrOutsideClearance";
+ diagnostics.Add("Blind-hole cylinder radius must satisfy strict XY clearance.");
+ return false;
+ }
+
+ var depth = entersTop ? (boxMaxZ - cylMinZ) : (cylMaxZ - boxMinZ);
+ diagnostics.Add($"Blind entry face detected: {(entersTop ? "Top(+Z)" : "Bottom(-Z)")}.");
+ diagnostics.Add($"Blind depth computed: {depth:R}.");
+ diagnostics.Add("Blind-hole plan produced.");
+
+ plan = new HoleRecoveryPlan(HoleHostKind.RectangularBox, HoleAxisKind.Z, HoleKind.Blind, HoleDepthKind.Blind, HoleEntryFeatureKind.Plain, HoleExitFeatureKind.ClosedBottom,
+ depth, box.Width, box.Height, box.Depth, hostT, toolT,
+ [new(HoleProfileSegmentKind.Cylindrical, cyl.Radius, cyl.Radius, 0d, depth)],
+ [new(HoleSurfacePatchRole.EntryFace, "Cylinder intersects one host entry face with circular profile."),
+ new(HoleSurfacePatchRole.HostRetainedPlanarFaces, "Host planar faces are retained after blind-hole subtraction."),
+ new(HoleSurfacePatchRole.CylindricalWall, "One cylindrical blind wall patch is expected."),
+ new(HoleSurfacePatchRole.BlindBottomCap, "One circular blind bottom cap patch is expected.")],
+ [new(HoleTrimCurveRole.CircularRimTrim, "Circular trims on entry rim and blind bottom are expected.")],
+ FrepMaterializerCapability.ExactBRep,
+ diagnostics.ToArray());
+ return true;
+ }
+}
internal sealed class CounterboreVariant : IHoleRecoveryVariant
{
private const double Score = 1100d;
@@ -170,7 +295,7 @@ internal sealed class CounterboreVariant : IHoleRecoveryVariant
return new(Name, true, Score, plan, evidence, Array.Empty<string>(), ["CounterboreVariant admitted canonical nested subtract pattern."]);
}
- private static bool TryUnwrapTranslation(Aetheris.Kernel.Core.Cir.CirNode node, out Aetheris.Kernel.Core.Cir.CirNode unwrapped, out Aetheris.Kernel.Core.Math.Vector3D translation)
+ internal static bool TryUnwrapTranslation(Aetheris.Kernel.Core.Cir.CirNode node, out Aetheris.Kernel.Core.Cir.CirNode unwrapped, out Aetheris.Kernel.Core.Math.Vector3D translation)
{
unwrapped = node;
translation = Aetheris.Kernel.Core.Math.Vector3D.Zero;
diff --git a/docs/cir-recovery-v8-blind-hole-variant-executor-step.md b/docs/cir-recovery-v8-blind-hole-variant-executor-step.md
new file mode 100644
index 00000000..16e5d47f
--- /dev/null
+++ b/docs/cir-recovery-v8-blind-hole-variant-executor-step.md
@@ -0,0 +1,70 @@
+# CIR-RECOVERY-V8: bounded blind-hole variant + executor + STEP smoke
+
+## Scope
+
+Supported bounded CIR shape (after optional identity/translation wrappers):
+
+- `Subtract(Box, Cylinder)`
+- box host only
+- cylinder tool only
+- Z-axis canonical orientation
+- translation-only transforms
+- cylinder intersects exactly one host Z face and terminates inside host (blind bottom inside)
+- strict XY clearance (no tangent/grazing)
+
+## Semantics
+
+Admitted cases produce `HoleRecoveryPlan` with:
+
+- `HoleKind = Blind`
+- `DepthKind = Blind`
+- `EntryFeature = Plain`
+- `ExitFeature = ClosedBottom`
+- single cylindrical profile segment from entry to blind bottom
+- expected patches include retained host faces, cylindrical blind wall, and blind bottom cap
+- expected trims include circular entry/bottom trims
+
+## Execution
+
+`HoleRecoveryExecutor` now supports bounded blind-hole plans directly:
+
+1. `BrepPrimitives.CreateBox`
+2. `BrepPrimitives.CreateCylinder(radius, depth)`
+3. position tool by entry-side convention inferred from plan (`top(+Z)` or `bottom(-Z)`)
+4. `BrepBoolean.Subtract`
+
+No generic profile-stack executor was added.
+
+## STEP smoke
+
+Smoke validates export via existing API:
+
+- `Step242Exporter.ExportBody(BrepBody, Step242ExportOptions?)`
+- expected markers: `ISO-10303-21`, `MANIFOLD_SOLID_BREP`, `ADVANCED_FACE`, `CYLINDRICAL_SURFACE`
+- `BREP_WITH_VOIDS` is not expected for this open blind depression
+
+Exporter behavior is unchanged.
+
+## Rejections
+
+Stable rejection/defer diagnostics remain for:
+
+- non-subtract, nested/composite booleans
+- non-box host / non-cylinder tool
+- unsupported transforms
+- through-hole spans
+- missing entry-face intersection
+- bottom outside host
+- tangent/grazing/outside XY radius clearance
+
+## Non-goals kept
+
+- no countersink work
+- no counterbore changes
+- no generic Boolean recovery
+- no STEP exporter behavior changes
+- no public CLI/API surface expansion
+
+## Recommended V9
+
+Generalize bounded blind-hole coverage to additional entry-side and transform compositions with explicit admissibility/score tuning and shape-lab updates before any generic stack executor work.