Skip to content

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.cs
index 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.cs
index 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.cs
index 3944de0f..f093c0e7 100644
--- a/Aetheris.Kernel.Firmament/Execution/RetainedLoopTrimOracleIntegrator.cs
+++ b/Aetheris.Kernel.Firmament/Execution/RetainedLoopTrimOracleIntegrator.cs
@@ -30,8 +30,23 @@ internal static class RetainedLoopTrimOracleIntegrator
var 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 RetainedLoopTrimOracleIntegrator
var 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 RetainedLoopTrimOracleIntegrator
return 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.cs
new file mode 100644
index 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.cs
index 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 SurfaceRestrictedFieldFactory
diagnostics.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.md
new file mode 100644
index 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.