Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add bounded CIR materializer support for subtract(box,box)
Yuechen Li2d6755345834
diff --git a/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.cs b/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.csindex edcb3560..a1d22837 100644--- a/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.cs@@ -21,6 +21,23 @@ public sealed class CirBrepMaterializerTestsAssert.Equal(CirBrepMaterializer.BoxMinusCylinderPattern, result.PatternName);}++ [Fact]+ public void CirMaterializer_BoxMinusBox_Succeeds()+ {+ var root = new CirSubtractNode(+ new CirTransformNode(new CirBoxNode(20, 20, 10), Transform3D.CreateTranslation(new Vector3D(0, 0, 5))),+ new CirTransformNode(new CirBoxNode(6, 20, 10), Transform3D.CreateTranslation(new Vector3D(7, 0, 5))));++ var result = CirBrepMaterializer.TryMaterialize(root);++ Assert.True(result.IsSuccess);+ Assert.NotNull(result.Body);+ Assert.Equal(CirBrepMaterializer.BoxMinusBoxPattern, result.PatternName);+ Assert.Null(result.UnsupportedReason);+ Assert.Empty(result.Diagnostics);+ }+[Fact]public void CirMaterializer_UnsupportedPattern_FailsClearly(){@@ -29,7 +46,7 @@ public sealed class CirBrepMaterializerTestsAssert.False(result.IsSuccess);Assert.Null(result.Body);- Assert.Equal("rhs-not-cylinder", result.UnsupportedReason);+ Assert.Equal("rhs-unsupported", result.UnsupportedReason);}[Fact]@@ -46,6 +63,22 @@ public sealed class CirBrepMaterializerTestsAssert.Contains(remat.Value.TransitionEvents, e => e.FromMode == NativeGeometryExecutionMode.CirOnly && e.ToMode == NativeGeometryExecutionMode.BRepActive);}++ [Fact]+ public void CirOnly_BoxMinusBox_RematerializesToBRepActive()+ {+ var plan = BuildBoxMinusBoxPlan();+ var state = new NativeGeometryState(NativeGeometryExecutionMode.CirOnly, NativeGeometryMaterializationAuthority.PendingRematerialization, null, "notch", new NativeGeometryReplayLog([]), [], new NativeGeometryCirMirrorState(CirMirrorStatus.NotAttempted, null, []));++ var remat = NativeGeometryRematerializer.TryRematerialize(plan, state);++ Assert.True(remat.IsSuccess);+ Assert.Equal(NativeGeometryExecutionMode.BRepActive, remat.Value.ExecutionMode);+ Assert.Equal(NativeGeometryMaterializationAuthority.BRepAuthoritative, remat.Value.MaterializationAuthority);+ Assert.NotNull(remat.Value.MaterializedBody);+ Assert.Contains(remat.Value.TransitionEvents, e => e.FromMode == NativeGeometryExecutionMode.CirOnly && e.ToMode == NativeGeometryExecutionMode.BRepActive);+ }+private static FirmamentPrimitiveLoweringPlan BuildBoxMinusCylinderPlan(){var primitives = new[]@@ -58,4 +91,19 @@ public sealed class CirBrepMaterializerTests};return new FirmamentPrimitiveLoweringPlan(primitives, booleans, []);}+++ private static FirmamentPrimitiveLoweringPlan BuildBoxMinusBoxPlan()+ {+ var primitives = new[]+ {+ new FirmamentLoweredPrimitive(0, "base", FirmamentLoweredPrimitiveKind.Box, new FirmamentLoweredBoxParameters(20,20,10), null)+ };+ var booleans = new[]+ {+ new FirmamentLoweredBoolean(1, "notch", FirmamentLoweredBooleanKind.Subtract, "from", "base", new FirmamentLoweredToolOp("box", new Dictionary<string,string>{{"op","box"},{"size","[6,20,10]"}}, "op box size=[6,20,10]"), new FirmamentLoweredPlacement(new FirmamentLoweredPlacementOriginAnchor(), true, new double[] { 7, 0, 0 }, null, null, null, []))+ };+ return new FirmamentPrimitiveLoweringPlan(primitives, booleans, []);+ }+}diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.csindex cf95c685..0b97b577 100644--- a/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentStepExporterTests.cs@@ -1,3 +1,4 @@+using System.Linq;using Aetheris.Kernel.Core.Step242;using Aetheris.Kernel.Firmament.Execution;@@ -250,10 +251,73 @@ public sealed class FirmamentStepExporterTestsPrimitiveExecutionResult = execution with { NativeGeometryState = cirOnlyState }};+ var export = FirmamentStepExporter.Export(cirOnlyArtifact);+ Assert.True(export.IsSuccess, string.Join(" | ", export.Diagnostics.Select(d => d.Message)));+ Assert.Contains("PRODUCT_DEFINITION", export.Value.StepText, StringComparison.Ordinal);+ }+++ [Fact]+ public void CirOnly_BoxMinusBox_ExportSucceedsAfterRematerialization()+ {+ var compiler = new FirmamentCompiler();+ var source = """+firmament:+ version: 1++model:+ name: cir_box_box_remat+ units: mm++ops[2]:+ -+ op: box+ id: base+ size[3]:+ 20+ 20+ 10++ -+ op: subtract+ id: carved+ from: base+ with:+ op: box+ size[3]:+ 6+ 20+ 10+ place:+ on: origin+ offset[3]:+ 7+ 0+ 0+""";+ var compiled = compiler.Compile(new FirmamentCompileRequest(new FirmamentSourceDocument(source)));+ Assert.True(compiled.Compilation.IsSuccess);++ var artifact = compiled.Compilation.Value;+ var execution = artifact.PrimitiveExecutionResult!;+ var cirOnlyState = execution.NativeGeometryState with+ {+ ExecutionMode = NativeGeometryExecutionMode.CirOnly,+ MaterializationAuthority = NativeGeometryMaterializationAuthority.PendingRematerialization,+ MaterializedBody = null,+ CirIntentRootReference = "carved"+ };++ var cirOnlyArtifact = artifact with+ {+ PrimitiveExecutionResult = execution with { NativeGeometryState = cirOnlyState }+ };+var export = FirmamentStepExporter.Export(cirOnlyArtifact);Assert.True(export.IsSuccess);Assert.Contains("PRODUCT_DEFINITION", export.Value.StepText, StringComparison.Ordinal);}+[Fact]public void Export_CirOnlyState_Fails_Clearly_Without_Materializer(){diff --git a/Aetheris.Kernel.Firmament/Execution/CirBrepMaterializer.cs b/Aetheris.Kernel.Firmament/Execution/CirBrepMaterializer.csindex 3e0c9363..0f110051 100644--- a/Aetheris.Kernel.Firmament/Execution/CirBrepMaterializer.cs+++ b/Aetheris.Kernel.Firmament/Execution/CirBrepMaterializer.cs@@ -9,6 +9,7 @@ namespace Aetheris.Kernel.Firmament.Execution;internal static class CirBrepMaterializer{internal const string BoxMinusCylinderPattern = "subtract(box,cylinder)";+ internal const string BoxMinusBoxPattern = "subtract(box,box)";internal static CirBrepMaterializationResult TryMaterialize(CirNode root){@@ -16,29 +17,38 @@ internal static class CirBrepMaterializerif (root is not CirSubtractNode subtract){- return Unsupported("Root CIR node must be subtract.", "root-not-subtract");+ return Unsupported(BoxMinusCylinderPattern, "Root CIR node must be subtract.", "root-not-subtract");}- if (!TryUnwrapTranslation(subtract.Left, out var boxNode, out var boxTranslation) || boxNode is not CirBoxNode box)+ if (!TryUnwrapTranslation(subtract.Left, out var leftNode, out var leftTranslation) || leftNode is not CirBoxNode leftBox){- return Unsupported("Subtract lhs must be a translated/untranslated box node.", "lhs-not-box");+ return Unsupported(BoxMinusCylinderPattern, "Subtract lhs must be a translated/untranslated box node.", "lhs-not-box");}- if (!TryUnwrapTranslation(subtract.Right, out var cylinderNode, out var cylinderTranslation) || cylinderNode is not CirCylinderNode cylinder)+ return subtract.Right switch{- return Unsupported("Subtract rhs must be a translated/untranslated cylinder node.", "rhs-not-cylinder");- }+ CirCylinderNode cylinder => TryMaterializeBoxMinusCylinder(leftBox, leftTranslation, cylinder, Vector3D.Zero),+ CirTransformNode transformedCylinder when TryUnwrapTranslation(transformedCylinder, out var cylinderNode, out var cylinderTranslation) && cylinderNode is CirCylinderNode cylinder+ => TryMaterializeBoxMinusCylinder(leftBox, leftTranslation, cylinder, cylinderTranslation),+ CirBoxNode rightBox => TryMaterializeBoxMinusBox(leftBox, leftTranslation, rightBox, Vector3D.Zero),+ CirTransformNode transformedBox when TryUnwrapTranslation(transformedBox, out var rightNode, out var rightTranslation) && rightNode is CirBoxNode rightBox+ => TryMaterializeBoxMinusBox(leftBox, leftTranslation, rightBox, rightTranslation),+ _ => Unsupported(BoxMinusCylinderPattern, "Subtract rhs must be a translated/untranslated cylinder or box node.", "rhs-unsupported")+ };+ }+ private static CirBrepMaterializationResult TryMaterializeBoxMinusCylinder(CirBoxNode box, Vector3D boxTranslation, CirCylinderNode cylinder, Vector3D cylinderTranslation)+ {var boxResult = BrepPrimitives.CreateBox(box.Width, box.Height, box.Depth);if (!boxResult.IsSuccess){- return Failed("Failed to create BRep box primitive.", boxResult.Diagnostics);+ return Failed(BoxMinusCylinderPattern, "Failed to create BRep box primitive.", boxResult.Diagnostics);}var cylinderResult = BrepPrimitives.CreateCylinder(cylinder.Radius, cylinder.Height);if (!cylinderResult.IsSuccess){- return Failed("Failed to create BRep cylinder primitive.", cylinderResult.Diagnostics);+ return Failed(BoxMinusCylinderPattern, "Failed to create BRep cylinder primitive.", cylinderResult.Diagnostics);}var placedBox = TranslateBody(boxResult.Value, boxTranslation);@@ -46,28 +56,57 @@ internal static class CirBrepMaterializervar subtractResult = BrepBoolean.Subtract(placedBox, placedCylinder);if (!subtractResult.IsSuccess){- return Failed("Failed to boolean subtract box/cylinder during CIR rematerialization.", subtractResult.Diagnostics);+ return Failed(BoxMinusCylinderPattern, "Failed to boolean subtract box/cylinder during CIR rematerialization.", subtractResult.Diagnostics);}return new CirBrepMaterializationResult(true, subtractResult.Value, BoxMinusCylinderPattern, null, [], "matched-box-minus-cylinder");}+ private static CirBrepMaterializationResult TryMaterializeBoxMinusBox(CirBoxNode leftBox, Vector3D leftTranslation, CirBoxNode rightBox, Vector3D rightTranslation)+ {+ var leftBoxResult = BrepPrimitives.CreateBox(leftBox.Width, leftBox.Height, leftBox.Depth);+ if (!leftBoxResult.IsSuccess)+ {+ return Failed(BoxMinusBoxPattern, "Failed to create lhs BRep box primitive.", leftBoxResult.Diagnostics);+ }++ var rightBoxResult = BrepPrimitives.CreateBox(rightBox.Width, rightBox.Height, rightBox.Depth);+ if (!rightBoxResult.IsSuccess)+ {+ return Failed(BoxMinusBoxPattern, "Failed to create rhs BRep box primitive.", rightBoxResult.Diagnostics);+ }++ var placedLeft = TranslateBody(leftBoxResult.Value, leftTranslation);+ var placedRight = TranslateBody(rightBoxResult.Value, rightTranslation);+ var subtractResult = BrepBoolean.Subtract(placedLeft, placedRight);+ if (!subtractResult.IsSuccess)+ {+ return Failed(BoxMinusBoxPattern, "Failed to boolean subtract box/box during CIR rematerialization.", subtractResult.Diagnostics);+ }++ return new CirBrepMaterializationResult(true, subtractResult.Value, BoxMinusBoxPattern, null, [], "matched-box-minus-box");+ }+private static bool TryUnwrapTranslation(CirNode node, out CirNode unwrapped, out Vector3D translation){- if (node is CirTransformNode transformNode)+ var total = Vector3D.Zero;+ var current = node;++ while (current is CirTransformNode transformNode){- if (!TryExtractPureTranslation(transformNode.Transform, out translation))+ if (!TryExtractPureTranslation(transformNode.Transform, out var localTranslation)){unwrapped = node;+ translation = Vector3D.Zero;return false;}- unwrapped = transformNode.Child;- return true;+ total += localTranslation;+ current = transformNode.Child;}- translation = Vector3D.Zero;- unwrapped = node;+ translation = total;+ unwrapped = current;return true;}@@ -111,11 +150,11 @@ internal static class CirBrepMaterializerreturn FirmamentPrimitiveExecutionTranslation.TranslateBody(body, translation);}- private static CirBrepMaterializationResult Unsupported(string diagnostic, string reason)- => new(false, null, BoxMinusCylinderPattern, reason, [], diagnostic);+ private static CirBrepMaterializationResult Unsupported(string pattern, string diagnostic, string reason)+ => new(false, null, pattern, reason, [], diagnostic);- private static CirBrepMaterializationResult Failed(string diagnostic, IReadOnlyList<Core.Diagnostics.KernelDiagnostic> diagnostics)- => new(false, null, BoxMinusCylinderPattern, "materialize-failed", diagnostics, diagnostic);+ private static CirBrepMaterializationResult Failed(string pattern, string diagnostic, IReadOnlyList<Core.Diagnostics.KernelDiagnostic> diagnostics)+ => new(false, null, pattern, "materialize-failed", diagnostics, diagnostic);}internal sealed record CirBrepMaterializationResult(diff --git a/docs/cir-f5-second-materializer.md b/docs/cir-f5-second-materializer.mdnew file mode 100644index 00000000..c5170836--- /dev/null+++ b/docs/cir-f5-second-materializer.md@@ -0,0 +1,55 @@+# CIR-F5 second bounded CIR→BRep materializer checkpoint++## Chosen pattern++CIR-F5 adds exactly one new pattern: `subtract(box,box)` (box minus box), while preserving CIR-F4 support for `subtract(box,cylinder)`.++## Supported shape++Supported:+- root `CirSubtractNode`+- lhs: translated/untranslated `CirBoxNode`+- rhs: translated/untranslated `CirBoxNode` or `CirCylinderNode`+- pure-translation `CirTransformNode` wrappers only++## Explicitly unsupported++Unsupported (clear diagnostic path):+- non-subtract roots+- lhs non-box+- rhs non-box/non-cylinder+- non-translation transforms+- nested/general CIR trees+- union/intersect materialization+- assemblies and generated topology naming++## Materialization strategy++No new geometry kernel logic was added.++`subtract(box,box)` rematerialization is implemented by reusing existing bounded BRep primitives and booleans:+- `BrepPrimitives.CreateBox(...)` for lhs+- `BrepPrimitives.CreateBox(...)` for rhs+- `BrepBoolean.Subtract(...)` for final exact BRep++`subtract(box,cylinder)` remains on the existing path:+- `BrepPrimitives.CreateBox(...)`+- `BrepPrimitives.CreateCylinder(...)`+- `BrepBoolean.Subtract(...)`++## Runtime rematerialization and export++`NativeGeometryRematerializer.TryRematerialize(...)` behavior is unchanged:+- accepts `CirOnly` state,+- lowers CIR from replay/lowering plan,+- invokes bounded `CirBrepMaterializer`,+- on success transitions to `BRepActive` + `BRepAuthoritative` with transition event.++`FirmamentStepExporter` behavior is unchanged in policy:+- for `CirOnly`, it attempts bounded rematerialization first,+- exports through existing STEP242 path on success,+- fails clearly when no bounded materializer match exists.++## F6 recommendation++Add one additional bounded subtract family with explicit recognizer naming and strict diagnostics (for example a constrained translated prism tool) while keeping the matcher list explicit and non-generic.