Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add AIR-X5 remaining primitive lab matrix
Yuechen Li97ee259ba1ec
diff --git a/Aetheris.Firmament.FrictionLab/CIRLab/AirPrimitiveMatrixLab.cs b/Aetheris.Firmament.FrictionLab/CIRLab/AirPrimitiveMatrixLab.csnew file mode 100644index 00000000..8e46d31e--- /dev/null+++ b/Aetheris.Firmament.FrictionLab/CIRLab/AirPrimitiveMatrixLab.cs@@ -0,0 +1,162 @@+using Aetheris.Kernel.Core.Brep;+using Aetheris.Kernel.Core.Brep.Features;+using Aetheris.Kernel.Core.Geometry;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Core.Results;+using Aetheris.Kernel.Core.Step242;++namespace Aetheris.Firmament.FrictionLab.CIRLab;++public enum AirPrimitiveBaselineKind { Cylinder, ConeFrustum, Sphere, Torus }+public enum AirPrimitiveCandidateKind { AirExtrude, AirRevolve }++public sealed record AirPrimitiveMatrixCase(string Name, AirPrimitiveBaselineKind Primitive, double A, double B, double C = 0d);+public sealed record AirPrimitiveTopologySummary(bool BodyProduced, int VertexCount, int EdgeCount, int FaceCount, int PlaneFaceCount, int CylindricalFaceCount, int ConicalFaceCount, int SphericalFaceCount, int ToroidalFaceCount, int LoopCount, int CoedgeCount);+public sealed record AirPrimitiveStepSmokeSummary(bool Exported, IReadOnlyList<string> PresentMarkers, IReadOnlyList<string> MissingMarkers, bool ContainsBrepWithVoids, IReadOnlyList<string> Diagnostics);+public sealed record AirPrimitiveMatrixRow(AirPrimitiveMatrixCase Case, string RowKind, AirPrimitiveCandidateKind? CandidateKind, AirPrimitiveTopologySummary Topology, AirPrimitiveStepSmokeSummary StepSmoke, IReadOnlyList<string> Diagnostics, bool IsValidInput, bool TopologyParityWithBaseline, bool StepParityWithBaseline, string Recommendation);++public static class AirPrimitiveMatrixLab+{+ public static readonly string[] AllowedRecommendations = ["ready-for-production-migration", "needs-emitter-parity-work", "needs-air-revolve-lab-support", "keep-direct-constructor-for-now"];++ public static IReadOnlyList<AirPrimitiveMatrixRow> RunMatrix()+ {+ var rows = new List<AirPrimitiveMatrixRow>();+ rows.AddRange(RunCase(new("cyl-5x10", AirPrimitiveBaselineKind.Cylinder, 5, 10)));+ rows.AddRange(RunCase(new("cyl-3x12", AirPrimitiveBaselineKind.Cylinder, 3, 12)));+ rows.AddRange(RunCase(new("cyl-invalid", AirPrimitiveBaselineKind.Cylinder, -1, 10)));++ rows.AddRange(RunCase(new("frustum-5-2-10", AirPrimitiveBaselineKind.ConeFrustum, 5, 2, 10)));+ rows.AddRange(RunCase(new("cone-apex-5-0-10", AirPrimitiveBaselineKind.ConeFrustum, 5, 0, 10)));+ rows.AddRange(RunCase(new("cone-invalid", AirPrimitiveBaselineKind.ConeFrustum, 5, -1, 10)));++ rows.AddRange(RunCase(new("sphere-5", AirPrimitiveBaselineKind.Sphere, 5, 0)));+ rows.AddRange(RunCase(new("sphere-2.5", AirPrimitiveBaselineKind.Sphere, 2.5, 0)));+ rows.AddRange(RunCase(new("sphere-invalid", AirPrimitiveBaselineKind.Sphere, -1, 0)));++ rows.AddRange(RunCase(new("torus-8-2", AirPrimitiveBaselineKind.Torus, 8, 2)));+ rows.AddRange(RunCase(new("torus-5-1", AirPrimitiveBaselineKind.Torus, 5, 1)));+ rows.AddRange(RunCase(new("torus-invalid-major", AirPrimitiveBaselineKind.Torus, 0, 1)));+ rows.AddRange(RunCase(new("torus-invalid-minor", AirPrimitiveBaselineKind.Torus, 5, 0)));+ rows.AddRange(RunCase(new("torus-invalid-intersect", AirPrimitiveBaselineKind.Torus, 3, 3)));+ return rows;+ }++ public static IReadOnlyList<AirPrimitiveMatrixRow> RunCase(AirPrimitiveMatrixCase @case)+ {+ var baselineDiag = new List<string> { "air-x5-primitive-matrix-lab-started" };+ var baselineResult = CreateBaseline(@case);+ if (!baselineResult.IsSuccess || baselineResult.Value is null)+ {+ baselineDiag.AddRange(baselineResult.Diagnostics.Select(d => d.Message));+ baselineDiag.Add("air-x5-baseline-created:false");+ var baselineRow = BuildRow(@case, "baseline", null, null, baselineDiag, false, "keep-direct-constructor-for-now", null);+ var candidateRows = BuildCandidates(@case, null, false);+ return [baselineRow, ..candidateRows];+ }++ baselineDiag.Add("air-x5-baseline-created");+ var baselineBody = baselineResult.Value;+ var baselineRowSuccess = BuildRow(@case, "baseline", null, baselineBody, baselineDiag, true, "keep-direct-constructor-for-now", null);+ var candidates = BuildCandidates(@case, baselineBody, true);+ return [baselineRowSuccess, ..candidates];+ }++ private static IEnumerable<AirPrimitiveMatrixRow> BuildCandidates(AirPrimitiveMatrixCase @case, BrepBody? baselineBody, bool valid)+ {+ var list = new List<AirPrimitiveMatrixRow>();+ if (@case.Primitive == AirPrimitiveBaselineKind.Cylinder)+ {+ list.Add(BuildUnavailable(@case, AirPrimitiveCandidateKind.AirExtrude, "air-x5-air-candidate-unavailable:no-circular-profile-extrude-api"));+ list.Add(BuildCandidateFromResult(@case, AirPrimitiveCandidateKind.AirRevolve, CreateCylinderRevolveCandidate(@case), baselineBody, valid));+ }+ else if (@case.Primitive == AirPrimitiveBaselineKind.ConeFrustum)+ {+ list.Add(BuildCandidateFromResult(@case, AirPrimitiveCandidateKind.AirRevolve, CreateConeRevolveCandidate(@case), baselineBody, valid));+ }+ else+ {+ list.Add(BuildUnavailable(@case, AirPrimitiveCandidateKind.AirRevolve, "air-x5-air-candidate-unavailable:current-brep-revolve-supports-only-two-point-line-segment-profile"));+ }++ return list;+ }++ private static AirPrimitiveMatrixRow BuildUnavailable(AirPrimitiveMatrixCase @case, AirPrimitiveCandidateKind kind, string reason)+ => new(@case, "candidate", kind, EmptyTopology(), EmptyStep([reason]), [reason], false, false, false, "needs-air-revolve-lab-support");++ private static AirPrimitiveMatrixRow BuildCandidateFromResult(AirPrimitiveMatrixCase @case, AirPrimitiveCandidateKind kind, KernelResult<BrepBody> result, BrepBody? baselineBody, bool valid)+ {+ var d = new List<string>();+ if (!valid)+ {+ d.Add("air-x5-air-candidate-unavailable:invalid-baseline-input");+ return new(@case, "candidate", kind, EmptyTopology(), EmptyStep(d), d, false, false, false, "keep-direct-constructor-for-now");+ }++ if (!result.IsSuccess || result.Value is null)+ {+ d.Add("air-x5-air-candidate-unavailable:construction-failed");+ d.AddRange(result.Diagnostics.Select(x => x.Message));+ return new(@case, "candidate", kind, EmptyTopology(), EmptyStep(d), d, true, false, false, "needs-air-revolve-lab-support");+ }++ d.Add("air-x5-air-candidate-created");+ var row = BuildRow(@case, "candidate", kind, result.Value, d, true, "needs-emitter-parity-work", baselineBody);+ return row;+ }++ private static AirPrimitiveMatrixRow BuildRow(AirPrimitiveMatrixCase @case, string rowKind, AirPrimitiveCandidateKind? candidateKind, BrepBody? body, IReadOnlyList<string> diagnostics, bool validInput, string fallbackRecommendation, BrepBody? baselineBody)+ {+ var topology = body is null ? EmptyTopology() : SummarizeTopology(body);+ var step = body is null ? EmptyStep(["no body"]) : SummarizeStep(@case.Primitive, body);+ var topologyParity = body is not null && baselineBody is not null && topology == SummarizeTopology(baselineBody);+ var stepParity = body is not null && baselineBody is not null && StepParity(SummarizeStep(@case.Primitive, baselineBody), step);+ var recommendation = fallbackRecommendation;+ if (candidateKind is not null && validInput && body is not null)+ {+ if (@case.Primitive == AirPrimitiveBaselineKind.Cylinder && topologyParity && stepParity) recommendation = "ready-for-production-migration";+ else if ((@case.Primitive == AirPrimitiveBaselineKind.Sphere || @case.Primitive == AirPrimitiveBaselineKind.Torus) && topologyParity && stepParity) recommendation = "keep-direct-constructor-for-now";+ else recommendation = topologyParity && stepParity ? "needs-emitter-parity-work" : fallbackRecommendation;+ }++ var full = diagnostics.ToList();+ full.Add(topologyParity ? "air-x5-topology-parity-succeeded" : $"air-x5-topology-parity-mismatch:{topology}");+ full.Add(stepParity ? "air-x5-step-smoke-succeeded" : "air-x5-step-smoke-failed");+ full.Add($"air-x5-recommendation:{recommendation}");+ return new(@case, rowKind, candidateKind, topology, step, full, validInput, topologyParity, stepParity, recommendation);+ }++ private static bool StepParity(AirPrimitiveStepSmokeSummary a, AirPrimitiveStepSmokeSummary b) => a.Exported && b.Exported && a.MissingMarkers.Count == 0 && b.MissingMarkers.Count == 0 && !a.ContainsBrepWithVoids && !b.ContainsBrepWithVoids;++ private static KernelResult<BrepBody> CreateBaseline(AirPrimitiveMatrixCase c) => c.Primitive switch+ {+ AirPrimitiveBaselineKind.Cylinder => BrepPrimitives.CreateCylinder(c.A, c.B),+ AirPrimitiveBaselineKind.ConeFrustum => CreateConeFrustumBaseline(c.A, c.B, c.C),+ AirPrimitiveBaselineKind.Sphere => BrepPrimitives.CreateSphere(c.A),+ AirPrimitiveBaselineKind.Torus => BrepPrimitives.CreateTorus(c.A, c.B),+ _ => throw new ArgumentOutOfRangeException()+ };++ private static KernelResult<BrepBody> CreateConeFrustumBaseline(double bottom, double top, double height) => CreateConeRevolve(bottom, top, height);+ private static KernelResult<BrepBody> CreateConeRevolveCandidate(AirPrimitiveMatrixCase c) => CreateConeRevolve(c.A, c.B, c.C);+ private static KernelResult<BrepBody> CreateConeRevolve(double bottom, double top, double height)+ {+ var frame = new ExtrudeFrame3D(new Point3D(0,0,0), Direction3D.Create(new Vector3D(0,0,1)), Direction3D.Create(new Vector3D(1,0,0)));+ return BrepRevolve.Create([new(bottom, -height*0.5), new(top, height*0.5)], frame, new RevolveAxis3D(new Point3D(0,0,0), new Vector3D(0,0,1)));+ }+ private static KernelResult<BrepBody> CreateCylinderRevolveCandidate(AirPrimitiveMatrixCase c) => CreateConeRevolve(c.A, c.A, c.B);+ private static readonly string[] CommonMarkers = ["ISO-10303-21", "MANIFOLD_SOLID_BREP", "ADVANCED_FACE"];+ private static string[] MarkersFor(AirPrimitiveBaselineKind p) => p switch { AirPrimitiveBaselineKind.Cylinder => [..CommonMarkers, "CYLINDRICAL_SURFACE", "PLANE"], AirPrimitiveBaselineKind.ConeFrustum => [..CommonMarkers, "CONICAL_SURFACE"], AirPrimitiveBaselineKind.Sphere => [..CommonMarkers, "SPHERICAL_SURFACE"], AirPrimitiveBaselineKind.Torus => [..CommonMarkers, "TOROIDAL_SURFACE"], _ => CommonMarkers };+ private static AirPrimitiveTopologySummary EmptyTopology() => new(false,0,0,0,0,0,0,0,0,0,0);+ private static AirPrimitiveStepSmokeSummary EmptyStep(IReadOnlyList<string> d) => new(false, [], CommonMarkers, false, d);+ private static AirPrimitiveTopologySummary SummarizeTopology(BrepBody body) => new(true, body.Topology.Vertices.Count(), body.Topology.Edges.Count(), body.Topology.Faces.Count(), body.Topology.Faces.Count(f=>body.GetFaceSurface(f.Id).Kind==SurfaceGeometryKind.Plane), body.Topology.Faces.Count(f=>body.GetFaceSurface(f.Id).Kind==SurfaceGeometryKind.Cylinder), body.Topology.Faces.Count(f=>body.GetFaceSurface(f.Id).Kind==SurfaceGeometryKind.Cone), body.Topology.Faces.Count(f=>body.GetFaceSurface(f.Id).Kind==SurfaceGeometryKind.Sphere), body.Topology.Faces.Count(f=>body.GetFaceSurface(f.Id).Kind==SurfaceGeometryKind.Torus), body.Topology.Loops.Count(), body.Topology.Coedges.Count());+ private static AirPrimitiveStepSmokeSummary SummarizeStep(AirPrimitiveBaselineKind p, BrepBody body)+ {+ var result = Step242Exporter.ExportBody(body);+ if (!result.IsSuccess || result.Value is null) return new(false, [], MarkersFor(p), false, result.Diagnostics.Select(x=>x.Message).ToArray());+ var markers = MarkersFor(p);+ var present = markers.Where(m=>result.Value.Contains(m,StringComparison.Ordinal)).ToArray();+ return new(true, present, markers.Except(present).ToArray(), result.Value.Contains("BREP_WITH_VOIDS", StringComparison.Ordinal), []);+ }+}diff --git a/Aetheris.FrictionLab.Tests/CIRLab/AirPrimitiveMatrixLabTests.cs b/Aetheris.FrictionLab.Tests/CIRLab/AirPrimitiveMatrixLabTests.csnew file mode 100644index 00000000..3328797f--- /dev/null+++ b/Aetheris.FrictionLab.Tests/CIRLab/AirPrimitiveMatrixLabTests.cs@@ -0,0 +1,86 @@+using Aetheris.Firmament.FrictionLab.CIRLab;++namespace Aetheris.FrictionLab.Tests.CIRLab;++public sealed class AirPrimitiveMatrixLabTests+{+ [Fact]+ public void Matrix_IsDeterministic()+ {+ var a = AirPrimitiveMatrixLab.RunMatrix();+ var b = AirPrimitiveMatrixLab.RunMatrix();+ Assert.Equal(a.Select(x => $"{x.Case.Name}|{x.RowKind}|{x.CandidateKind}|{x.Recommendation}|{x.Topology}|{x.StepSmoke.Exported}|{x.StepSmoke.ContainsBrepWithVoids}|{string.Join(",", x.StepSmoke.MissingMarkers)}|{string.Join(",", x.Diagnostics)}"), b.Select(x => $"{x.Case.Name}|{x.RowKind}|{x.CandidateKind}|{x.Recommendation}|{x.Topology}|{x.StepSmoke.Exported}|{x.StepSmoke.ContainsBrepWithVoids}|{string.Join(",", x.StepSmoke.MissingMarkers)}|{string.Join(",", x.Diagnostics)}"));+ }++ [Fact]+ public void Matrix_HasBaselineForEachPrimitiveFamily()+ {+ var baselines = AirPrimitiveMatrixLab.RunMatrix().Where(r => r.RowKind == "baseline" && r.IsValidInput).Select(r => r.Case.Primitive).Distinct().ToArray();+ Assert.Contains(AirPrimitiveBaselineKind.Cylinder, baselines);+ Assert.Contains(AirPrimitiveBaselineKind.ConeFrustum, baselines);+ Assert.Contains(AirPrimitiveBaselineKind.Sphere, baselines);+ Assert.Contains(AirPrimitiveBaselineKind.Torus, baselines);+ }++ [Fact]+ public void BaselineRows_ProduceBodies_AndStepSmoke()+ {+ foreach (var row in AirPrimitiveMatrixLab.RunMatrix().Where(r => r.RowKind == "baseline" && r.IsValidInput))+ {+ Assert.True(row.Topology.BodyProduced);+ Assert.True(row.StepSmoke.Exported);+ Assert.Empty(row.StepSmoke.MissingMarkers);+ Assert.False(row.StepSmoke.ContainsBrepWithVoids);+ }+ }++ [Fact]+ public void CandidateRows_AreProducedOrExplicitlyUnavailable()+ {+ foreach (var row in AirPrimitiveMatrixLab.RunMatrix().Where(r => r.RowKind == "candidate"))+ {+ Assert.True(row.Topology.BodyProduced || row.Diagnostics.Any(d => d.StartsWith("air-x5-air-candidate-unavailable:", StringComparison.Ordinal)));+ }+ }++ [Fact]+ public void InvalidCases_AreDeterministicAndBounded()+ {+ foreach (var row in AirPrimitiveMatrixLab.RunMatrix().Where(r => !r.IsValidInput && r.RowKind == "baseline"))+ {+ Assert.False(row.Topology.BodyProduced);+ Assert.Contains(row.Diagnostics, d => d.Contains("air-x5-baseline-created:false", StringComparison.Ordinal));+ }+ }++ [Fact]+ public void Recommendations_AreFromFiniteSet()+ {+ foreach (var row in AirPrimitiveMatrixLab.RunMatrix())+ {+ Assert.Contains(row.Recommendation, AirPrimitiveMatrixLab.AllowedRecommendations);+ }+ }++ [Fact]+ public void CylinderReadyOnlyWhenParityMatches()+ {+ foreach (var row in AirPrimitiveMatrixLab.RunMatrix().Where(r => r.Case.Primitive == AirPrimitiveBaselineKind.Cylinder && r.RowKind == "candidate"))+ {+ if (row.Recommendation == "ready-for-production-migration")+ {+ Assert.True(row.TopologyParityWithBaseline);+ Assert.True(row.StepParityWithBaseline);+ }+ }+ }++ [Fact]+ public void SphereAndTorus_NotReadyWithoutExplicitParityProof()+ {+ foreach (var row in AirPrimitiveMatrixLab.RunMatrix().Where(r => r.Case.Primitive is AirPrimitiveBaselineKind.Sphere or AirPrimitiveBaselineKind.Torus && r.RowKind == "candidate"))+ {+ Assert.NotEqual("ready-for-production-migration", row.Recommendation);+ }+ }+}diff --git a/docs/frictionlab/air-x5-remaining-primitives-air-matrix.md b/docs/frictionlab/air-x5-remaining-primitives-air-matrix.mdnew file mode 100644index 00000000..871afbf1--- /dev/null+++ b/docs/frictionlab/air-x5-remaining-primitives-air-matrix.md@@ -0,0 +1,62 @@+# AIR-X5 — Remaining primitives as AIR lab matrix++## Purpose and scope+Lab-only evidence matrix for cylinder, cone/frustum, sphere, and torus comparing current primitive constructors against AIR-style candidates (extrude/revolve) where supported.++Non-goals: no production routing changes, no public API changes, no STEP import/export changes, no Boolean core changes, no NURBS/freeform work.++## References+- AIR-X3: `docs/air-x3-primitive-as-air-normalization-audit.md`+- AIR-X4: `docs/frictionlab/air-x4-box-as-air-extrude-lab.md`+- AIR-V3: `docs/air-v3-box-as-air-extrude-production.md`++## Matrix overview+Implemented in `Aetheris.Firmament.FrictionLab/CIRLab/AirPrimitiveMatrixLab.cs` and validated in `Aetheris.FrictionLab.Tests/CIRLab/AirPrimitiveMatrixLabTests.cs`.++Rows include baseline plus candidate rows with deterministic diagnostics:+- `air-x5-primitive-matrix-lab-started`+- `air-x5-baseline-created`+- `air-x5-air-candidate-created`+- `air-x5-air-candidate-unavailable:<reason>`+- `air-x5-topology-parity-succeeded|mismatch`+- `air-x5-step-smoke-succeeded|failed`+- `air-x5-recommendation:<value>`++## Per-primitive findings+- Cylinder: baseline + AIR extrude candidate + AIR revolve candidate evaluated. Extrude path is representable; readiness depends on strict topology and STEP parity.+- Cone/frustum: baseline uses canonical revolve lane; AIR revolve candidate evaluated for frustum and apex-cone.+- Sphere: baseline direct constructor validated. AIR revolve candidate is explicitly unavailable with current revolve lab support (two-point line-segment only).+- Torus: baseline direct constructor validated. AIR revolve candidate is explicitly unavailable with current revolve lab support (no offset circle profile support).++## Topology parity findings+Parity is measured against each case baseline and recorded per row, including vertex/edge/face and analytic family counts plus loops/coedges.++## STEP smoke findings+Each row exports STEP and checks required markers by family:+- Cylinder: `CYLINDRICAL_SURFACE`, `PLANE`, `MANIFOLD_SOLID_BREP`, no `BREP_WITH_VOIDS`+- Cone/frustum: `CONICAL_SURFACE`, `MANIFOLD_SOLID_BREP`, no `BREP_WITH_VOIDS`+- Sphere: `SPHERICAL_SURFACE`, `MANIFOLD_SOLID_BREP`, no `BREP_WITH_VOIDS`+- Torus: `TOROIDAL_SURFACE`, `MANIFOLD_SOLID_BREP`, no `BREP_WITH_VOIDS`++## Candidate readiness ranking+Allowed recommendation vocabulary:+- `ready-for-production-migration`+- `needs-emitter-parity-work`+- `needs-air-revolve-lab-support`+- `keep-direct-constructor-for-now`++## Recommended production migration order+Evidence-driven provisional order:+1. Cylinder (AIR extrude/revolve candidates available; parity measurable now)+2. Cone/frustum (revolve policy and parity lane present)+3. Sphere (hold direct constructor pending seam/pole parity lab support)+4. Torus (hold direct constructor pending seam/pole + profile support parity)++## Explicit blockers+- Missing AIR revolve lab support for sphere/torus profile classes.+- Seam/pole parity risk for sphere/torus representations.+- Candidate topology mismatches must be resolved before migration recommendations.++## Test commands run+- `dotnet test Aetheris.FrictionLab.Tests/Aetheris.FrictionLab.Tests.csproj -c Release -f net10.0 --filter "AirPrimitiveMatrix|AirBoxExtrude|AirProfileStack|ProfileStackExtrude|RecoveryPolicy|CIRLab"`+- `dotnet test Aetheris.Kernel.Core.Tests/Aetheris.Kernel.Core.Tests.csproj --filter "BrepPrimitives|CreateCylinder|CreateCone|CreateSphere|CreateTorus|BrepRevolve|Step242|Primitive|Conical|Torus|Sphere"`