Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-T7 tiered trim representation bridge

Yuechen Li0742caab6a04
diff --git a/Aetheris.Kernel.Firmament.Tests/TieredTrimRepresentationBuilderTests.cs b/Aetheris.Kernel.Firmament.Tests/TieredTrimRepresentationBuilderTests.cs
new file mode 100644
index 00000000..ab39fca0
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/TieredTrimRepresentationBuilderTests.cs
@@ -0,0 +1,92 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class TieredTrimRepresentationBuilderTests
+{
+ [Fact]
+ public void TieredTrim_CylinderCircleSelection_BuildsAnalyticCircleRepresentation()
+ {
+ var (field, stitched, selection) = BuildSelection(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 20)), 65, new RestrictedContourSnapOptions(0.06d, 0.02d, 8));
+ var result = TieredTrimRepresentationBuilder.Build(selection, stitched, field);
+
+ Assert.Equal(TieredTrimRepresentationKind.AnalyticCircle, result.Representation.Kind);
+ Assert.NotNull(result.Representation.Circle);
+ Assert.NotNull(result.Representation.NumericalContour);
+ Assert.Equal(TieredTrimExportCapability.ElementaryCurveCandidate, result.Representation.ExportCapability);
+ Assert.False(result.Representation.ExactStepExported);
+ Assert.False(result.Representation.BRepTopologyEmitted);
+ }
+
+ [Fact]
+ public void TieredTrim_SphereCircleSelection_BuildsAnalyticCircleRepresentation()
+ {
+ var (field, stitched, selection) = BuildSelection(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(6)), 65, new RestrictedContourSnapOptions(0.06d, 0.02d, 8));
+ var result = TieredTrimRepresentationBuilder.Build(selection, stitched, field);
+ Assert.Equal(TieredTrimRepresentationKind.AnalyticCircle, result.Representation.Kind);
+ Assert.NotNull(result.Representation.Circle);
+ }
+
+ [Fact]
+ public void TieredTrim_OpenLineSelection_BuildsAnalyticLineOrDeferredRepresentation()
+ {
+ var segA = new SurfaceTrimContourSegment2D(0, 0, new(0d, 0.25d), new(0.2d, 0.3d), RestrictedFieldCellClassification.Mixed, []);
+ var segB = new SurfaceTrimContourSegment2D(1, 0, new(0.2d, 0.3d), new(0.4d, 0.35d), RestrictedFieldCellClassification.Mixed, []);
+ var stitched = SurfaceTrimContourStitcher.Stitch(new SurfaceTrimContourExtractionResult(true, RestrictedFieldContourExtractionMethod.MarchingSquares, 2, [segA, segB], []));
+ var options = new RestrictedContourSnapOptions(0.02d, 0.05d, 3);
+ var selection = RestrictedContourSnapSelector.Select(stitched, RestrictedContourSnapAnalyzer.Analyze(stitched, options), options);
+ var result = TieredTrimRepresentationBuilder.Build(selection, stitched, null);
+
+ Assert.True(result.Representation.Kind is TieredTrimRepresentationKind.AnalyticLine or TieredTrimRepresentationKind.NumericalOnly or TieredTrimRepresentationKind.Deferred);
+ if (result.Representation.Kind != TieredTrimRepresentationKind.AnalyticLine)
+ {
+ Assert.Contains(result.Representation.Diagnostics, d => d.Contains("deferred", StringComparison.Ordinal) || d.Contains("numerical-only", StringComparison.Ordinal));
+ }
+ }
+
+ [Fact]
+ public void TieredTrim_Torus_DoesNotClaimGenericExactness()
+ {
+ var (field, stitched, selection) = BuildSelection(new CirSubtractNode(new CirBoxNode(12, 12, 12), new CirTorusNode(4, 1)), 65, new RestrictedContourSnapOptions(0.01d, 0.01d, 8));
+ var result = TieredTrimRepresentationBuilder.Build(selection, stitched, field);
+ Assert.Contains(result.Diagnostics, d => d == "tiered-trim-torus-generic-exactness-not-claimed");
+ Assert.False(result.Representation.ExactStepExported);
+ }
+
+ [Fact]
+ public void TieredTrim_NumericalOnly_IsNotExportable()
+ {
+ var chain = new SurfaceTrimContourChain2D(0, SurfaceTrimContourChainStatus.ClosedLoop, [new SurfaceTrimContourChainPoint2D(0,0,0,"A"), new SurfaceTrimContourChainPoint2D(1,1,0,"B")], [0], true, false, [], "k");
+ var stitched = new SurfaceTrimContourStitchResult(true, [chain], 1, 0, 0, 0, 0, []);
+ var candidate = new RestrictedContourSnapCandidate(0, RestrictedContourSnapKind.Circle, RestrictedContourSnapStatus.Rejected, null, 0.2d, 0.1d, 10, ["high-error"]);
+ var selection = RestrictedContourSnapSelector.Select(stitched, new RestrictedContourSnapAnalysisResult(true, [candidate], []), new RestrictedContourSnapOptions(0.01d, 0.01d, 2));
+
+ var result = TieredTrimRepresentationBuilder.Build(selection, stitched, null);
+ Assert.Equal(TieredTrimRepresentationKind.NumericalOnly, result.Representation.Kind);
+ Assert.Equal(TieredTrimExportCapability.NumericalOnlyNotExportable, result.Representation.ExportCapability);
+ }
+
+ [Fact]
+ public void TieredTrim_MissingProvenance_Diagnosed()
+ {
+ var chain = new SurfaceTrimContourChain2D(0, SurfaceTrimContourChainStatus.OpenChain, [new SurfaceTrimContourChainPoint2D(0,0,0,"A"), new SurfaceTrimContourChainPoint2D(1,0,0,"B")], [0], false, false, [], "k");
+ var stitched = new SurfaceTrimContourStitchResult(true, [chain], 0, 1, 0, 0, 0, []);
+ var candidate = new RestrictedContourSnapCandidate(0, RestrictedContourSnapKind.Line, RestrictedContourSnapStatus.Candidate, new LineSnapParameters2D(0,0,1,0), 0.001d, 0.001d, 10, []);
+ var selection = new RestrictedContourSnapSelectionResult(true, RestrictedContourSnapRouteKind.AnalyticLine, candidate, true, RestrictedContourExportCapability.ElementaryCurveCandidate, [], []);
+
+ var result = TieredTrimRepresentationBuilder.Build(selection, stitched, null);
+ Assert.Contains(result.Representation.SurfaceIntersectionProvenance.Diagnostics, d => d.StartsWith("tiered-trim-provenance-missing", StringComparison.Ordinal));
+ }
+
+ private static (SurfaceRestrictedField field, SurfaceTrimContourStitchResult stitched, RestrictedContourSnapSelectionResult selection) BuildSelection(CirSubtractNode root, int resolution, RestrictedContourSnapOptions options)
+ {
+ var source = Assert.Single(SourceSurfaceExtractor.Extract(root.Left).Descriptors.Where(d => d.ParameterPayloadReference == "top"));
+ var field = SurfaceRestrictedFieldFactory.ForSubtractSource(root, source, SubtractOperandSide.Left);
+ var grid = RestrictedFieldGridSampler.Sample(field, new RestrictedFieldGridOptions(resolution, resolution));
+ var extraction = RestrictedFieldMarchingSquaresExtractor.Extract(grid, field.Parameterization);
+ var stitched = SurfaceTrimContourStitcher.Stitch(extraction);
+ var selection = RestrictedContourSnapSelector.Select(stitched, RestrictedContourSnapAnalyzer.Analyze(stitched, options), options);
+ return (field, stitched, selection);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/TieredTrimRepresentationBuilder.cs b/Aetheris.Kernel.Firmament/Execution/TieredTrimRepresentationBuilder.cs
new file mode 100644
index 00000000..5e22d956
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/TieredTrimRepresentationBuilder.cs
@@ -0,0 +1,161 @@
+using Aetheris.Kernel.Core.Cir;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal enum TieredTrimRepresentationKind
+{
+ AnalyticLine,
+ AnalyticCircle,
+ NumericalOnly,
+ Deferred,
+ Unsupported,
+}
+
+internal enum TieredTrimExportCapability
+{
+ ElementaryCurveCandidate,
+ NumericalOnlyNotExportable,
+ Deferred,
+ Unsupported,
+}
+
+internal sealed record TrimSurfaceIntersectionProvenance(
+ string? SourceSurfaceKey,
+ SurfacePatchFamily? SourceSurfaceFamily,
+ string? OppositeFieldKind,
+ string? OppositeOperandRole,
+ IReadOnlyList<string> RestrictedFieldDiagnostics,
+ int? ChainId,
+ RestrictedContourSnapRouteKind SnapRoute,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record AnalyticCircleTrimData(
+ double CenterU,
+ double CenterV,
+ double RadiusUV,
+ double MaxError,
+ double MeanError,
+ int SampleCount);
+
+internal sealed record AnalyticLineTrimData(
+ double PointU,
+ double PointV,
+ double DirectionU,
+ double DirectionV,
+ double MaxError,
+ double MeanError,
+ int SampleCount);
+
+internal sealed record NumericalTrimContourData(
+ int ChainId,
+ IReadOnlyList<SurfaceTrimContourChainPoint2D> PointsUV,
+ bool Closed,
+ SurfaceTrimContourChainStatus Status,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record TieredTrimCurveRepresentation(
+ TieredTrimRepresentationKind Kind,
+ TieredTrimExportCapability ExportCapability,
+ AnalyticCircleTrimData? Circle,
+ AnalyticLineTrimData? Line,
+ NumericalTrimContourData? NumericalContour,
+ TrimSurfaceIntersectionProvenance SurfaceIntersectionProvenance,
+ bool AcceptedInternalAnalyticCandidate,
+ bool ExactStepExported,
+ bool BRepTopologyEmitted,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record TieredTrimRepresentationBuildResult(
+ bool Success,
+ TieredTrimCurveRepresentation Representation,
+ IReadOnlyList<string> Diagnostics);
+
+internal static class TieredTrimRepresentationBuilder
+{
+ internal static TieredTrimRepresentationBuildResult Build(
+ RestrictedContourSnapSelectionResult selection,
+ SurfaceTrimContourStitchResult stitchResult,
+ SurfaceRestrictedField? field)
+ {
+ ArgumentNullException.ThrowIfNull(selection);
+ ArgumentNullException.ThrowIfNull(stitchResult);
+
+ var diagnostics = new List<string> { "tiered-trim-build-started" };
+
+ var chainId = selection.SelectedCandidate?.ChainId;
+ var chain = chainId.HasValue ? stitchResult.Chains.FirstOrDefault(c => c.ChainId == chainId.Value) : stitchResult.Chains.FirstOrDefault();
+ var num = chain is null
+ ? null
+ : new NumericalTrimContourData(chain.ChainId, chain.Points, chain.Closed, chain.Status, chain.Diagnostics);
+
+ if (num is not null) diagnostics.Add("tiered-trim-numerical-contour-preserved");
+
+ var provenanceDiagnostics = new List<string>();
+ var provenance = BuildProvenance(field, chainId, selection.SelectedRoute, provenanceDiagnostics);
+ diagnostics.AddRange(provenanceDiagnostics);
+
+ TieredTrimCurveRepresentation rep;
+ switch (selection.SelectedRoute)
+ {
+ case RestrictedContourSnapRouteKind.AnalyticCircle when selection.SelectedCandidate?.Parameters is CircleSnapParameters2D circle:
+ rep = new TieredTrimCurveRepresentation(
+ TieredTrimRepresentationKind.AnalyticCircle,
+ TieredTrimExportCapability.ElementaryCurveCandidate,
+ new AnalyticCircleTrimData(circle.CenterU, circle.CenterV, circle.Radius, selection.SelectedCandidate.MaxError, selection.SelectedCandidate.MeanError, selection.SelectedCandidate.SampleCount),
+ null,
+ num,
+ provenance,
+ true,
+ false,
+ false,
+ ["tiered-trim-analytic-circle-representation-built", "tiered-trim-export-capability-candidate-only", "tiered-trim-step-export-not-performed", "tiered-trim-brep-topology-not-emitted", "tiered-trim-torus-generic-exactness-not-claimed"]);
+ break;
+ case RestrictedContourSnapRouteKind.AnalyticLine when selection.SelectedCandidate?.Parameters is LineSnapParameters2D line:
+ rep = new TieredTrimCurveRepresentation(
+ TieredTrimRepresentationKind.AnalyticLine,
+ TieredTrimExportCapability.ElementaryCurveCandidate,
+ null,
+ new AnalyticLineTrimData(line.PointU, line.PointV, line.DirectionU, line.DirectionV, selection.SelectedCandidate.MaxError, selection.SelectedCandidate.MeanError, selection.SelectedCandidate.SampleCount),
+ num,
+ provenance,
+ true,
+ false,
+ false,
+ ["tiered-trim-analytic-line-representation-built", "tiered-trim-export-capability-candidate-only", "tiered-trim-step-export-not-performed", "tiered-trim-brep-topology-not-emitted"]);
+ break;
+ case RestrictedContourSnapRouteKind.NumericalOnly:
+ rep = new TieredTrimCurveRepresentation(TieredTrimRepresentationKind.NumericalOnly, TieredTrimExportCapability.NumericalOnlyNotExportable, null, null, num, provenance, false, false, false,
+ ["tiered-trim-numerical-only-not-exportable", "tiered-trim-step-export-not-performed", "tiered-trim-brep-topology-not-emitted", "tiered-trim-torus-generic-exactness-not-claimed"]);
+ break;
+ case RestrictedContourSnapRouteKind.Deferred:
+ rep = new TieredTrimCurveRepresentation(TieredTrimRepresentationKind.Deferred, TieredTrimExportCapability.Deferred, null, null, num, provenance, false, false, false,
+ ["tiered-trim-deferred", "tiered-trim-step-export-not-performed", "tiered-trim-brep-topology-not-emitted", "tiered-trim-torus-generic-exactness-not-claimed"]);
+ break;
+ default:
+ rep = new TieredTrimCurveRepresentation(TieredTrimRepresentationKind.Unsupported, TieredTrimExportCapability.Unsupported, null, null, num, provenance, false, false, false,
+ ["tiered-trim-unsupported", "tiered-trim-step-export-not-performed", "tiered-trim-brep-topology-not-emitted", "tiered-trim-torus-generic-exactness-not-claimed"]);
+ break;
+ }
+
+ diagnostics.AddRange(rep.Diagnostics);
+ return new TieredTrimRepresentationBuildResult(selection.Success && stitchResult.Success, rep, diagnostics);
+ }
+
+ private static TrimSurfaceIntersectionProvenance BuildProvenance(SurfaceRestrictedField? field, int? chainId, RestrictedContourSnapRouteKind route, List<string> diagnostics)
+ {
+ var d = new List<string>();
+ var sourceKey = field?.SourceSurface.ParameterPayloadReference;
+ var sourceFamily = field?.SourceSurface.Family;
+ if (string.IsNullOrWhiteSpace(sourceKey)) d.Add("tiered-trim-provenance-missing-source-surface-key");
+ var oppositeKind = field?.OppositeTape is null ? null : "CirTape";
+ if (oppositeKind is null) d.Add("tiered-trim-provenance-missing-opposite-field-kind");
+
+ var side = field?.Diagnostics.FirstOrDefault(x => x.StartsWith("opposite-operand-selected:", StringComparison.Ordinal));
+ var role = side?.Split(':').LastOrDefault();
+ if (role is null) d.Add("tiered-trim-provenance-missing-opposite-operand-role");
+
+ diagnostics.Add(d.Count == 0 ? "tiered-trim-surface-intersection-provenance-preserved" : "tiered-trim-surface-intersection-provenance-partial");
+
+ return new TrimSurfaceIntersectionProvenance(sourceKey, sourceFamily, oppositeKind, role, field?.Diagnostics ?? [], chainId, route, d);
+ }
+}
diff --git a/docs/cir-t7-tiered-trim-representation.md b/docs/cir-t7-tiered-trim-representation.md
new file mode 100644
index 00000000..6d8d6347
--- /dev/null
+++ b/docs/cir-t7-tiered-trim-representation.md
@@ -0,0 +1,60 @@
+# CIR-T7: Selected trim candidate → tiered trim representation bridge
+
+## Purpose
+
+CIR-T7 adds an internal bridge from CIR-T6 snap selection results into a tiered trim representation object.
+It is diagnostic-first and behavior-preserving: accepted analytic candidates remain internal only.
+
+## Tiered representation model
+
+`TieredTrimCurveRepresentation` carries three layers:
+
+1. **Analytic tier** (`AnalyticLine` / `AnalyticCircle` data in UV, with errors)
+2. **Numerical tier** (stitched chain points and status)
+3. **Surface-intersection provenance tier** (source surface key/family, opposite field role/kind, route and chain)
+
+It also carries explicit state flags:
+
+- `AcceptedInternalAnalyticCandidate`
+- `ExactStepExported=false`
+- `BRepTopologyEmitted=false`
+
+## Export capability distinction
+
+CIR-T7 maps to explicit internal export capability states:
+
+- `ElementaryCurveCandidate` (future line/circle export could be possible)
+- `NumericalOnlyNotExportable`
+- `Deferred`
+- `Unsupported`
+
+`ElementaryCurveCandidate` does **not** imply STEP export happened.
+
+## Route behavior
+
+- `AnalyticCircle` selection builds an analytic-circle representation + numerical contour + provenance.
+- `AnalyticLine` selection builds an analytic-line representation + numerical contour + provenance.
+- `NumericalOnly` preserves numerical contour and marks not exportable.
+- `Deferred` / `Unsupported` preserve diagnostics and stay non-exported.
+
+## Torus policy
+
+CIR-T7 preserves candidate-only semantics and never claims generic torus exactness.
+No quartic recognition is introduced.
+
+## Non-goals (unchanged)
+
+- No BRep edge/coedge/loop emission
+- No STEP curve entity emission
+- No retained-loop descriptor mutation
+- No BSpline fitting
+- No boolean behavior change
+- No public CLI behavior change
+
+## JudgmentEngine usage
+
+No new JudgmentEngine use was introduced in T7. The bridge is deterministic mapping from T6 selected route into representation.
+
+## Next step (T8)
+
+Integrate tiered trim representations into retained loop descriptors/materialization planning while preserving SEM-A0 naming/provenance guardrails and keeping export semantics explicit.