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