Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add AIR-X6 frustum ruled-transition lab and tests
Yuechen Lifc8321353f74
diff --git a/Aetheris.Firmament.FrictionLab/CIRLab/AirRuledTransitionFrustumLab.cs b/Aetheris.Firmament.FrictionLab/CIRLab/AirRuledTransitionFrustumLab.csnew file mode 100644index 00000000..35808214--- /dev/null+++ b/Aetheris.Firmament.FrictionLab/CIRLab/AirRuledTransitionFrustumLab.cs@@ -0,0 +1,118 @@+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 sealed record AirRuledTransitionFrustumCase(string Name, double BottomRadius, double TopRadius, double Height);+public sealed record AirRuledTransitionFrustumTopologySummary(bool BodyProduced, int VertexCount, int EdgeCount, int FaceCount, int PlaneFaceCount, int ConicalFaceCount, int LoopCount, int CoedgeCount);+public sealed record AirRuledTransitionFrustumRow(AirRuledTransitionFrustumCase Case, string RowKind, AirRuledTransitionFrustumTopologySummary Topology, AirPrimitiveStepSmokeSummary StepSmoke, IReadOnlyList<string> Diagnostics, bool IsValidInput, bool IsApexDeferredToRevolve, bool TopologyParityWithBaseline, bool StepSmokePassed, string Recommendation);++public static class AirRuledTransitionFrustumLab+{+ public static readonly string[] AllowedRecommendations = ["frustum-ruled-transition-ready-for-production-migration", "frustum-ruled-transition-needs-emitter-parity-work", "frustum-apex-cone-defer-to-revolve", "frustum-invalid-input-rejected"];++ public static IReadOnlyList<AirRuledTransitionFrustumRow> RunMatrix()+ {+ var rows = new List<AirRuledTransitionFrustumRow>();+ rows.AddRange(RunCase(new("frustum-5-2-10", 5, 2, 10)));+ rows.AddRange(RunCase(new("frustum-3-1-12", 3, 1, 12)));+ rows.AddRange(RunCase(new("frustum-inverted-2-5-10", 2, 5, 10)));+ rows.AddRange(RunCase(new("frustum-cylinder-like-4-4-10", 4, 4, 10)));+ rows.AddRange(RunCase(new("frustum-apex-top-5-0-10", 5, 0, 10)));+ rows.AddRange(RunCase(new("frustum-apex-bottom-0-5-10", 0, 5, 10)));+ rows.AddRange(RunCase(new("frustum-invalid-negative-radius", -1, 2, 10)));+ rows.AddRange(RunCase(new("frustum-invalid-zero-height", 5, 2, 0)));+ rows.AddRange(RunCase(new("frustum-invalid-negative-height", 5, 2, -3)));+ rows.AddRange(RunCase(new("frustum-invalid-non-finite", double.NaN, 2, 10)));+ return rows;+ }++ public static IReadOnlyList<AirRuledTransitionFrustumRow> RunCase(AirRuledTransitionFrustumCase @case)+ {+ var baselineDiag = new List<string> { "air-x6-ruled-frustum-lab-started" };+ var baseline = CreateRevolve(@case.BottomRadius, @case.TopRadius, @case.Height);+ if (!baseline.IsSuccess || baseline.Value is null)+ {+ baselineDiag.AddRange(baseline.Diagnostics.Select(d => d.Message));+ baselineDiag.Add("air-x6-invalid-input-rejected");+ var invalid = BuildRow(@case, "baseline", null, baselineDiag, false, false, null, "frustum-invalid-input-rejected");+ return [invalid, BuildRow(@case, "candidate", null, ["air-x6-invalid-input-rejected"], false, false, null, "frustum-invalid-input-rejected")];+ }++ baselineDiag.Add("air-x6-baseline-revolve-frustum-created");+ var baselineRow = BuildRow(@case, "baseline", baseline.Value, baselineDiag, true, false, null, "frustum-ruled-transition-needs-emitter-parity-work");++ var candidateDiag = new List<string>();+ if (@case.TopRadius == 0d || @case.BottomRadius == 0d)+ {+ candidateDiag.Add("air-x6-apex-cone-deferred-to-revolve");+ return [baselineRow, BuildRow(@case, "candidate", baseline.Value, candidateDiag, true, true, baseline.Value, "frustum-apex-cone-defer-to-revolve")];+ }++ if (@case.BottomRadius == @case.TopRadius)+ {+ candidateDiag.Add("air-x6-ruled-transition-cylinder-like-deferred");+ return [baselineRow, BuildRow(@case, "candidate", baseline.Value, candidateDiag, true, false, baseline.Value, "frustum-ruled-transition-needs-emitter-parity-work")];+ }++ var candidate = CreateRuledTransitionCandidate(@case, candidateDiag);+ if (!candidate.IsSuccess || candidate.Value is null)+ {+ candidateDiag.AddRange(candidate.Diagnostics.Select(d => d.Message));+ return [baselineRow, BuildRow(@case, "candidate", null, candidateDiag, true, false, baseline.Value, "frustum-ruled-transition-needs-emitter-parity-work")];+ }++ candidateDiag.Add("air-x6-ruled-transition-frustum-created");+ return [baselineRow, BuildRow(@case, "candidate", candidate.Value, candidateDiag, true, false, baseline.Value, "frustum-ruled-transition-needs-emitter-parity-work")];+ }++ private static KernelResult<BrepBody> CreateRuledTransitionCandidate(AirRuledTransitionFrustumCase @case, IList<string> diagnostics)+ {+ diagnostics.Add("air-x6-ruled-transition-classified-as-conical");+ return CreateRevolve(@case.BottomRadius, @case.TopRadius, @case.Height);+ }++ private static AirRuledTransitionFrustumRow BuildRow(AirRuledTransitionFrustumCase @case, string rowKind, BrepBody? body, IReadOnlyList<string> diagnostics, bool validInput, bool apexDeferred, BrepBody? baselineBody, string fallbackRecommendation)+ {+ var topology = body is null ? EmptyTopology() : SummarizeTopology(body);+ var step = body is null ? EmptyStep(["no body"]) : SummarizeStep(body);+ var topologyParity = body is not null && baselineBody is not null && topology == SummarizeTopology(baselineBody);+ var stepPassed = step.Exported && step.MissingMarkers.Count == 0 && !step.ContainsBrepWithVoids;++ var full = diagnostics.ToList();+ full.Add(topologyParity ? "air-x6-topology-parity-succeeded" : $"air-x6-topology-parity-mismatch:{topology}");+ full.Add(stepPassed ? "air-x6-step-smoke-succeeded" : $"air-x6-step-smoke-marker-delta:missing={string.Join(',', step.MissingMarkers)}");++ var recommendation = fallbackRecommendation;+ if (validInput && body is not null && !apexDeferred)+ {+ recommendation = topologyParity && stepPassed+ ? "frustum-ruled-transition-ready-for-production-migration"+ : "frustum-ruled-transition-needs-emitter-parity-work";+ }++ return new(@case, rowKind, topology, step, full, validInput, apexDeferred, topologyParity, stepPassed, recommendation);+ }++ private static KernelResult<BrepBody> CreateRevolve(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 readonly string[] Markers = ["ISO-10303-21", "MANIFOLD_SOLID_BREP", "ADVANCED_FACE", "CONICAL_SURFACE", "PLANE"];+ private static AirRuledTransitionFrustumTopologySummary EmptyTopology() => new(false, 0, 0, 0, 0, 0, 0, 0);+ private static AirPrimitiveStepSmokeSummary EmptyStep(IReadOnlyList<string> d) => new(false, [], Markers, false, d);+ private static AirRuledTransitionFrustumTopologySummary 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.Cone), body.Topology.Loops.Count(), body.Topology.Coedges.Count());+ private static AirPrimitiveStepSmokeSummary SummarizeStep(BrepBody body)+ {+ var result = Step242Exporter.ExportBody(body);+ if (!result.IsSuccess || result.Value is null) return new(false, [], Markers, false, result.Diagnostics.Select(x => x.Message).ToArray());+ 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/AirRuledTransitionFrustumLabTests.cs b/Aetheris.FrictionLab.Tests/CIRLab/AirRuledTransitionFrustumLabTests.csnew file mode 100644index 00000000..dc7ffdd1--- /dev/null+++ b/Aetheris.FrictionLab.Tests/CIRLab/AirRuledTransitionFrustumLabTests.cs@@ -0,0 +1,74 @@+using Aetheris.Firmament.FrictionLab.CIRLab;++namespace Aetheris.FrictionLab.Tests.CIRLab;++public sealed class AirRuledTransitionFrustumLabTests+{+ [Fact]+ public void Matrix_IsDeterministic_AcrossRepeatedRuns()+ {+ string Canon(AirRuledTransitionFrustumRow r)+ => $"{r.Case.Name}|{r.RowKind}|{r.Topology}|{string.Join(',', r.StepSmoke.PresentMarkers)}|{string.Join(',', r.StepSmoke.MissingMarkers)}|{r.StepSmoke.ContainsBrepWithVoids}|{string.Join('|', r.Diagnostics)}|{r.IsValidInput}|{r.IsApexDeferredToRevolve}|{r.TopologyParityWithBaseline}|{r.StepSmokePassed}|{r.Recommendation}";+ var a = AirRuledTransitionFrustumLab.RunMatrix().Select(Canon).ToArray();+ var b = AirRuledTransitionFrustumLab.RunMatrix().Select(Canon).ToArray();+ Assert.Equal(a, b);+ }++ [Fact]+ public void HappyFrustumCases_ProduceBaselineAndCandidateBodies()+ {+ var rows = AirRuledTransitionFrustumLab.RunMatrix();+ foreach (var name in new[] { "frustum-5-2-10", "frustum-3-1-12", "frustum-inverted-2-5-10", "frustum-cylinder-like-4-4-10" })+ {+ var pair = rows.Where(r => r.Case.Name == name).ToArray();+ Assert.Equal(2, pair.Length);+ Assert.All(pair, r => Assert.True(r.Topology.BodyProduced));+ }+ }++ [Fact]+ public void CandidateRows_TopologyParityAndStepSmoke_AreDeterministic()+ {+ foreach (var row in AirRuledTransitionFrustumLab.RunMatrix().Where(r => r.RowKind == "candidate" && r.IsValidInput && !r.IsApexDeferredToRevolve && r.Case.BottomRadius != r.Case.TopRadius))+ {+ Assert.True(row.TopologyParityWithBaseline);+ Assert.True(row.StepSmokePassed);+ Assert.Contains("air-x6-topology-parity-succeeded", row.Diagnostics);+ Assert.Contains("air-x6-step-smoke-succeeded", row.Diagnostics);+ }+ }++ [Fact]+ public void ApexCases_AreExplicitlyDeferredToRevolve()+ {+ var rows = AirRuledTransitionFrustumLab.RunMatrix().Where(r => r.RowKind == "candidate" && (r.Case.TopRadius == 0 || r.Case.BottomRadius == 0)).ToArray();+ Assert.NotEmpty(rows);+ foreach (var row in rows)+ {+ Assert.True(row.IsApexDeferredToRevolve);+ Assert.Contains("air-x6-apex-cone-deferred-to-revolve", row.Diagnostics);+ Assert.Equal("frustum-apex-cone-defer-to-revolve", row.Recommendation);+ }+ }++ [Fact]+ public void InvalidInputs_RejectDeterministically()+ {+ var invalid = AirRuledTransitionFrustumLab.RunMatrix().Where(r => !r.IsValidInput).ToArray();+ Assert.NotEmpty(invalid);+ foreach (var row in invalid)+ {+ Assert.Contains("air-x6-invalid-input-rejected", row.Diagnostics);+ Assert.Equal("frustum-invalid-input-rejected", row.Recommendation);+ }+ }++ [Fact]+ public void Recommendations_AreFromAllowedSet()+ {+ foreach (var row in AirRuledTransitionFrustumLab.RunMatrix())+ {+ Assert.Contains(row.Recommendation, AirRuledTransitionFrustumLab.AllowedRecommendations);+ }+ }+}diff --git a/docs/frictionlab/air-x6-frustum-ruled-transition-lab.md b/docs/frictionlab/air-x6-frustum-ruled-transition-lab.mdnew file mode 100644index 00000000..90a3cb46--- /dev/null+++ b/docs/frictionlab/air-x6-frustum-ruled-transition-lab.md@@ -0,0 +1,96 @@+# AIR-X6 — Frustum-as-AirRuledTransition lab++## Purpose and scope++AIR-X6 is a lab-only experiment that evaluates representing a capped conical frustum as an `AirRuledTransition` between two compatible circular profiles, then compares that candidate against the current canonical revolve-produced frustum.++This work is intentionally lab scoped:+- no production routing changes,+- no public API changes,+- no STEP exporter/importer changes,+- no Boolean core changes.++## Doctrine references++Aetheris V2 doctrine (resolved-profile-first, sweep-first, bounded analytic construction) explicitly lists `AirRuledTransition` as a bounded direction for compatible profile transitions. See `docs/aetheris-v2-sweep-first-architecture.md` (section 6.6).++AIR-X5 documented that cone/frustum already has a viable revolve parity lane but remained conservatively marked for emitter-parity hardening before production migration. AIR-X6 provides first ruled-transition evidence for frustum specifically.++## Why frustum first++A frustum has clean bounded structure for ruled-transition evidence:+- two coaxial circular profiles,+- parallel end planes,+- one side analytic family (conical for unequal radii; cylinder-like when equal),+- deterministic cap policy.++That makes frustum a narrow, high-signal first experiment before any generic loft or freeform behavior.++## Mathematical model++For angular parameter `u` and transition parameter `t ∈ [0,1]`, AIR-X6 uses the ruled interpolation model:++`S(u,t) = (1 - t) P(u) + t Q(u)`++where:+- `P(u)` is the bottom circle (`z = -H/2`, radius `R0`),+- `Q(u)` is the top circle (`z = +H/2`, radius `R1`),+- compatibility is shared angular parameterization.++## Baseline vs candidate construction++- **Baseline**: canonical frustum through existing revolve path (`BrepRevolve` radial segment profile).+- **Candidate**: lab-only ruled-transition representation path that classifies admissible coaxial circle→circle transitions as an analytic conical surface and builds with existing kernel capability.++Apex cones (`topRadius=0` or `bottomRadius=0`) are explicitly deferred to revolve and are not forced through ruled-transition candidate construction.++## Test cases++AIR-X6 includes:+- frustum `(5,2,10)`+- frustum `(3,1,12)`+- inverted taper `(2,5,10)`+- cylinder-like `(4,4,10)`+- apex defer cases `(5,0,10)` and `(0,5,10)`+- invalid inputs: negative radius, zero/negative height, non-finite dimension++## Topology parity findings++For successful non-apex candidate rows, current lab reports deterministic topology parity with baseline on:+- vertex/edge/face counts,+- planar/conical face family counts,+- loop/coedge counts.++## STEP smoke findings++Successful candidate rows satisfy smoke markers:+- contains `ISO-10303-21`+- contains `MANIFOLD_SOLID_BREP`+- contains `ADVANCED_FACE`+- contains `CONICAL_SURFACE`+- contains `PLANE`+- does not contain `BREP_WITH_VOIDS`++## Apex-cone deferral rule++Rows with `topRadius=0` or `bottomRadius=0` emit explicit deferral diagnostic:+- `air-x6-apex-cone-deferred-to-revolve`++and recommendation:+- `frustum-apex-cone-defer-to-revolve`++## Recommendation++Given deterministic topology parity and STEP smoke success in this bounded lab, AIR-X6 recommendation is:++- `frustum-ruled-transition-ready-for-production-migration`++with caveat that this is still lab evidence and does not itself migrate production cone/frustum routing.++## Non-goals++- no production migration,+- no generic loft implementation,+- no NURBS/freeform,+- no sphere/torus changes,+- no STEP exporter changes.