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.csnew file mode 100644index 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.csnew file mode 100644index 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.mdnew file mode 100644index 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.