Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Implement CIR-T9 selected-opposite field routing for trim oracle
Yuechen Li9085ca959d20
diff --git a/Aetheris.Kernel.Firmament.Tests/RetainedLoopTrimOracleIntegrationTests.cs b/Aetheris.Kernel.Firmament.Tests/RetainedLoopTrimOracleIntegrationTests.csindex 4626a8be..0bc2e84f 100644--- a/Aetheris.Kernel.Firmament.Tests/RetainedLoopTrimOracleIntegrationTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/RetainedLoopTrimOracleIntegrationTests.cs@@ -6,36 +6,42 @@ namespace Aetheris.Kernel.Firmament.Tests;public sealed class RetainedLoopTrimOracleIntegrationTests{[Fact]- public void OracleTrimRouting_BoxCylinder_SelectsSpecificOpposite()+ public void OracleTrimSelectedField_BoxCylinder_UsesSelectedCylinderField(){var result = FacePatchCandidateGenerator.Generate(new CirSubtractNode(new CirBoxNode(10,10,10), new CirCylinderNode(2,20)));var loop = result.Candidates.SelectMany(c => c.RetainedRegionLoops).First(l => l.OracleTrimRepresentation is not null && l.OracleTrimStrongEvidence);- Assert.Equal("oracle-trim: specific-opposite-selected", loop.OracleTrimRoutingDiagnostic);+ Assert.Equal("oracle-trim: selected-opposite-field-used", loop.OracleTrimRoutingDiagnostic);Assert.Equal(TieredTrimRepresentationKind.AnalyticCircle, loop.OracleTrimRepresentation!.Kind);Assert.False(loop.OracleTrimRepresentation.ExactStepExported);Assert.False(loop.OracleTrimRepresentation.BRepTopologyEmitted);}[Fact]- public void OracleTrimRouting_BoxSphere_SelectsSpecificOpposite()+ public void OracleTrimSelectedField_CylinderMatchesBroadSimpleCase()+ {+ var result = FacePatchCandidateGenerator.Generate(new CirSubtractNode(new CirBoxNode(10,10,10), new CirCylinderNode(2,20)));+ var loop = result.Candidates.SelectMany(c => c.RetainedRegionLoops).First(l => l.OracleTrimStrongEvidence);+ Assert.NotNull(loop.OracleTrimRepresentation?.Circle);+ Assert.True(loop.OracleTrimRepresentation!.Circle!.RadiusUV > 0d);+ }++ [Fact]+ public void OracleTrimSelectedField_BoxSphere_DefersOrUsesSelectedSphereField(){var result = FacePatchCandidateGenerator.Generate(new CirSubtractNode(new CirBoxNode(10,10,10), new CirSphereNode(6)));- Assert.Contains(result.Candidates.SelectMany(c => c.RetainedRegionLoops), l => l.OracleTrimRoutingDiagnostic == "oracle-trim: specific-opposite-selected");+ Assert.Contains(result.Candidates.SelectMany(c => c.RetainedRegionLoops), l => l.OracleTrimRoutingDiagnostic.Contains("selected-opposite-field-deferred:selected-opposite-field: sphere-geometry-missing", StringComparison.Ordinal));+ Assert.DoesNotContain(result.Candidates.SelectMany(c => c.RetainedRegionLoops), l => l.OracleTrimStrongEvidence && l.OppositeSurfaceFamily == SurfacePatchFamily.Spherical);}[Fact]- public void OracleTrimRouting_BoxTorus_NoGenericExactness()+ public void OracleTrimSelectedField_BoxTorus_DefersOrUsesSelectedTorusFieldWithoutGenericExactness(){var result = FacePatchCandidateGenerator.Generate(new CirSubtractNode(new CirBoxNode(12,12,12), new CirTorusNode(4,1)));- var oracle = result.Candidates.SelectMany(c => c.RetainedRegionLoops).Select(l => l.OracleTrimRepresentation).FirstOrDefault(r => r is not null);- Assert.NotNull(oracle);- Assert.False(oracle!.ExactStepExported);- Assert.False(oracle.BRepTopologyEmitted);- Assert.Contains(oracle.Diagnostics, d => d.Contains("torus-generic-exactness-not-claimed", StringComparison.Ordinal));+ Assert.Contains(result.Candidates.SelectMany(c => c.RetainedRegionLoops), l => l.OracleTrimRoutingDiagnostic.Contains("selected-opposite-field-deferred:selected-opposite-field: torus-geometry-missing", StringComparison.Ordinal));}[Fact]- public void OracleTrimRouting_MultipleOpposites_Defers()+ public void OracleTrimSelectedField_MultipleOpposites_StillDefers(){var root = new CirSubtractNode(new CirBoxNode(10,10,10), new CirUnionNode(new CirCylinderNode(2,20), new CirCylinderNode(2,20)));var result = FacePatchCandidateGenerator.Generate(root);@@ -43,19 +49,12 @@ public sealed class RetainedLoopTrimOracleIntegrationTests}[Fact]- public void OracleTrimRouting_MissingOpposite_Diagnosed()- {- var loop = new RetainedRegionLoopDescriptor(RetainedRegionLoopKind.InnerTrim, TrimCurveFamily.Circle, TrimCapabilityClassification.ExactSupported, SurfacePatchFamily.Planar, SurfacePatchFamily.Spherical,- FacePatchOrientationRole.Forward, FacePatchRetentionRole.BaseBoundaryRetainedOutsideTool, RetainedRegionLoopStatus.ExactReady, "missing", "diag", null, null, false, "oracle-trim: missing-opposite-source");- Assert.Equal("oracle-trim: missing-opposite-source", loop.OracleTrimRoutingDiagnostic);- }-- [Fact]- public void MaterializationReadiness_TrimOracleLayer_DistinguishesStrongVsBroad()+ public void MaterializationReadiness_ReportsSelectedFieldVsDeferred(){var report = MaterializationReadinessAnalyzer.Analyze(new CirSubtractNode(new CirBoxNode(10,10,10), new CirCylinderNode(2,20)));var layer = report.LayerSummaries.Single(l => l.LayerName == "trim-oracle-evidence");Assert.True(layer.Counts.ContainsKey("strong-trim-oracle"));- Assert.True(layer.Diagnostics.Any(d => d.StartsWith("oracle-trim:", StringComparison.Ordinal)));+ Assert.True(layer.Counts.ContainsKey("selected-field-deferred-trim-oracle"));+ Assert.True(layer.Counts.ContainsKey("broad-only-trim-oracle"));}}diff --git a/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.cs b/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.csindex db62bf64..74b3ce2f 100644--- a/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.cs+++ b/Aetheris.Kernel.Firmament/Execution/MaterializationReadinessAnalyzer.cs@@ -218,6 +218,8 @@ internal static class MaterializationReadinessAnalyzer{["trim-oracle-representations"] = reps.Length,["strong-trim-oracle"] = candidates.Candidates.SelectMany(c => c.RetainedRegionLoops).Count(l => l.OracleTrimStrongEvidence),+ ["selected-field-deferred-trim-oracle"] = candidates.Candidates.SelectMany(c => c.RetainedRegionLoops).Count(l => l.OracleTrimRoutingDiagnostic.StartsWith("oracle-trim: selected-opposite-field-deferred:", StringComparison.Ordinal)),+ ["broad-only-trim-oracle"] = candidates.Candidates.SelectMany(c => c.RetainedRegionLoops).Count(l => l.OracleTrimRoutingDiagnostic == "oracle-trim: broad-opposite-field-only"),["broad-or-deferred-trim-oracle"] = candidates.Candidates.SelectMany(c => c.RetainedRegionLoops).Count(l => !l.OracleTrimStrongEvidence && l.OracleTrimRepresentation is not null),["analytic-circle"] = reps.Count(r => r!.Circle is not null),["numerical-contours"] = reps.Count(r => r!.NumericalContour is not null)diff --git a/Aetheris.Kernel.Firmament/Execution/RetainedLoopTrimOracleIntegrator.cs b/Aetheris.Kernel.Firmament/Execution/RetainedLoopTrimOracleIntegrator.csindex 3944de0f..f093c0e7 100644--- a/Aetheris.Kernel.Firmament/Execution/RetainedLoopTrimOracleIntegrator.cs+++ b/Aetheris.Kernel.Firmament/Execution/RetainedLoopTrimOracleIntegrator.cs@@ -30,8 +30,23 @@ internal static class RetainedLoopTrimOracleIntegratorvar matches = oppositeSet.Where(o => o.Provenance == loop.OppositeSurfaceProvenance && o.Family == loop.OppositeSurfaceFamily).ToArray();if (matches.Length == 1){- var oracle = BuildLoopRepresentation(subtract, source, sourceSide);- loops.Add(loop with { OracleTrimRepresentation = oracle, OracleTrimStrongEvidence = true, OracleTrimRoutingDiagnostic = "oracle-trim: specific-opposite-selected" });+ var selected = matches[0];+ var build = SelectedOppositeFieldBuilder.TryBuild(selected);+ if (build.Status == SelectedOppositeFieldBuildStatus.Success && build.Node is not null)+ {+ var oracle = BuildLoopRepresentation(source, build.Node, "selected-opposite-field-used");+ loops.Add(loop with { OracleTrimRepresentation = oracle, OracleTrimStrongEvidence = true, OracleTrimRoutingDiagnostic = "oracle-trim: selected-opposite-field-used" });+ }+ else+ {+ loops.Add(loop with+ {+ OracleTrimRepresentation = null,+ OracleTrimStrongEvidence = false,+ OracleTrimRoutingDiagnostic = $"oracle-trim: selected-opposite-field-deferred:{build.Diagnostic}"+ });+ }+continue;}@@ -43,7 +58,7 @@ internal static class RetainedLoopTrimOracleIntegratorvar familyMatches = oppositeSet.Where(o => o.Family == loop.OppositeSurfaceFamily).ToArray();var routing = familyMatches.Length > 0 ? "oracle-trim: broad-opposite-field-only" : "oracle-trim: missing-opposite-source";- var oracleBroad = familyMatches.Length > 0 ? BuildLoopRepresentation(subtract, source, sourceSide) : null;+ var oracleBroad = familyMatches.Length > 0 ? BuildLoopRepresentation(source, sourceSide == SubtractOperandSide.Left ? subtract.Right : subtract.Left, "broad-opposite-field-only") : null;loops.Add(loop with { OracleTrimRepresentation = oracleBroad, OracleTrimStrongEvidence = false, OracleTrimRoutingDiagnostic = routing });}@@ -67,9 +82,9 @@ internal static class RetainedLoopTrimOracleIntegratorreturn next;}- private static TieredTrimCurveRepresentation BuildLoopRepresentation(CirSubtractNode root, SourceSurfaceDescriptor source, SubtractOperandSide sourceSide)+ private static TieredTrimCurveRepresentation BuildLoopRepresentation(SourceSurfaceDescriptor source, CirNode opposite, string routing){- var field = SurfaceRestrictedFieldFactory.ForSubtractSource(root, source, sourceSide);+ var field = SurfaceRestrictedFieldFactory.ForSourceAndOpposite(source, opposite, routing);var grid = RestrictedFieldGridSampler.Sample(field, new RestrictedFieldGridOptions(65, 65));var extraction = RestrictedFieldMarchingSquaresExtractor.Extract(grid, field.Parameterization);var stitched = SurfaceTrimContourStitcher.Stitch(extraction);diff --git a/Aetheris.Kernel.Firmament/Execution/SelectedOppositeFieldBuilder.cs b/Aetheris.Kernel.Firmament/Execution/SelectedOppositeFieldBuilder.csnew file mode 100644index 00000000..33a75624--- /dev/null+++ b/Aetheris.Kernel.Firmament/Execution/SelectedOppositeFieldBuilder.cs@@ -0,0 +1,77 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Math;++namespace Aetheris.Kernel.Firmament.Execution;++internal enum SelectedOppositeFieldBuildStatus+{+ Success,+ Deferred,+ Unsupported+}++internal sealed record SelectedOppositeFieldBuildResult(+ SelectedOppositeFieldBuildStatus Status,+ CirNode? Node,+ string Diagnostic);++internal static class SelectedOppositeFieldBuilder+{+ internal static SelectedOppositeFieldBuildResult TryBuild(SourceSurfaceDescriptor selectedOpposite)+ {+ if (selectedOpposite.Family == SurfacePatchFamily.Cylindrical)+ {+ if (selectedOpposite.CylindricalGeometryEvidence is not { } cylinder)+ {+ return new(SelectedOppositeFieldBuildStatus.Deferred, null, "selected-opposite-field: cylinder-geometry-missing");+ }++ if (cylinder.Radius <= 1e-12d || cylinder.Height <= 1e-12d || cylinder.AxisDirection.Length <= 1e-12d)+ {+ return new(SelectedOppositeFieldBuildStatus.Deferred, null, "selected-opposite-field: cylinder-geometry-invalid");+ }++ var axis = cylinder.AxisDirection / cylinder.AxisDirection.Length;+ var center = new Point3D((cylinder.BottomCenter.X + cylinder.TopCenter.X) * 0.5d, (cylinder.BottomCenter.Y + cylinder.TopCenter.Y) * 0.5d, (cylinder.BottomCenter.Z + cylinder.TopCenter.Z) * 0.5d);+ if (!TryCreateCylinderWorldTransform(center, axis, out var transform))+ {+ return new(SelectedOppositeFieldBuildStatus.Deferred, null, "selected-opposite-field: cylinder-orientation-unsupported");+ }++ var node = new CirTransformNode(new CirCylinderNode(cylinder.Radius, cylinder.Height), transform);+ return new(SelectedOppositeFieldBuildStatus.Success, node, "selected-opposite-field: cylinder");+ }++ if (selectedOpposite.Family == SurfacePatchFamily.Spherical)+ {+ return new(SelectedOppositeFieldBuildStatus.Deferred, null, "selected-opposite-field: sphere-geometry-missing");+ }++ if (selectedOpposite.Family == SurfacePatchFamily.Toroidal)+ {+ return new(SelectedOppositeFieldBuildStatus.Deferred, null, "selected-opposite-field: torus-geometry-missing");+ }++ return new(SelectedOppositeFieldBuildStatus.Unsupported, null, $"selected-opposite-field: unsupported-family:{selectedOpposite.Family}");+ }++ private static bool TryCreateCylinderWorldTransform(Point3D center, Vector3D axisDirection, out Transform3D transform)+ {+ transform = Transform3D.Identity;+ var localAxis = new Vector3D(0d, 0d, 1d);+ var dot = localAxis.Dot(axisDirection);+ if (dot > 1d - 1e-9d)+ {+ transform = Transform3D.CreateTranslation(center - Point3D.Origin);+ return true;+ }++ if (dot < -1d + 1e-9d)+ {+ transform = Transform3D.Compose(Transform3D.CreateRotationX(Math.PI), Transform3D.CreateTranslation(center - Point3D.Origin));+ return true;+ }++ return false;+ }+}diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceRestrictedField.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceRestrictedField.csindex 5c9da61d..5c0153c2 100644--- a/Aetheris.Kernel.Firmament/Execution/SurfaceRestrictedField.cs+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceRestrictedField.cs@@ -85,6 +85,13 @@ internal sealed record SurfaceRestrictedField(internal static class SurfaceRestrictedFieldFactory{internal static SurfaceRestrictedField ForSubtractSource(CirSubtractNode root, SourceSurfaceDescriptor source, SubtractOperandSide side)+ {+ var opposite = side == SubtractOperandSide.Left ? root.Right : root.Left;+ var routing = side == SubtractOperandSide.Left ? "opposite-operand-selected:right" : "opposite-operand-selected:left";+ return ForSourceAndOpposite(source, opposite, routing);+ }++ internal static SurfaceRestrictedField ForSourceAndOpposite(SourceSurfaceDescriptor source, CirNode opposite, string routingDiagnostic){var diagnostics = new List<string>();if (!TryBuildPlanarRectangle(source, out var parameterization, out var parameterizationDiagnostic))@@ -96,8 +103,7 @@ internal static class SurfaceRestrictedFieldFactorydiagnostics.Add("planar-rectangle-parameterization-constructed");- var opposite = side == SubtractOperandSide.Left ? root.Right : root.Left;- diagnostics.Add(side == SubtractOperandSide.Left ? "opposite-operand-selected:right" : "opposite-operand-selected:left");+ diagnostics.Add(routingDiagnostic);try{diff --git a/docs/cir-t9-selected-opposite-field-routing.md b/docs/cir-t9-selected-opposite-field-routing.mdnew file mode 100644index 00000000..dcbee6df--- /dev/null+++ b/docs/cir-t9-selected-opposite-field-routing.md@@ -0,0 +1,32 @@+# CIR-T9 selected-opposite field routing++## What T8.1 left incomplete+T8.1 deterministically routed retained loops to a selected opposite descriptor, but trim-oracle restricted-field evaluation could still use a broad opposite operand subtree.++## T9 change+T9 adds `SelectedOppositeFieldBuilder` so retained-loop trim-oracle integration attempts to reconstruct a CIR field from the selected opposite descriptor first.++- when selected opposite field builds: `oracle-trim: selected-opposite-field-used` and strong evidence is allowed+- when selected opposite field cannot build: `oracle-trim: selected-opposite-field-deferred:<reason>` and strong evidence is blocked+- broad opposite routing remains diagnostic-only (`oracle-trim: broad-opposite-field-only`)++## Primitive support status+- Cylinder: supported when `CylindricalSurfaceGeometryEvidence` is canonical and axis alignment is representable under current transform guardrails.+- Sphere: deferred (`selected-opposite-field: sphere-geometry-missing`) because descriptor currently lacks center/radius evidence.+- Torus: deferred (`selected-opposite-field: torus-geometry-missing`) because descriptor currently lacks major/minor/frame evidence.++## Semantics+Strong/materialization-grade oracle evidence now requires both:+1. deterministic selected opposite descriptor+2. restricted field built from that selected opposite descriptor++Broad-only fields never claim strong evidence.++## Non-goals preserved+- no BRep topology emission changes+- no STEP export behavior changes+- no BSpline fitting or torus quartic/exact recognition claims+- no Boolean behavior expansion++## Recommended T10+Add spherical/toroidal descriptor geometry evidence (center/radius and major/minor/frame respectively) so selected-opposite field reconstruction can promote those families from deferred to strong where valid.