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