Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Implement PMI-M0b planar datum authoring and inspection

Yuechen Li17bd50c5dc21
diff --git a/Aetheris.Kernel.Core.Tests/Pmi/PmiModelTests.cs b/Aetheris.Kernel.Core.Tests/Pmi/PmiModelTests.cs
index f83fc8ae..7fe193fe 100644
--- a/Aetheris.Kernel.Core.Tests/Pmi/PmiModelTests.cs
+++ b/Aetheris.Kernel.Core.Tests/Pmi/PmiModelTests.cs
@@ -6,20 +6,36 @@ namespace Aetheris.Kernel.Core.Tests.Pmi;
public sealed class PmiModelTests
{
[Fact]
- public void PmiModel_CanDeclarePlanarDatumFeature()
+ public void CreatePlanarDatum_Succeeds()
{
var model = PmiModel.Empty("part_main")
- .AddDatum(new PmiDatumFeature(
- "datum:A",
+ .CreatePlanarDatum(
"A",
- PmiDatumFeatureKind.Planar,
- new PmiPlanarFaceReference("base", "base.top")));
+ PmiPlanarFaceReference.FromSelector("base.top_face"));
var datum = Assert.Single(model.DatumFeatures);
Assert.Equal("A", datum.Label);
Assert.Equal(PmiDatumFeatureKind.Planar, datum.Kind);
var planar = Assert.IsType<PmiPlanarFaceReference>(datum.Target);
- Assert.Equal("base.top", planar.Selector);
+ Assert.Equal("base.top_face", planar.Selector);
+ }
+
+ [Fact]
+ public void CreatePlanarDatum_DuplicateLabel_Fails()
+ {
+ var model = PmiModel.Empty("part_main")
+ .CreatePlanarDatum("A", PmiPlanarFaceReference.FromSelector("base.top_face"));
+
+ var error = Assert.Throws<InvalidOperationException>(() =>
+ model.CreatePlanarDatum("a", PmiPlanarFaceReference.FromSelector("base.bottom_face")));
+
+ Assert.Contains("already exists", error.Message, StringComparison.Ordinal);
+ }
+
+ [Fact]
+ public void CreatePlanarDatum_NonPlanar_Fails()
+ {
+ Assert.Throws<ArgumentException>(() => PmiPlanarFaceReference.FromSelector("main_hole"));
}
[Fact]
diff --git a/Aetheris.Kernel.Core/Pmi/PmiModel.cs b/Aetheris.Kernel.Core/Pmi/PmiModel.cs
index ecd0295c..e39449f7 100644
--- a/Aetheris.Kernel.Core/Pmi/PmiModel.cs
+++ b/Aetheris.Kernel.Core/Pmi/PmiModel.cs
@@ -14,6 +14,31 @@ public sealed record PmiModel(
public PmiModel AddDatum(PmiDatumFeature datum)
=> this with { DatumFeatures = DatumFeatures.Concat([datum]).ToArray() };
+ public PmiModel CreatePlanarDatum(string label, PmiPlanarFaceReference reference)
+ {
+ if (string.IsNullOrWhiteSpace(label))
+ {
+ throw new ArgumentException("Datum label is required.", nameof(label));
+ }
+
+ ArgumentNullException.ThrowIfNull(reference);
+ if (!reference.IsValid)
+ {
+ throw new ArgumentException("Planar datum reference must include non-empty feature id and selector.", nameof(reference));
+ }
+
+ if (DatumFeatures.Any(existing => string.Equals(existing.Label, label, StringComparison.OrdinalIgnoreCase)))
+ {
+ throw new InvalidOperationException($"Datum label '{label}' already exists in this PMI model.");
+ }
+
+ return AddDatum(new PmiDatumFeature(
+ $"datum:{label}",
+ label,
+ PmiDatumFeatureKind.Planar,
+ reference));
+ }
+
public PmiModel AddDimension(PmiDimension dimension)
=> this with { Dimensions = Dimensions.Concat([dimension]).ToArray() };
}
@@ -48,7 +73,29 @@ public abstract record PmiSemanticReference;
/// <summary>
/// Semantic reference to a planar target selected from a feature context.
/// </summary>
-public sealed record PmiPlanarFaceReference(string FeatureId, string Selector) : PmiSemanticReference;
+public sealed record PmiPlanarFaceReference(string FeatureId, string Selector) : PmiSemanticReference
+{
+ public bool IsValid => !string.IsNullOrWhiteSpace(FeatureId) && !string.IsNullOrWhiteSpace(Selector);
+
+ public static PmiPlanarFaceReference FromSelector(string selectorTarget)
+ {
+ if (string.IsNullOrWhiteSpace(selectorTarget))
+ {
+ throw new ArgumentException("Selector target must be non-empty.", nameof(selectorTarget));
+ }
+
+ var separatorIndex = selectorTarget.IndexOf('.', StringComparison.Ordinal);
+ if (separatorIndex <= 0 || separatorIndex >= selectorTarget.Length - 1)
+ {
+ throw new ArgumentException(
+ "Selector target must be shaped as 'feature.port'.",
+ nameof(selectorTarget));
+ }
+
+ var featureId = selectorTarget[..separatorIndex];
+ return new PmiPlanarFaceReference(featureId, selectorTarget);
+ }
+}
/// <summary>
/// Semantic reference to a cylindrical/hole-like feature.
diff --git a/Aetheris.Kernel.Firmament.Tests/FirmamentPmiTests.cs b/Aetheris.Kernel.Firmament.Tests/FirmamentPmiTests.cs
index 6200444b..d6255160 100644
--- a/Aetheris.Kernel.Firmament.Tests/FirmamentPmiTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/FirmamentPmiTests.cs
@@ -42,6 +42,36 @@ public sealed class FirmamentPmiTests
Assert.Contains("unknown selector root feature 'missing'", diagnostic.Message, StringComparison.Ordinal);
}
+ [Fact]
+ public void CreatePlanarDatum_DuplicateLabel_Fails()
+ {
+ var result = CompileFixture("testdata/firmament/fixtures/m7e-invalid-pmi-duplicate-datum-label.firmament");
+ Assert.False(result.Compilation.IsSuccess);
+ var diagnostic = Assert.Single(result.Compilation.Diagnostics);
+ Assert.Contains("reuses label 'A'", diagnostic.Message, StringComparison.Ordinal);
+ }
+
+ [Fact]
+ public void CreatePlanarDatum_NonPlanar_Fails()
+ {
+ var result = CompileFixture("testdata/firmament/fixtures/m7e-invalid-pmi-nonplanar-datum-target.firmament");
+ Assert.False(result.Compilation.IsSuccess);
+ var diagnostic = Assert.Single(result.Compilation.Diagnostics);
+ Assert.Contains("requires a planar-face selector target", diagnostic.Message, StringComparison.Ordinal);
+ }
+
+ [Fact]
+ public void AnalyzerDisplaysDatum()
+ {
+ var export = ExportFixture("testdata/firmament/examples/m7_semantic_pmi_baseline.firmament");
+ Assert.True(export.IsSuccess);
+
+ var datum = Assert.Single(export.Value.DatumInspection!);
+ Assert.Equal("A", datum.Label);
+ Assert.Equal("planar", datum.DatumType);
+ Assert.Equal("base.top_face", datum.Target);
+ }
+
[Fact]
public void LegacyAutoHoleDemo_BuildsSemanticDiameterDimensions_InKernelPmiModel()
@@ -63,6 +93,21 @@ public sealed class FirmamentPmiTests
second => Assert.Equal("diameter:hole_b", second.DimensionId));
}
+ [Fact]
+ public void IntegrationSanity_LegacyAutoHolePmi_StillWorks_WithExplicitDatumsAvailable()
+ {
+ var baselineWithDatum = ExportFixture("testdata/firmament/examples/m7_semantic_pmi_baseline.firmament");
+ Assert.True(baselineWithDatum.IsSuccess);
+ Assert.Single(baselineWithDatum.Value.DatumInspection!);
+
+ var legacyAutoHole = CompileFixture("testdata/firmament/examples/boolean_two_cylinder_holes_basic.firmament");
+ Assert.True(legacyAutoHole.Compilation.IsSuccess);
+
+ var loweringPlan = Assert.IsType<FirmamentCompilationArtifact>(legacyAutoHole.Compilation.Value).PrimitiveLoweringPlan;
+ var model = FirmamentStepExporter.BuildLegacyAutoHolePmiModel(loweringPlan!, selectionFeatureId: "hole_b");
+ Assert.Equal(2, model.Dimensions.Count);
+ }
+
private static FirmamentCompileResult CompileFixture(string fixturePath)
{
var sourceText = FirmamentCorpusHarness.ReadFixtureText(fixturePath);
diff --git a/Aetheris.Kernel.Firmament/Execution/FirmamentSelectorResolver.cs b/Aetheris.Kernel.Firmament/Execution/FirmamentSelectorResolver.cs
index cb9adc30..184094cb 100644
--- a/Aetheris.Kernel.Firmament/Execution/FirmamentSelectorResolver.cs
+++ b/Aetheris.Kernel.Firmament/Execution/FirmamentSelectorResolver.cs
@@ -34,13 +34,15 @@ internal static class FirmamentSelectorResolver
? cylinderCount
: TryResolveConeCount(body, port, resultKind, out var coneCount)
? coneCount
- : TryResolveTorusCount(body, port, resultKind, out var torusCount)
- ? torusCount
- : resultKind switch
- {
- FirmamentSelectorResultKind.Face or FirmamentSelectorResultKind.FaceSet => body.Topology.Faces.Count(),
- FirmamentSelectorResultKind.EdgeSet => body.Topology.Edges.Count(),
- FirmamentSelectorResultKind.VertexSet => body.Topology.Vertices.Count(),
+ : TryResolveTorusCount(body, port, resultKind, out var torusCount)
+ ? torusCount
+ : TryResolveBoxLikeCount(body, port, resultKind, out var boxLikeCount)
+ ? boxLikeCount
+ : resultKind switch
+ {
+ FirmamentSelectorResultKind.Face or FirmamentSelectorResultKind.FaceSet => body.Topology.Faces.Count(),
+ FirmamentSelectorResultKind.EdgeSet => body.Topology.Edges.Count(),
+ FirmamentSelectorResultKind.VertexSet => body.Topology.Vertices.Count(),
_ => 0
};
@@ -48,6 +50,20 @@ internal static class FirmamentSelectorResolver
return true;
}
+ private static bool TryResolveBoxLikeCount(BrepBody body, string port, FirmamentSelectorResultKind resultKind, out int count)
+ {
+ count = port switch
+ {
+ "top_face" => CountFaces(body, surface => surface.Kind == SurfaceGeometryKind.Plane && surface.Plane!.Value.Normal.ToVector().Z > 0.5d),
+ "bottom_face" => CountFaces(body, surface => surface.Kind == SurfaceGeometryKind.Plane && surface.Plane!.Value.Normal.ToVector().Z < -0.5d),
+ "edges" when resultKind == FirmamentSelectorResultKind.EdgeSet => body.Topology.Edges.Count(),
+ "vertices" when resultKind == FirmamentSelectorResultKind.VertexSet => body.Topology.Vertices.Count(),
+ _ => -1
+ };
+
+ return count >= 0;
+ }
+
private static bool TryResolveConeCount(BrepBody body, string port, FirmamentSelectorResultKind resultKind, out int count)
{
count = 0;
diff --git a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
index 0b900a34..00aa281b 100644
--- a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
@@ -7,4 +7,10 @@ public sealed record FirmamentStepExportResult(
string ExportedBodyCategory,
string? ExportedFeatureKind = null,
string ExportBodyPolicy = FirmamentStepExporter.LastExecutedGeometricBodyPolicy,
- string ExportBodySelectionReason = FirmamentStepExporter.LastExecutedGeometricBodySelectionReason);
+ string ExportBodySelectionReason = FirmamentStepExporter.LastExecutedGeometricBodySelectionReason,
+ IReadOnlyList<FirmamentPmiInspectionDatum>? DatumInspection = null);
+
+public sealed record FirmamentPmiInspectionDatum(
+ string Label,
+ string DatumType,
+ string Target);
diff --git a/Aetheris.Kernel.Firmament/FirmamentStepExporter.cs b/Aetheris.Kernel.Firmament/FirmamentStepExporter.cs
index 9c90d799..4cf7c1b7 100644
--- a/Aetheris.Kernel.Firmament/FirmamentStepExporter.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentStepExporter.cs
@@ -54,7 +54,8 @@ public static class FirmamentStepExporter
selectionResult.Value.FeatureId,
selectionResult.Value.OpIndex,
selectionResult.Value.BodyCategory,
- selectionResult.Value.FeatureKind));
+ selectionResult.Value.FeatureKind,
+ DatumInspection: BuildDatumInspection(pmiModel.Model)));
}
private static KernelResult<ExportBodySelection> SelectExportBody(FirmamentPrimitiveExecutionResult? primitiveExecutionResult)
@@ -239,13 +240,14 @@ public static class FirmamentStepExporter
&& entry.RawFields.TryGetValue("label", out var label))
{
if (string.Equals(datumKind, "plane", StringComparison.Ordinal)
- && targetRaw.Contains(".", StringComparison.Ordinal))
+ && TryBuildPlanarDatumReference(targetRaw, featureBodies, out var planarReference))
{
- model = model.AddDatum(new PmiDatumFeature(
- $"datum:{label}",
- label,
- PmiDatumFeatureKind.Planar,
- new PmiPlanarFaceReference(featureId, targetRaw)));
+ if (model.DatumFeatures.Any(existing => string.Equals(existing.Label, label, StringComparison.OrdinalIgnoreCase)))
+ {
+ continue;
+ }
+
+ model = model.CreatePlanarDatum(label, planarReference);
}
}
@@ -289,6 +291,64 @@ public static class FirmamentStepExporter
return map;
}
+ private static IReadOnlyList<FirmamentPmiInspectionDatum> BuildDatumInspection(PmiModel model)
+ => model.DatumFeatures
+ .Select(datum => datum.Target is PmiPlanarFaceReference planar
+ ? new FirmamentPmiInspectionDatum(datum.Label, "planar", planar.Selector)
+ : new FirmamentPmiInspectionDatum(datum.Label, datum.Kind.ToString().ToLowerInvariant(), datum.Target.ToString() ?? "unknown"))
+ .ToArray();
+
+ private static bool TryBuildPlanarDatumReference(
+ string targetRaw,
+ IReadOnlyDictionary<string, BrepBody> featureBodies,
+ out PmiPlanarFaceReference planarReference)
+ {
+ planarReference = null!;
+
+ PmiPlanarFaceReference candidate;
+ try
+ {
+ candidate = PmiPlanarFaceReference.FromSelector(targetRaw);
+ }
+ catch (ArgumentException)
+ {
+ return false;
+ }
+
+ if (!FirmamentSelectorResolver.TryResolve(targetRaw, featureBodies, FirmamentSelectorResultKind.Face, out var selectorResolution))
+ {
+ return false;
+ }
+
+ if (selectorResolution.Count != 1)
+ {
+ return false;
+ }
+
+ if (!featureBodies.TryGetValue(candidate.FeatureId, out var body))
+ {
+ return false;
+ }
+
+ var planarFaceCount = body.Topology.Faces.Count(face =>
+ body.TryGetFaceSurfaceGeometry(face.Id, out var surface)
+ && surface is not null
+ && surface.Kind == Aetheris.Kernel.Core.Geometry.SurfaceGeometryKind.Plane);
+
+ if (planarFaceCount <= 0)
+ {
+ return false;
+ }
+
+ if (targetRaw.EndsWith(".side_face", StringComparison.Ordinal) || targetRaw.EndsWith(".surface", StringComparison.Ordinal))
+ {
+ return false;
+ }
+
+ planarReference = candidate;
+ return true;
+ }
+
private sealed record DerivedPmiPayload(PmiModel Model, IReadOnlyList<Step242SemanticPmiNote> PassthroughNotes);
private sealed record ExportBodySelection(
diff --git a/Aetheris.Kernel.Firmament/Validation/FirmamentPmiValidator.cs b/Aetheris.Kernel.Firmament/Validation/FirmamentPmiValidator.cs
index 441a983e..6337b92d 100644
--- a/Aetheris.Kernel.Firmament/Validation/FirmamentPmiValidator.cs
+++ b/Aetheris.Kernel.Firmament/Validation/FirmamentPmiValidator.cs
@@ -20,6 +20,7 @@ internal static class FirmamentPmiValidator
var opsByFeatureId = parsedDocument.Ops.Entries
.Where(entry => entry.RawFields.TryGetValue("id", out _))
.ToDictionary(entry => entry.RawFields["id"], StringComparer.Ordinal);
+ var seenDatumLabels = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
for (var index = 0; index < parsedDocument.Pmi.Entries.Count; index++)
{
@@ -27,7 +28,7 @@ internal static class FirmamentPmiValidator
var result = entry.Kind switch
{
FirmamentParsedPmiKind.Hole => ValidateHole(entry, index, opsByFeatureId),
- FirmamentParsedPmiKind.Datum => ValidateDatum(entry, index, opsByFeatureId),
+ FirmamentParsedPmiKind.Datum => ValidateDatum(entry, index, opsByFeatureId, seenDatumLabels),
FirmamentParsedPmiKind.Note => ValidateNote(entry, index, opsByFeatureId),
_ => Fail($"PMI entry at index {index} has unsupported kind '{entry.KindRaw}'. Supported kinds: hole, datum, note.")
};
@@ -86,7 +87,11 @@ internal static class FirmamentPmiValidator
return KernelResult<bool>.Success(true);
}
- private static KernelResult<bool> ValidateDatum(FirmamentParsedPmiEntry entry, int index, IReadOnlyDictionary<string, FirmamentParsedOpEntry> opsByFeatureId)
+ private static KernelResult<bool> ValidateDatum(
+ FirmamentParsedPmiEntry entry,
+ int index,
+ IReadOnlyDictionary<string, FirmamentParsedOpEntry> opsByFeatureId,
+ ISet<string> seenDatumLabels)
{
if (!entry.RawFields.TryGetValue("datum_kind", out var datumKind)
|| string.IsNullOrWhiteSpace(datumKind))
@@ -100,6 +105,11 @@ internal static class FirmamentPmiValidator
return Fail($"PMI datum entry at index {index} is missing required field 'label'.");
}
+ if (!seenDatumLabels.Add(label))
+ {
+ return Fail($"PMI datum entry at index {index} reuses label '{label}'. Datum labels must be unique within a document.");
+ }
+
if (string.Equals(datumKind, "plane", StringComparison.Ordinal))
{
var selectorResult = RequireSelectorTarget(entry, index, opsByFeatureId);
@@ -110,7 +120,9 @@ internal static class FirmamentPmiValidator
var rootKind = opsByFeatureId[selectorResult.Value.FeatureId].KnownKind;
if (!FirmamentSelectorContracts.TryGetPortContract(rootKind, selectorResult.Value.Port, out var contract)
- || contract.ResultKind is not (FirmamentSelectorResultKind.Face or FirmamentSelectorResultKind.FaceSet))
+ || contract.ResultKind != FirmamentSelectorResultKind.Face
+ || contract.Cardinality != FirmamentSelectorCardinality.One
+ || !IsPlanarFacePort(rootKind, selectorResult.Value.Port))
{
return Fail($"PMI datum entry at index {index} requires a planar-face selector target for datum_kind 'plane'.");
}
@@ -236,4 +248,25 @@ internal static class FirmamentPmiValidator
var normalized = new string(toolRaw.Where(character => !char.IsWhiteSpace(character)).ToArray());
return normalized.Contains("op:cylinder", StringComparison.Ordinal);
}
+
+ private static bool IsPlanarFacePort(FirmamentKnownOpKind featureKind, string port)
+ => featureKind switch
+ {
+ FirmamentKnownOpKind.Box
+ or FirmamentKnownOpKind.TriangularPrism
+ or FirmamentKnownOpKind.HexagonalPrism
+ or FirmamentKnownOpKind.StraightSlot
+ or FirmamentKnownOpKind.Add
+ or FirmamentKnownOpKind.Subtract
+ or FirmamentKnownOpKind.Intersect
+ or FirmamentKnownOpKind.Draft
+ or FirmamentKnownOpKind.Chamfer
+ or FirmamentKnownOpKind.Fillet
+ => string.Equals(port, "top_face", StringComparison.Ordinal)
+ || string.Equals(port, "bottom_face", StringComparison.Ordinal),
+ FirmamentKnownOpKind.Cylinder or FirmamentKnownOpKind.Cone
+ => string.Equals(port, "top_face", StringComparison.Ordinal)
+ || string.Equals(port, "bottom_face", StringComparison.Ordinal),
+ _ => false
+ };
}
diff --git a/testdata/firmament/fixtures/m7e-invalid-pmi-duplicate-datum-label.firmament b/testdata/firmament/fixtures/m7e-invalid-pmi-duplicate-datum-label.firmament
new file mode 100644
index 00000000..6319093e
--- /dev/null
+++ b/testdata/firmament/fixtures/m7e-invalid-pmi-duplicate-datum-label.firmament
@@ -0,0 +1,28 @@
+firmament:
+ version: 1
+
+model:
+ name: m7e_invalid_pmi_duplicate_datum_label
+ units: mm
+
+ops[1]:
+ -
+ op: box
+ id: base
+ size[3]:
+ 20
+ 20
+ 10
+
+pmi[2]:
+ -
+ kind: datum
+ datum_kind: plane
+ label: A
+ target: base.top_face
+
+ -
+ kind: datum
+ datum_kind: plane
+ label: A
+ target: base.bottom_face
diff --git a/testdata/firmament/fixtures/m7e-invalid-pmi-nonplanar-datum-target.firmament b/testdata/firmament/fixtures/m7e-invalid-pmi-nonplanar-datum-target.firmament
new file mode 100644
index 00000000..07983070
--- /dev/null
+++ b/testdata/firmament/fixtures/m7e-invalid-pmi-nonplanar-datum-target.firmament
@@ -0,0 +1,20 @@
+firmament:
+ version: 1
+
+model:
+ name: m7e_invalid_pmi_nonplanar_datum_target
+ units: mm
+
+ops[1]:
+ -
+ op: cylinder
+ id: pin
+ radius: 5
+ height: 20
+
+pmi[1]:
+ -
+ kind: datum
+ datum_kind: plane
+ label: A
+ target: pin.side_face