Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

M2: add bounded principal-plane pattern_mirror support

Yuechen Li17c19c0142c2
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentBuildAndExportTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentBuildAndExportTests.cs
index dd58db67..f7c09ee2 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentBuildAndExportTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentBuildAndExportTests.cs
@@ -258,6 +258,18 @@ public sealed class FirmamentBuildAndExportTests
"subtract");
}
+ [Fact]
+ public void Run_P2MirrorHolePairExample_Writes_Default_Export_Artifact()
+ {
+ AssertExampleBuildAndExport(
+ "testdata/firmament/examples/p2_mirror_hole_pair.firmament",
+ "p2_mirror_hole_pair.step",
+ "hole_cut_left__mir_yz",
+ 2,
+ "boolean",
+ "subtract");
+ }
+
[Fact]
public void Run_FrictionLabBlindHoleMountBlock_NowBuildsAndExports()
{
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentDocumentCoherenceValidationTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentDocumentCoherenceValidationTests.cs
index bdb2b6e5..6c435afe 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentDocumentCoherenceValidationTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentDocumentCoherenceValidationTests.cs
@@ -62,6 +62,30 @@ public sealed class FirmamentDocumentCoherenceValidationTests
diagnostic.Message);
}
+ [Fact]
+ public void Compiler_Rejects_PatternMirror_With_Unsupported_Plane()
+ {
+ var result = CompileFixture("testdata/firmament/fixtures/p3_invalid_pattern_mirror_plane.firmament");
+
+ Assert.False(result.Compilation.IsSuccess);
+ var diagnostic = Assert.Single(result.Compilation.Diagnostics);
+ Assert.Equal(
+ $"[{FirmamentDiagnosticCodes.PatternInvalidFieldValue.Value}] Pattern op 'pattern_mirror' at index 2 has invalid field 'plane' value; supported planes are 'xy', 'xz', and 'yz'.",
+ diagnostic.Message);
+ }
+
+ [Fact]
+ public void Compiler_Rejects_PatternMirror_With_NonOrigin_Source_Placement()
+ {
+ var result = CompileFixture("testdata/firmament/fixtures/p3_invalid_pattern_mirror_source_placement.firmament");
+
+ Assert.False(result.Compilation.IsSuccess);
+ var diagnostic = Assert.Single(result.Compilation.Diagnostics);
+ Assert.Equal(
+ $"[{FirmamentDiagnosticCodes.PatternInvalidFieldValue.Value}] Pattern op 'pattern_mirror' at index 2 uses unsupported source feature id 'hole_cut'; only origin-anchored source placements are mirrorable in M2.",
+ diagnostic.Message);
+ }
+
[Theory]
[InlineData("testdata/firmament/fixtures/m2a-invalid-add-to-missing-id.firmament", "add", "to", "missing")]
[InlineData("testdata/firmament/fixtures/m2a-invalid-subtract-from-missing-id.firmament", "subtract", "from", "missing")]
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs
index 0a48c79c..2df72b46 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentExamplePackSmokeTests.cs
@@ -19,6 +19,7 @@ public sealed class FirmamentExamplePackSmokeTests
"testdata/firmament/examples/boolean_two_cylinder_holes_basic.firmament",
"testdata/firmament/examples/boolean_cylinder_cone_holes_basic.firmament",
"testdata/firmament/examples/boolean_box_sphere_cavity_basic.firmament",
+ "testdata/firmament/examples/p2_mirror_hole_pair.firmament",
"testdata/firmament/examples/placed_primitive.firmament",
"testdata/firmament/examples/schema_box_basic.firmament"
];
@@ -51,6 +52,7 @@ public sealed class FirmamentExamplePackSmokeTests
[InlineData("testdata/firmament/examples/boolean_two_cylinder_holes_basic.firmament", "hole_b", 2, "boolean", "subtract")]
[InlineData("testdata/firmament/examples/boolean_cylinder_cone_holes_basic.firmament", "cut_b", 2, "boolean", "subtract")]
[InlineData("testdata/firmament/examples/boolean_box_sphere_cavity_basic.firmament", "cavity", 1, "boolean", "subtract")]
+ [InlineData("testdata/firmament/examples/p2_mirror_hole_pair.firmament", "hole_cut_left__mir_yz", 2, "boolean", "subtract")]
[InlineData("testdata/firmament/examples/placed_primitive.firmament", "post", 1, "primitive", "cylinder")]
[InlineData("testdata/firmament/examples/schema_box_basic.firmament", "schema_box", 0, "primitive", "box")]
public void ExamplePack_GoldenPath_Examples_Export(string fixturePath, string expectedFeatureId, int expectedOpIndex, string expectedBodyCategory, string expectedFeatureKind)
diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
index f9fd58bd..69bdfa57 100644
--- a/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentPrimitiveExecutor.cs
@@ -231,7 +231,8 @@ internal static class FirmamentPrimitiveExecutor
private static bool IsPatternGeneratedFeature(string featureId)
=> featureId.Contains("__lin", StringComparison.Ordinal)
- || featureId.Contains("__cir", StringComparison.Ordinal);
+ || featureId.Contains("__cir", StringComparison.Ordinal)
+ || featureId.Contains("__mir_", StringComparison.Ordinal);
private static KernelResult<FirmamentExecutedPrimitiveBodies> ExecutePrimitive(FirmamentLoweredPrimitive primitive, IReadOnlyDictionary<string, BrepBody> publishedBodies)
{
diff --git a/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs b/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs
index 7ba8bbea..5457d45f 100644
--- a/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs
+++ b/Aetheris.Kernel.Firmament/Formatting/FirmamentCanonicalFormatter.cs
@@ -164,6 +164,10 @@ internal static class FirmamentCanonicalFormatter
EmitIfPresent(builder, entry.RawFields, emitted, indentLevel, "angle_degrees");
EmitIfPresent(builder, entry.RawFields, emitted, indentLevel, "angle_step_degrees");
break;
+ case FirmamentKnownOpKind.PatternMirror:
+ EmitIfPresent(builder, entry.RawFields, emitted, indentLevel, "source");
+ EmitIfPresent(builder, entry.RawFields, emitted, indentLevel, "plane");
+ break;
}
foreach (var pair in entry.RawFields)
diff --git a/Aetheris.Kernel.Firmament/ParsedModel/FirmamentKnownOpKind.cs b/Aetheris.Kernel.Firmament/ParsedModel/FirmamentKnownOpKind.cs
index cfcff5a2..9e1fba49 100644
--- a/Aetheris.Kernel.Firmament/ParsedModel/FirmamentKnownOpKind.cs
+++ b/Aetheris.Kernel.Firmament/ParsedModel/FirmamentKnownOpKind.cs
@@ -14,7 +14,8 @@ public enum FirmamentKnownOpKind
ExpectSelectable,
ExpectManifold,
PatternLinear,
- PatternCircular
+ PatternCircular,
+ PatternMirror
}
internal static class FirmamentKnownOpKinds
@@ -34,7 +35,8 @@ internal static class FirmamentKnownOpKinds
["expect_selectable"] = FirmamentKnownOpKind.ExpectSelectable,
["expect_manifold"] = FirmamentKnownOpKind.ExpectManifold,
["pattern_linear"] = FirmamentKnownOpKind.PatternLinear,
- ["pattern_circular"] = FirmamentKnownOpKind.PatternCircular
+ ["pattern_circular"] = FirmamentKnownOpKind.PatternCircular,
+ ["pattern_mirror"] = FirmamentKnownOpKind.PatternMirror
};
public static bool TryParse(string opName, out FirmamentKnownOpKind kind) =>
@@ -56,6 +58,7 @@ internal static class FirmamentKnownOpKinds
FirmamentKnownOpKind.ExpectManifold => FirmamentOpFamily.Validation,
FirmamentKnownOpKind.PatternLinear => FirmamentOpFamily.Pattern,
FirmamentKnownOpKind.PatternCircular => FirmamentOpFamily.Pattern,
+ FirmamentKnownOpKind.PatternMirror => FirmamentOpFamily.Pattern,
_ => throw new ArgumentOutOfRangeException(nameof(kind), kind, "Unknown Firmament known op kind.")
};
}
diff --git a/Aetheris.Kernel.Firmament/Validation/FirmamentDocumentCoherenceValidator.cs b/Aetheris.Kernel.Firmament/Validation/FirmamentDocumentCoherenceValidator.cs
index a4829ac5..b5ff0486 100644
--- a/Aetheris.Kernel.Firmament/Validation/FirmamentDocumentCoherenceValidator.cs
+++ b/Aetheris.Kernel.Firmament/Validation/FirmamentDocumentCoherenceValidator.cs
@@ -1,4 +1,5 @@
using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Math;
using Aetheris.Kernel.Core.Results;
using Aetheris.Kernel.Firmament.Diagnostics;
using Aetheris.Kernel.Firmament.ParsedModel;
@@ -132,6 +133,11 @@ internal static class FirmamentDocumentCoherenceValidator
]);
}
+ if (patternEntry.KnownKind == FirmamentKnownOpKind.PatternMirror)
+ {
+ return ExpandMirrorPattern(patternEntry, sourceEntry, opIndex);
+ }
+
if (!int.TryParse(patternEntry.RawFields["count"], NumberStyles.Integer, CultureInfo.InvariantCulture, out var count) || count <= 0)
{
return KernelResult<IReadOnlyList<FirmamentParsedOpEntry>>.Failure([
@@ -319,6 +325,116 @@ internal static class FirmamentDocumentCoherenceValidator
return entry with { RawFields = fields };
}
+ private static KernelResult<IReadOnlyList<FirmamentParsedOpEntry>> ExpandMirrorPattern(
+ FirmamentParsedOpEntry patternEntry,
+ FirmamentParsedOpEntry sourceEntry,
+ int opIndex)
+ {
+ var plane = patternEntry.RawFields["plane"].Trim();
+ var mirroredFeatureId = $"{sourceEntry.RawFields["id"]}__mir_{plane}";
+ if (!TryGetMirrorAxisScale(plane, out var axisScale))
+ {
+ return KernelResult<IReadOnlyList<FirmamentParsedOpEntry>>.Failure([
+ CreateDiagnostic(
+ FirmamentDiagnosticCodes.PatternInvalidFieldValue,
+ $"Pattern op '{patternEntry.OpName}' at index {opIndex} has invalid field 'plane' value; supported planes are 'xy', 'xz', and 'yz'.")
+ ]);
+ }
+
+ if (!TryCreateMirroredPlacement(sourceEntry.Placement, axisScale, out var mirroredPlacement, out var placementFailure))
+ {
+ return KernelResult<IReadOnlyList<FirmamentParsedOpEntry>>.Failure([
+ CreateDiagnostic(
+ FirmamentDiagnosticCodes.PatternInvalidFieldValue,
+ $"Pattern op '{patternEntry.OpName}' at index {opIndex} uses unsupported source feature id '{sourceEntry.RawFields["id"]}'; {placementFailure}.")
+ ]);
+ }
+
+ var mirroredFields = new Dictionary<string, string>(sourceEntry.RawFields, StringComparer.Ordinal)
+ {
+ ["id"] = mirroredFeatureId
+ };
+
+ var mirrored = sourceEntry with
+ {
+ RawFields = mirroredFields,
+ Placement = mirroredPlacement
+ };
+
+ var chainedMirrored = ChainBooleanReferenceIfNeeded(mirrored, sourceEntry.RawFields["id"]);
+ return KernelResult<IReadOnlyList<FirmamentParsedOpEntry>>.Success([chainedMirrored]);
+ }
+
+ private static bool TryGetMirrorAxisScale(string plane, out Vector3D axisScale)
+ {
+ axisScale = plane switch
+ {
+ "xy" => new Vector3D(1d, 1d, -1d),
+ "xz" => new Vector3D(1d, -1d, 1d),
+ "yz" => new Vector3D(-1d, 1d, 1d),
+ _ => Vector3D.Zero
+ };
+
+ return axisScale != Vector3D.Zero;
+ }
+
+ private static bool TryCreateMirroredPlacement(
+ FirmamentParsedPlacement? sourcePlacement,
+ Vector3D axisScale,
+ out FirmamentParsedPlacement mirroredPlacement,
+ out string failureReason)
+ {
+ mirroredPlacement = null!;
+ failureReason = string.Empty;
+
+ if (sourcePlacement is null)
+ {
+ mirroredPlacement = new FirmamentParsedPlacement(
+ new FirmamentParsedPlacementOriginAnchor(),
+ [0d, 0d, 0d],
+ OnFace: null,
+ CenteredOn: null,
+ AroundAxis: null,
+ RadialOffset: null,
+ AngleDegrees: null,
+ UnknownFields: Array.Empty<string>());
+ return true;
+ }
+
+ if (sourcePlacement.On is not FirmamentParsedPlacementOriginAnchor)
+ {
+ failureReason = "only origin-anchored source placements are mirrorable in M2";
+ return false;
+ }
+
+ if (!string.IsNullOrWhiteSpace(sourcePlacement.OnFace)
+ || !string.IsNullOrWhiteSpace(sourcePlacement.CenteredOn)
+ || !string.IsNullOrWhiteSpace(sourcePlacement.AroundAxis)
+ || sourcePlacement.RadialOffset is not null
+ || sourcePlacement.AngleDegrees is not null)
+ {
+ failureReason = "only offset-based source placements are mirrorable in M2";
+ return false;
+ }
+
+ if (sourcePlacement.Offset.Count != 3)
+ {
+ failureReason = "source placement offset must have exactly 3 components";
+ return false;
+ }
+
+ mirroredPlacement = sourcePlacement with
+ {
+ Offset =
+ [
+ sourcePlacement.Offset[0] * axisScale.X,
+ sourcePlacement.Offset[1] * axisScale.Y,
+ sourcePlacement.Offset[2] * axisScale.Z
+ ]
+ };
+ return true;
+ }
+
private static bool TryParseNumericVector(string raw, out IReadOnlyList<double> values)
{
values = Array.Empty<double>();
diff --git a/Aetheris.Kernel.Firmament/Validation/FirmamentPatternRequiredFieldValidator.cs b/Aetheris.Kernel.Firmament/Validation/FirmamentPatternRequiredFieldValidator.cs
index 85f9e723..1ea237e8 100644
--- a/Aetheris.Kernel.Firmament/Validation/FirmamentPatternRequiredFieldValidator.cs
+++ b/Aetheris.Kernel.Firmament/Validation/FirmamentPatternRequiredFieldValidator.cs
@@ -25,6 +25,7 @@ internal static class FirmamentPatternRequiredFieldValidator
{
FirmamentKnownOpKind.PatternLinear => ValidateLinear(entry, index),
FirmamentKnownOpKind.PatternCircular => ValidateCircular(entry, index),
+ FirmamentKnownOpKind.PatternMirror => ValidateMirror(entry, index),
_ => KernelResult<bool>.Success(true)
};
@@ -107,6 +108,27 @@ internal static class FirmamentPatternRequiredFieldValidator
return KernelResult<bool>.Success(true);
}
+ private static KernelResult<bool> ValidateMirror(FirmamentParsedOpEntry entry, int opIndex)
+ {
+ if (!TryGetRequiredScalar(entry, "source", opIndex, out var sourceDiagnostic))
+ {
+ return KernelResult<bool>.Failure([sourceDiagnostic!]);
+ }
+
+ if (!TryGetRequiredScalar(entry, "plane", opIndex, out var planeDiagnostic))
+ {
+ return KernelResult<bool>.Failure([planeDiagnostic!]);
+ }
+
+ var plane = entry.RawFields["plane"].Trim();
+ if (plane is not ("xy" or "xz" or "yz"))
+ {
+ return InvalidFieldValue("plane", opIndex, entry.OpName, "supported planes are 'xy', 'xz', and 'yz'");
+ }
+
+ return KernelResult<bool>.Success(true);
+ }
+
private static KernelResult<bool> ValidatePositiveIntegerField(FirmamentParsedOpEntry entry, string fieldName, int opIndex)
{
if (!entry.RawFields.TryGetValue(fieldName, out var raw) || string.IsNullOrWhiteSpace(raw))
diff --git a/testdata/firmament/examples/README.md b/testdata/firmament/examples/README.md
index b6bf3e92..5aa20d15 100644
--- a/testdata/firmament/examples/README.md
+++ b/testdata/firmament/examples/README.md
@@ -27,6 +27,7 @@ Other combinations may fail and are intentionally not supported yet.
- `p1_bracket_rib_on_face_semantic.firmament` — minimal semantic placement subset example using `place.on_face` for bracket rib authoring ergonomics.
- `p2_linear_hole_row.firmament` — minimal built-in `pattern_linear` example for repeated hole rows.
- `p2_flange_bolt_circle_pattern.firmament` — minimal built-in `pattern_circular` bolt-circle example for flange holes.
+- `p2_mirror_hole_pair.firmament` — bounded `pattern_mirror` example for principal-plane mirrored hole placement.
- `schema_box_basic.firmament` — minimal schema-present export example showing schema presence without changing export body semantics; helper export path: `testdata/firmament/exports/schema_box_basic.step`.
Unsupported boolean requests are tracked as fixtures/tests, not presented in this working example pack. The supported safe subtract family remains narrow and explicit: `subtract(box, cylinder)` and `subtract(box, cone)` still require a Z-aligned tool, full span through the current box shell, non-degenerate boundary circles for cones, and strict in-bounds clearance with no tangent/grazing contact. Sequential composition is limited to repeated document-order subtracts from that same safe family only: `box → subtract cylinder/cone → subtract cylinder/cone`, while the intermediate result must stay representable as one outer box shell plus non-interfering analytic through-holes. This is not general multi-feature boolean support. Box+cylinder `add`, box+cylinder `intersect`, rotated cylinders, partial-depth cuts, tangent/grazing cases, outside-footprint cuts, interfering multi-hole layouts, and unsupported subtract orderings remain unsupported. Box+cone `add`, box+cone `intersect`, tilted cones, partial-depth cone cuts, tangent/grazing cone cuts, apex-inside cases, outside-footprint cone cuts, and unsupported mixed-ordering requests remain unsupported. Box+sphere support is still narrow and truth-first: only `subtract(box, sphere)` with a strictly contained, non-tangent, fully enclosed cavity is supported, reconstructed via one outer shell plus one inner spherical shell. `add(box, sphere)`, `intersect(box, sphere)`, tangent cavity requests, and partially outside sphere requests remain unsupported. Box+torus booleans are currently unsupported in every audited form: `subtract(box, torus)`, `add(box, torus)`, and `intersect(box, torus)` all fail the real kernel boundary for centered, offset, fully contained, face-intersecting, and outside-footprint torus placements, so no box+torus example is included here. These files are intended to stay minimal, readable, and aligned with the implemented language surface. Export artifacts are kept separately under `testdata/firmament/exports/` so examples remain source-only and demo outputs stay easy to find.
diff --git a/testdata/firmament/examples/p2_mirror_hole_pair.firmament b/testdata/firmament/examples/p2_mirror_hole_pair.firmament
new file mode 100644
index 00000000..805060f7
--- /dev/null
+++ b/testdata/firmament/examples/p2_mirror_hole_pair.firmament
@@ -0,0 +1,44 @@
+firmament:
+ version: 1
+
+model:
+ name: p2_mirror_hole_pair
+ units: mm
+
+ops[5]:
+ -
+ op: box
+ id: plate
+ size[3]:
+ 120
+ 80
+ 8
+
+ -
+ op: subtract
+ id: hole_cut_left
+ from: plate
+ with:
+ op: cylinder
+ radius: 3
+ height: 8
+ place:
+ on: origin
+ offset[3]:
+ -20
+ 0
+ 0
+
+ -
+ op: pattern_mirror
+ source: hole_cut_left
+ plane: yz
+
+ -
+ op: expect_selectable
+ target: hole_cut_left__mir_yz.side_faces
+ count: 6
+
+ -
+ op: expect_manifold
+ target: hole_cut_left__mir_yz
diff --git a/testdata/firmament/fixtures/p3_invalid_pattern_mirror_plane.firmament b/testdata/firmament/fixtures/p3_invalid_pattern_mirror_plane.firmament
new file mode 100644
index 00000000..8859c7ea
--- /dev/null
+++ b/testdata/firmament/fixtures/p3_invalid_pattern_mirror_plane.firmament
@@ -0,0 +1,23 @@
+firmament:
+ version: 1
+
+model:
+ name: p3_invalid_pattern_mirror_plane
+ units: mm
+
+ops[3]:
+ -
+ op: box
+ id: plate
+ size[3]: [120, 80, 8]
+
+ -
+ op: subtract
+ id: hole_cut
+ from: plate
+ with: { op: cylinder, radius: 3, height: 8 }
+
+ -
+ op: pattern_mirror
+ source: hole_cut
+ plane: zx
diff --git a/testdata/firmament/fixtures/p3_invalid_pattern_mirror_source_placement.firmament b/testdata/firmament/fixtures/p3_invalid_pattern_mirror_source_placement.firmament
new file mode 100644
index 00000000..b6f115ff
--- /dev/null
+++ b/testdata/firmament/fixtures/p3_invalid_pattern_mirror_source_placement.firmament
@@ -0,0 +1,26 @@
+firmament:
+ version: 1
+
+model:
+ name: p3_invalid_pattern_mirror_source_placement
+ units: mm
+
+ops[3]:
+ -
+ op: box
+ id: plate
+ size[3]: [120, 80, 8]
+
+ -
+ op: subtract
+ id: hole_cut
+ from: plate
+ with: { op: cylinder, radius: 3, height: 8 }
+ place:
+ on: plate.top_face
+ offset[3]: [20, 0, 0]
+
+ -
+ op: pattern_mirror
+ source: hole_cut
+ plane: yz