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.csnew file mode 100644index 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.csindex 22a564fc..eb3bf54a 100644--- a/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs+++ b/Aetheris.Kernel.Firmament/Materializer/HoleRecoveryExecutor.cs@@ -47,9 +47,15 @@ public static class HoleRecoveryExecutorreturn 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 HoleRecoveryExecutorreturn 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.csindex 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.csindex 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 : IHoleRecoveryVariantreturn 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.mdnew file mode 100644index 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.