Skip to content

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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.md
new file mode 100644
index 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.