Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-F8.2 source-surface extraction and trim capability matrix

Yuechen Lib344ab31f14d
diff --git a/Aetheris.Kernel.Firmament.Tests/SourceSurfaceAndTrimCapabilityTests.cs b/Aetheris.Kernel.Firmament.Tests/SourceSurfaceAndTrimCapabilityTests.cs
new file mode 100644
index 00000000..9400bd60
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/SourceSurfaceAndTrimCapabilityTests.cs
@@ -0,0 +1,85 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class SourceSurfaceAndTrimCapabilityTests
+{
+ [Fact]
+ public void SourceSurfaceExtractor_Box_ProducesSixPlanarDescriptors()
+ {
+ var result = SourceSurfaceExtractor.Extract(new CirBoxNode(10, 20, 30));
+ Assert.Equal(6, result.Descriptors.Count);
+ Assert.All(result.Descriptors, d => Assert.Equal(SurfacePatchFamily.Planar, d.Family));
+ Assert.Contains(result.Descriptors, d => d.ParameterPayloadReference == "top");
+ Assert.Contains(result.Descriptors, d => d.ParameterPayloadReference == "bottom");
+ }
+
+ [Fact]
+ public void SourceSurfaceExtractor_Cylinder_ProducesSideAndCaps()
+ {
+ var result = SourceSurfaceExtractor.Extract(new CirCylinderNode(5, 20));
+ Assert.Single(result.Descriptors.Where(d => d.Family == SurfacePatchFamily.Cylindrical));
+ Assert.Equal(2, result.Descriptors.Count(d => d.Family == SurfacePatchFamily.Planar));
+ }
+
+ [Fact]
+ public void SourceSurfaceExtractor_Sphere_ProducesSpherical()
+ {
+ var result = SourceSurfaceExtractor.Extract(new CirSphereNode(5));
+ var descriptor = Assert.Single(result.Descriptors);
+ Assert.Equal(SurfacePatchFamily.Spherical, descriptor.Family);
+ }
+
+ [Fact]
+ public void SourceSurfaceExtractor_Torus_ProducesToroidalDeferredMaterialization()
+ {
+ var result = SourceSurfaceExtractor.Extract(new CirTorusNode(10, 2));
+ var descriptor = Assert.Single(result.Descriptors);
+ Assert.Equal(SurfacePatchFamily.Toroidal, descriptor.Family);
+ Assert.Contains(result.Diagnostics, d => d.Code == "torus-materialization-deferred");
+ }
+
+ [Fact]
+ public void SourceSurfaceExtractor_BooleanTree_ExtractsPrimitiveSourceSurfaces()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 10));
+ var result = SourceSurfaceExtractor.Extract(root);
+ Assert.Equal(9, result.Descriptors.Count);
+ Assert.Contains(result.Diagnostics, d => d.Code == "retention-deferred");
+ }
+
+ [Fact]
+ public void SourceSurfaceExtractor_Transform_ComposesIntoDescriptors()
+ {
+ var root = new CirTransformNode(new CirSphereNode(5), Transform3D.CreateTranslation(new Vector3D(1, 2, 3)));
+ var result = SourceSurfaceExtractor.Extract(root);
+ var descriptor = Assert.Single(result.Descriptors);
+ Assert.Equal(new Point3D(1, 2, 3), descriptor.Transform.Apply(Point3D.Origin));
+ }
+
+ [Fact]
+ public void TrimCapabilityMatrix_PlanarSphere_IsCircleExact()
+ {
+ var result = TrimCapabilityMatrix.Evaluate(SurfacePatchFamily.Planar, SurfacePatchFamily.Spherical);
+ Assert.Equal(TrimCapabilityClassification.ExactSupported, result.Classification);
+ Assert.Contains(TrimCurveFamily.Circle, result.CurveFamilies);
+ }
+
+ [Fact]
+ public void TrimCapabilityMatrix_PlanarTorus_IsDeferred()
+ {
+ var result = TrimCapabilityMatrix.Evaluate(SurfacePatchFamily.Planar, SurfacePatchFamily.Toroidal);
+ Assert.Equal(TrimCapabilityClassification.Deferred, result.Classification);
+ }
+
+ [Fact]
+ public void TrimCapabilityMatrix_IsSymmetricForKnownPairs()
+ {
+ var ab = TrimCapabilityMatrix.Evaluate(SurfacePatchFamily.Cylindrical, SurfacePatchFamily.Planar);
+ var ba = TrimCapabilityMatrix.Evaluate(SurfacePatchFamily.Planar, SurfacePatchFamily.Cylindrical);
+ Assert.Equal(ab.Classification, ba.Classification);
+ Assert.Equal(ab.CurveFamilies, ba.CurveFamilies);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/SourceSurfaceExtraction.cs b/Aetheris.Kernel.Firmament/Execution/SourceSurfaceExtraction.cs
new file mode 100644
index 00000000..3b8aebd3
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/SourceSurfaceExtraction.cs
@@ -0,0 +1,147 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal enum TrimCapabilityClassification
+{
+ ExactSupported,
+ SpecialCaseOnly,
+ Deferred,
+ Unsupported
+}
+
+internal sealed record TrimCapabilityResult(
+ SurfacePatchFamily FamilyA,
+ SurfacePatchFamily FamilyB,
+ TrimCapabilityClassification Classification,
+ IReadOnlyList<TrimCurveFamily> CurveFamilies,
+ bool HasOrientationOrPlacementRestrictions,
+ string Reason);
+
+internal static class TrimCapabilityMatrix
+{
+ internal static TrimCapabilityResult Evaluate(SurfacePatchFamily a, SurfacePatchFamily b)
+ {
+ var key = Normalize(a, b);
+ return key switch
+ {
+ var k when k == Normalize(SurfacePatchFamily.Planar, SurfacePatchFamily.Planar)
+ => new(a, b, TrimCapabilityClassification.ExactSupported, [TrimCurveFamily.Line], false, "Planar/planar trims are exact line intersections."),
+ var k when k == Normalize(SurfacePatchFamily.Planar, SurfacePatchFamily.Cylindrical)
+ => new(a, b, TrimCapabilityClassification.SpecialCaseOnly, [TrimCurveFamily.Line, TrimCurveFamily.Circle, TrimCurveFamily.Ellipse], true, "Planar/cylindrical intersections vary by orientation and offset."),
+ var k when k == Normalize(SurfacePatchFamily.Planar, SurfacePatchFamily.Spherical)
+ => new(a, b, TrimCapabilityClassification.ExactSupported, [TrimCurveFamily.Circle], true, "Planar/spherical trims are circles when intersecting."),
+ var k when k == Normalize(SurfacePatchFamily.Planar, SurfacePatchFamily.Prismatic)
+ => new(a, b, TrimCapabilityClassification.ExactSupported, [TrimCurveFamily.Line, TrimCurveFamily.Polyline], false, "Planar/prismatic seams are linear/polyline exact trims."),
+ var k when k == Normalize(SurfacePatchFamily.Planar, SurfacePatchFamily.Conical)
+ => new(a, b, TrimCapabilityClassification.Deferred, [TrimCurveFamily.Ellipse, TrimCurveFamily.AlgebraicImplicit], true, "General planar/conical intersections require broader conic policy."),
+ var k when k == Normalize(SurfacePatchFamily.Planar, SurfacePatchFamily.Toroidal)
+ => new(a, b, TrimCapabilityClassification.Deferred, [TrimCurveFamily.AlgebraicImplicit], true, "General planar/toroidal intersections are quartic/algebraic."),
+ var k when k == Normalize(SurfacePatchFamily.Cylindrical, SurfacePatchFamily.Cylindrical)
+ => new(a, b, TrimCapabilityClassification.Deferred, [TrimCurveFamily.AlgebraicImplicit], true, "Cylindrical/cylindrical exact support is not centralized yet."),
+ var k when k == Normalize(SurfacePatchFamily.Spherical, SurfacePatchFamily.Cylindrical)
+ => new(a, b, TrimCapabilityClassification.Deferred, [TrimCurveFamily.AlgebraicImplicit], true, "Spherical/cylindrical support is deferred to broader analytic curve policy."),
+ var k when k.Item1 == SurfacePatchFamily.Toroidal || k.Item2 == SurfacePatchFamily.Toroidal
+ => new(a, b, TrimCapabilityClassification.Deferred, [TrimCurveFamily.AlgebraicImplicit], true, "Toroidal pairings remain deferred except future explicit special-cases."),
+ _ => new(a, b, TrimCapabilityClassification.Unsupported, [TrimCurveFamily.Unsupported], true, "No trim capability entry for the requested source surface family pair.")
+ };
+ }
+
+ private static (SurfacePatchFamily, SurfacePatchFamily) Normalize(SurfacePatchFamily a, SurfacePatchFamily b)
+ => a <= b ? (a, b) : (b, a);
+}
+
+internal sealed record SourceSurfaceExtractionDiagnostic(string Code, string Message);
+
+internal sealed record SourceSurfaceExtractionResult(
+ bool IsSuccess,
+ IReadOnlyList<SourceSurfaceDescriptor> Descriptors,
+ IReadOnlyList<SourceSurfaceExtractionDiagnostic> Diagnostics,
+ IReadOnlyList<string> UnsupportedNodeReasons);
+
+internal static class SourceSurfaceExtractor
+{
+ internal static SourceSurfaceExtractionResult Extract(CirNode root, NativeGeometryReplayLog? replayLog = null)
+ {
+ var descriptors = new List<SourceSurfaceDescriptor>();
+ var diagnostics = new List<SourceSurfaceExtractionDiagnostic>();
+ var unsupported = new List<string>();
+ Visit(root, Transform3D.Identity, descriptors, diagnostics, unsupported, replayLog);
+ if (root is CirSubtractNode or CirUnionNode or CirIntersectNode)
+ {
+ diagnostics.Add(new("retention-deferred", "Boolean source-surface extraction inventories primitive surfaces only; retained/discarded classification is deferred."));
+ }
+
+ return new(unsupported.Count == 0, descriptors, diagnostics, unsupported);
+ }
+
+ private static void Visit(CirNode node, Transform3D accumulated, List<SourceSurfaceDescriptor> descriptors, List<SourceSurfaceExtractionDiagnostic> diagnostics, List<string> unsupported, NativeGeometryReplayLog? replayLog)
+ {
+ switch (node)
+ {
+ case CirTransformNode transformNode:
+ Visit(transformNode.Child, Transform3D.Compose(accumulated, transformNode.Transform), descriptors, diagnostics, unsupported, replayLog);
+ return;
+ case CirBoxNode:
+ AddBoxDescriptors(accumulated, descriptors, replayLog, nameof(CirBoxNode));
+ return;
+ case CirCylinderNode:
+ AddCylinderDescriptors(accumulated, descriptors, replayLog, nameof(CirCylinderNode));
+ return;
+ case CirSphereNode:
+ descriptors.Add(CreateDescriptor(SurfacePatchFamily.Spherical, "sphere", accumulated, node, replayLog, FacePatchOrientationRole.Forward));
+ return;
+ case CirTorusNode:
+ descriptors.Add(CreateDescriptor(SurfacePatchFamily.Toroidal, "torus", accumulated, node, replayLog, FacePatchOrientationRole.Forward));
+ diagnostics.Add(new("torus-materialization-deferred", "Toroidal source surface extracted; downstream materialization remains deferred."));
+ return;
+ case CirSubtractNode subtract:
+ Visit(subtract.Left, accumulated, descriptors, diagnostics, unsupported, replayLog);
+ Visit(subtract.Right, accumulated, descriptors, diagnostics, unsupported, replayLog);
+ return;
+ case CirUnionNode union:
+ Visit(union.Left, accumulated, descriptors, diagnostics, unsupported, replayLog);
+ Visit(union.Right, accumulated, descriptors, diagnostics, unsupported, replayLog);
+ return;
+ case CirIntersectNode intersect:
+ Visit(intersect.Left, accumulated, descriptors, diagnostics, unsupported, replayLog);
+ Visit(intersect.Right, accumulated, descriptors, diagnostics, unsupported, replayLog);
+ return;
+ default:
+ unsupported.Add($"Unsupported CIR node kind for source-surface extraction: {node.Kind}.");
+ return;
+ }
+ }
+
+ private static void AddBoxDescriptors(Transform3D transform, List<SourceSurfaceDescriptor> descriptors, NativeGeometryReplayLog? replayLog, string owningKind)
+ {
+ var roles = new[] { "top", "bottom", "left", "right", "front", "back" };
+ foreach (var role in roles)
+ {
+ descriptors.Add(CreateDescriptor(SurfacePatchFamily.Planar, role, transform, CirNodeKind.Box, replayLog, FacePatchOrientationRole.Forward, owningKind));
+ }
+ }
+
+ private static void AddCylinderDescriptors(Transform3D transform, List<SourceSurfaceDescriptor> descriptors, NativeGeometryReplayLog? replayLog, string owningKind)
+ {
+ descriptors.Add(CreateDescriptor(SurfacePatchFamily.Cylindrical, "side", transform, CirNodeKind.Cylinder, replayLog, FacePatchOrientationRole.Forward, owningKind));
+ descriptors.Add(CreateDescriptor(SurfacePatchFamily.Planar, "cap-top", transform, CirNodeKind.Cylinder, replayLog, FacePatchOrientationRole.Forward, owningKind));
+ descriptors.Add(CreateDescriptor(SurfacePatchFamily.Planar, "cap-bottom", transform, CirNodeKind.Cylinder, replayLog, FacePatchOrientationRole.Reversed, owningKind));
+ }
+
+
+ private static SourceSurfaceDescriptor CreateDescriptor(SurfacePatchFamily family, string provenanceRole, Transform3D transform, CirNodeKind nodeKind, NativeGeometryReplayLog? replayLog, FacePatchOrientationRole orientation, string owningKind)
+ {
+ var op = replayLog?.Operations.LastOrDefault();
+ var placementSuffix = op is null ? "" : $"|placement:{op.ResolvedPlacement.Kind}";
+ return new SourceSurfaceDescriptor(family, provenanceRole, transform, $"cir:{nodeKind.ToString().ToLowerInvariant()}:{provenanceRole}{placementSuffix}", owningKind, op?.OpIndex, orientation);
+ }
+
+ private static SourceSurfaceDescriptor CreateDescriptor(SurfacePatchFamily family, string provenanceRole, Transform3D transform, CirNode node, NativeGeometryReplayLog? replayLog, FacePatchOrientationRole orientation, string? owningKind = null)
+ {
+ var op = replayLog?.Operations.LastOrDefault();
+ var placementSuffix = op is null ? "" : $"|placement:{op.ResolvedPlacement.Kind}";
+ return new SourceSurfaceDescriptor(family, provenanceRole, transform, $"cir:{node.Kind.ToString().ToLowerInvariant()}:{provenanceRole}{placementSuffix}", owningKind ?? node.GetType().Name, op?.OpIndex, orientation);
+ }
+}
diff --git a/docs/cir-f82-source-surface-and-trim-capabilities.md b/docs/cir-f82-source-surface-and-trim-capabilities.md
new file mode 100644
index 00000000..401201f6
--- /dev/null
+++ b/docs/cir-f82-source-surface-and-trim-capabilities.md
@@ -0,0 +1,56 @@
+# CIR-F8.2 — source-surface extraction + trim capability matrix
+
+## Purpose
+
+CIR-F8.2 adds two substrate services without changing production materialization behavior:
+
+1. `TrimCapabilityMatrix`: centralized source-surface-family pair policy for trim curve support.
+2. `SourceSurfaceExtractor`: inventory extraction of `SourceSurfaceDescriptor` values from CIR trees.
+
+This keeps architecture moving from pair-specific materializers toward descriptor-first surface-family materialization.
+
+## Capability semantics
+
+Each pair `(SurfacePatchFamily A, SurfacePatchFamily B)` resolves to:
+
+- classification: exact-supported / special-case-only / deferred / unsupported
+- candidate trim families (line/circle/ellipse/polyline/bspline/algebraic/unsupported)
+- whether orientation/placement restrictions apply
+- explicit reason text
+
+Current notable entries:
+
+- Planar×Planar → exact, line
+- Planar×Cylindrical → special-case-only, line/circle/ellipse
+- Planar×Spherical → exact, circle
+- Planar×Prismatic → exact, line/polyline
+- Planar×Conical → deferred
+- Planar×Toroidal → deferred
+- Cylindrical×Cylindrical → deferred
+- Spherical×Cylindrical → deferred
+- Toroidal×* → deferred
+
+## Source-surface extraction behavior
+
+`SourceSurfaceExtractor.Extract(CirNode, NativeGeometryReplayLog?)` traverses CIR including booleans and transform nodes.
+
+- Box: 6 planar descriptors (`top/bottom/left/right/front/back`)
+- Cylinder: 1 cylindrical side + 2 planar caps
+- Sphere: 1 spherical descriptor
+- Torus: 1 toroidal descriptor + deferred-materialization diagnostic
+- Booleans: both operands are inventoried; retained/discarded classification is intentionally deferred
+- Transform nodes: transforms are composed and preserved on descriptors
+
+Replay/provenance facts are attached opportunistically using latest replay operation when available (op index, placement-kind hint in provenance string).
+
+## Intentionally not implemented
+
+- No BRep face/edge emission
+- No trim-curve computation
+- No retained-face classification
+- No generated topology naming
+- No change to existing pair-specific rematerializers or STEP behavior
+
+## CIR-F8.3 recommendation
+
+Use extracted source surfaces + matrix lookup to produce first `FacePatchDescriptor` dry-run candidate sets for subtract(box,cylinder) and subtract(box,sphere), with explicit retained-surface diagnostics before any topology assembly.