Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Implement CIR-T1 planar restricted field evaluator

Yuechen Li2cc1d50bed15
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceRestrictedFieldTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceRestrictedFieldTests.cs
new file mode 100644
index 00000000..d42665de
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceRestrictedFieldTests.cs
@@ -0,0 +1,94 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class SurfaceRestrictedFieldTests
+{
+ [Fact]
+ public void RestrictedField_BoxFaceVsCylinder_EvaluatesDeterministically()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 20));
+ var source = Assert.Single(SourceSurfaceExtractor.Extract(root.Left).Descriptors.Where(d => d.ParameterPayloadReference == "top"));
+ var field = SurfaceRestrictedFieldFactory.ForSubtractSource(root, source, SubtractOperandSide.Left);
+
+ Assert.Equal(SurfaceRestrictedFieldStatus.Ready, field.Status);
+ var s1 = field.Evaluate(0.5d, 0.5d);
+ var s2 = field.Evaluate(0.5d, 0.5d);
+ Assert.Equal(s1.Value, s2.Value, 12);
+ Assert.Equal(RestrictedFieldSignClassification.InsideOpposite, s1.SignClassification);
+ Assert.Contains("evaluation-available", field.Diagnostics);
+ Assert.Contains("contour-extraction-not-implemented", field.Diagnostics);
+
+ var far = field.Evaluate(0.95d, 0.95d);
+ Assert.Equal(RestrictedFieldSignClassification.OutsideOpposite, far.SignClassification);
+ }
+
+ [Fact]
+ public void RestrictedField_BoxFaceVsSphere_EvaluatesDeterministically()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(6));
+ var source = Assert.Single(SourceSurfaceExtractor.Extract(root.Left).Descriptors.Where(d => d.ParameterPayloadReference == "top"));
+ var field = SurfaceRestrictedFieldFactory.ForSubtractSource(root, source, SubtractOperandSide.Left);
+
+ var a = field.Evaluate(0.5d, 0.5d);
+ var b = field.Evaluate(0.5d, 0.5d);
+ Assert.Equal(a.Value, b.Value, 12);
+ Assert.Equal(RestrictedFieldSignClassification.InsideOpposite, a.SignClassification);
+ }
+
+ [Fact]
+ public void RestrictedField_BoxFaceVsTorus_EvaluatesDespiteMaterializationDeferred()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(12, 12, 12), new CirTorusNode(4, 1));
+ var source = Assert.Single(SourceSurfaceExtractor.Extract(root.Left).Descriptors.Where(d => d.ParameterPayloadReference == "top"));
+ var field = SurfaceRestrictedFieldFactory.ForSubtractSource(root, source, SubtractOperandSide.Left);
+
+ Assert.Equal(SurfaceRestrictedFieldStatus.Ready, field.Status);
+ var a = field.Evaluate(0.5d, 0.5d);
+ var b = field.Evaluate(0.5d, 0.5d);
+ Assert.Equal(a.Value, b.Value, 12);
+ Assert.Contains("export-materialization-unchanged", field.Diagnostics);
+ }
+
+ [Fact]
+ public void RestrictedField_RejectsNonRectanglePlanarSource()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 8));
+ var circlePlanar = Assert.Single(SourceSurfaceExtractor.Extract(root.Right).Descriptors.Where(d => d.ParameterPayloadReference == "cap-top"));
+
+ var field = SurfaceRestrictedFieldFactory.ForSubtractSource(root, circlePlanar, SubtractOperandSide.Right);
+ Assert.Equal(SurfaceRestrictedFieldStatus.Unsupported, field.Status);
+ Assert.Contains(field.Diagnostics, d => d.Contains("bounded-kind-Circle", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void RestrictedField_RejectsMissingBoundedGeometry()
+ {
+ var source = new SourceSurfaceDescriptor(SurfacePatchFamily.Planar, "synthetic", null, null, Transform3D.Identity, "test", nameof(CirBoxNode), null, FacePatchOrientationRole.Forward);
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(3));
+
+ var field = SurfaceRestrictedFieldFactory.ForSubtractSource(root, source, SubtractOperandSide.Left);
+ Assert.Equal(SurfaceRestrictedFieldStatus.Unsupported, field.Status);
+ Assert.Contains("bounded-rectangle-missing", field.Diagnostics);
+ }
+
+ [Fact]
+ public void RestrictedField_SubtractSideSelection_SelectsOppositeOperand()
+ {
+ var left = new CirSphereNode(2);
+ var right = new CirCylinderNode(1, 8);
+ var root = new CirSubtractNode(left, right);
+ var source = new SourceSurfaceDescriptor(SurfacePatchFamily.Planar, "synthetic", BoundedPlanarPatchGeometry.CreateRectangle(new Point3D(-1, -1, 0), new Point3D(1, -1, 0), new Point3D(1, 1, 0), new Point3D(-1, 1, 0), new Vector3D(0, 0, 1)), null, Transform3D.Identity, "test", nameof(CirBoxNode), null, FacePatchOrientationRole.Forward);
+
+ var leftSource = SurfaceRestrictedFieldFactory.ForSubtractSource(root, source, SubtractOperandSide.Left);
+ var rightSource = SurfaceRestrictedFieldFactory.ForSubtractSource(root, source, SubtractOperandSide.Right);
+
+ var pLeft = leftSource.Evaluate(1d, 1d).Value;
+ var pRight = rightSource.Evaluate(0.5d, 0.5d).Value;
+ Assert.NotEqual(pLeft, pRight);
+ Assert.Contains("opposite-operand-selected:right", leftSource.Diagnostics);
+ Assert.Contains("opposite-operand-selected:left", rightSource.Diagnostics);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/SurfaceRestrictedField.cs b/Aetheris.Kernel.Firmament/Execution/SurfaceRestrictedField.cs
new file mode 100644
index 00000000..5c9da61d
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/SurfaceRestrictedField.cs
@@ -0,0 +1,159 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal enum SurfaceRestrictedFieldStatus
+{
+ Ready,
+ Deferred,
+ Unsupported,
+ Invalid
+}
+
+internal enum SubtractOperandSide
+{
+ Left,
+ Right
+}
+
+internal enum RestrictedFieldSignClassification
+{
+ InsideOpposite,
+ OutsideOpposite,
+ Boundary
+}
+
+internal readonly record struct RestrictedDomain2D(double UMin, double UMax, double VMin, double VMax)
+{
+ internal bool Contains(double u, double v) => u >= UMin && u <= UMax && v >= VMin && v <= VMax;
+}
+
+internal readonly record struct PlanarRectangleParameterization(
+ Point3D Corner00,
+ Vector3D UVector,
+ Vector3D VVector,
+ Vector3D Normal,
+ RestrictedDomain2D Domain)
+{
+ internal Point3D Evaluate(double u, double v) => Corner00 + (UVector * u) + (VVector * v);
+}
+
+internal sealed record RestrictedFieldSample(
+ double U,
+ double V,
+ Point3D Point,
+ double Value,
+ RestrictedFieldSignClassification SignClassification,
+ IReadOnlyList<string> Diagnostics);
+
+internal sealed record SurfaceRestrictedField(
+ SourceSurfaceDescriptor SourceSurface,
+ PlanarRectangleParameterization? Parameterization,
+ CirTape? OppositeTape,
+ SurfaceRestrictedFieldStatus Status,
+ IReadOnlyList<string> Diagnostics)
+{
+ internal RestrictedFieldSample Evaluate(double u, double v, ToleranceContext? tolerance = null)
+ {
+ var diag = new List<string>();
+ if (Status != SurfaceRestrictedFieldStatus.Ready || Parameterization is null || OppositeTape is null)
+ {
+ diag.Add("restricted-field-not-ready");
+ return new RestrictedFieldSample(u, v, Point3D.Origin, double.NaN, RestrictedFieldSignClassification.Boundary, diag);
+ }
+
+ var domain = Parameterization.Value.Domain;
+ if (!domain.Contains(u, v))
+ {
+ diag.Add("sample-outside-domain");
+ }
+
+ var point = Parameterization.Value.Evaluate(u, v);
+ var value = OppositeTape.Evaluate(point);
+ var tol = tolerance ?? ToleranceContext.Default;
+ var sign = double.Abs(value) <= tol.Linear
+ ? RestrictedFieldSignClassification.Boundary
+ : value < 0d ? RestrictedFieldSignClassification.InsideOpposite : RestrictedFieldSignClassification.OutsideOpposite;
+ diag.Add("evaluation-available");
+ diag.Add("contour-extraction-not-implemented");
+ return new RestrictedFieldSample(u, v, point, value, sign, diag);
+ }
+}
+
+internal static class SurfaceRestrictedFieldFactory
+{
+ internal static SurfaceRestrictedField ForSubtractSource(CirSubtractNode root, SourceSurfaceDescriptor source, SubtractOperandSide side)
+ {
+ var diagnostics = new List<string>();
+ if (!TryBuildPlanarRectangle(source, out var parameterization, out var parameterizationDiagnostic))
+ {
+ diagnostics.Add(parameterizationDiagnostic);
+ diagnostics.Add("export-materialization-unchanged");
+ return new SurfaceRestrictedField(source, null, null, SurfaceRestrictedFieldStatus.Unsupported, diagnostics);
+ }
+
+ 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");
+
+ try
+ {
+ var tape = CirTapeLowerer.Lower(opposite);
+ diagnostics.Add("opposite-tape-lowered");
+ diagnostics.Add("evaluation-available");
+ diagnostics.Add("contour-extraction-not-implemented");
+ diagnostics.Add("export-materialization-unchanged");
+ return new SurfaceRestrictedField(source, parameterization, tape, SurfaceRestrictedFieldStatus.Ready, diagnostics);
+ }
+ catch (Exception ex)
+ {
+ diagnostics.Add($"opposite-tape-lowering-failed:{ex.GetType().Name}");
+ diagnostics.Add("export-materialization-unchanged");
+ return new SurfaceRestrictedField(source, parameterization, null, SurfaceRestrictedFieldStatus.Deferred, diagnostics);
+ }
+ }
+
+ private static bool TryBuildPlanarRectangle(SourceSurfaceDescriptor source, out PlanarRectangleParameterization parameterization, out string diagnostic)
+ {
+ parameterization = default;
+ if (source.Family != SurfacePatchFamily.Planar)
+ {
+ diagnostic = "source-surface-unsupported:non-planar";
+ return false;
+ }
+
+ if (source.BoundedPlanarGeometry is not { } bounded)
+ {
+ diagnostic = "bounded-rectangle-missing";
+ return false;
+ }
+
+ if (bounded.Kind != BoundedPlanarPatchGeometryKind.Rectangle)
+ {
+ diagnostic = $"source-surface-unsupported:bounded-kind-{bounded.Kind}";
+ return false;
+ }
+
+ var u = bounded.Corner10 - bounded.Corner00;
+ var v = bounded.Corner01 - bounded.Corner00;
+ if (u.Length <= 1e-12d || v.Length <= 1e-12d)
+ {
+ diagnostic = "invalid-planar-rectangle-degenerate-vectors";
+ return false;
+ }
+
+ var normal = u.Cross(v);
+ if (normal.Length <= 1e-12d)
+ {
+ diagnostic = "invalid-planar-rectangle-degenerate-normal";
+ return false;
+ }
+
+ parameterization = new PlanarRectangleParameterization(bounded.Corner00, u, v, normal / normal.Length, new RestrictedDomain2D(0d, 1d, 0d, 1d));
+ diagnostic = "ok";
+ return true;
+ }
+}
diff --git a/docs/cir-t1-planar-restricted-field.md b/docs/cir-t1-planar-restricted-field.md
new file mode 100644
index 00000000..b966fae5
--- /dev/null
+++ b/docs/cir-t1-planar-restricted-field.md
@@ -0,0 +1,68 @@
+# CIR-T1: planar rectangular surface-restricted field evaluator
+
+## Purpose
+
+CIR-T1 introduces the first executable trim-oracle substrate: evaluate an opposite CIR field over a **source planar rectangular parameter domain**.
+
+Given source surface `S(u,v)` and opposite field `F(x,y,z)`, T1 provides deterministic point samples of `g(u,v)=F(S(u,v))`.
+
+## Parameterization contract
+
+T1 supports only source descriptors where:
+
+- `Family = Planar`
+- `BoundedPlanarGeometry.Kind = Rectangle`
+- corners are available as `Corner00/Corner10/Corner01/Corner11`
+
+The evaluator constructs:
+
+- `S(u,v) = Corner00 + u*(Corner10-Corner00) + v*(Corner01-Corner00)`
+- domain `u,v ∈ [0,1]`
+
+It rejects non-planar, missing bounded geometry, non-rectangle bounded geometry, and degenerate U/V vectors.
+
+## Subtract opposite operand selection
+
+For `CirSubtractNode(left,right)`, T1 uses explicit source side:
+
+- source side `Left` => opposite node `right`
+- source side `Right` => opposite node `left`
+
+Opposite node is lowered via `CirTapeLowerer.Lower` and sampled via `CirTape.Evaluate`.
+
+## Evaluation behavior
+
+`Evaluate(u,v)`:
+
+1. checks domain membership and records a diagnostic if outside;
+2. maps `(u,v)` to world point through planar rectangle parameterization;
+3. evaluates opposite tape at that point;
+4. classifies sign with tolerance:
+ - negative = inside opposite
+ - positive = outside opposite
+ - near-zero = boundary
+
+## Exactness/export/materialization policy
+
+T1 is evaluation-only. It does not alter:
+
+- topology emission,
+- STEP export behavior,
+- Boolean behavior,
+- surface-family materialization readiness decisions.
+
+SEM-A0 guardrails remain preserved (no generated topology naming changes).
+
+## Non-goals
+
+Not included in T1:
+
+- contour extraction,
+- marching squares or cell interval refinement,
+- analytic snap,
+- trim curve/BRep integration,
+- CLI exposure changes.
+
+## Recommended T2
+
+Add restricted-domain grid/cell sampling over this evaluator, then a deterministic marching-squares contour scaffold that consumes sampled signs/values without changing exporter/materializer behavior.