Skip to content

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.cs
index edcb3560..a1d22837 100644
--- a/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/CirBrepMaterializerTests.cs
@@ -21,6 +21,23 @@ public sealed class CirBrepMaterializerTests
Assert.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 CirBrepMaterializerTests
Assert.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 CirBrepMaterializerTests
Assert.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.cs
index 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 FirmamentStepExporterTests
PrimitiveExecutionResult = 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.cs
index 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 CirBrepMaterializer
if (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 CirBrepMaterializer
var 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 CirBrepMaterializer
return 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.md
new file mode 100644
index 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.