Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add CIR-T2 restricted-field grid sampling and cell classification
Yuechen Li16b65b214aa2
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceRestrictedFieldTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceRestrictedFieldTests.csindex d42665de..1340e530 100644--- a/Aetheris.Kernel.Firmament.Tests/SurfaceRestrictedFieldTests.cs+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceRestrictedFieldTests.cs@@ -6,6 +6,89 @@ namespace Aetheris.Kernel.Firmament.Tests;public sealed class SurfaceRestrictedFieldTests{+ [Fact]+ public void RestrictedFieldGrid_BoxFaceVsCylinder_HasMixedCells()+ {+ 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);++ var grid = RestrictedFieldGridSampler.Sample(field, new RestrictedFieldGridOptions(17, 17));+ Assert.Equal(17 * 17, grid.Counts.SampleCount);+ Assert.Equal(16 * 16, grid.Counts.CellCount);+ Assert.True(grid.Counts.MixedCellCount > 0 || grid.Counts.BoundaryCellCount > 0);+ Assert.True(grid.Counts.InsideCellCount > 0);+ Assert.True(grid.Counts.OutsideCellCount > 0);+ Assert.Contains("contour-extraction-not-implemented", grid.Diagnostics);+ }++ [Fact]+ public void RestrictedFieldGrid_BoxFaceVsSphere_HasMixedCells()+ {+ 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 grid = RestrictedFieldGridSampler.Sample(field, new RestrictedFieldGridOptions(17, 17));+ Assert.True(grid.Counts.MixedCellCount > 0 || grid.Counts.BoundaryCellCount > 0);+ }++ [Fact]+ public void RestrictedFieldGrid_BoxFaceVsTorus_SamplesAndReportsMixedOrDeferred()+ {+ 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);++ var grid = RestrictedFieldGridSampler.Sample(field, new RestrictedFieldGridOptions(17, 17));+ Assert.Equal(17 * 17, grid.Counts.SampleCount);+ Assert.True(grid.Counts.MixedCellCount >= 0);+ Assert.Contains("export-materialization-unchanged", grid.Diagnostics);+ }++ [Fact]+ public void RestrictedFieldGrid_DeterministicOrdering()+ {+ 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 = RestrictedFieldGridSampler.Sample(field, new RestrictedFieldGridOptions(17, 17));+ var b = RestrictedFieldGridSampler.Sample(field, new RestrictedFieldGridOptions(17, 17));+ Assert.Equal(a.Counts, b.Counts);+ Assert.Equal(a.Samples.Select(s => (s.I, s.J, s.Sample.Value, s.Sample.SignClassification)), b.Samples.Select(s => (s.I, s.J, s.Sample.Value, s.Sample.SignClassification)));+ Assert.Equal(a.Cells.Select(c => (c.CellI, c.CellJ, c.Classification)), b.Cells.Select(c => (c.CellI, c.CellJ, c.Classification)));+ }++ [Theory]+ [InlineData(1, 17)]+ [InlineData(17, 1)]+ public void RestrictedFieldGrid_InvalidResolution_Rejected(int u, int v)+ {+ 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);++ Assert.Throws<ArgumentOutOfRangeException>(() => RestrictedFieldGridSampler.Sample(field, new RestrictedFieldGridOptions(u, v)));+ }++ [Fact]+ public void RestrictedFieldGrid_CellClassificationPolicy()+ {+ static RestrictedFieldGridSample Sample(int i, int j, RestrictedFieldSignClassification sign, double value = 1d)+ => new(i, j, i, j, new RestrictedFieldSample(i, j, Point3D.Origin, value, sign, ["evaluation-available"]));++ var inside = RestrictedFieldGridSampler.ClassifyCell([Sample(0,0,RestrictedFieldSignClassification.InsideOpposite,-1), Sample(1,0,RestrictedFieldSignClassification.InsideOpposite,-1), Sample(0,1,RestrictedFieldSignClassification.InsideOpposite,-1), Sample(1,1,RestrictedFieldSignClassification.InsideOpposite,-1)]);+ var outside = RestrictedFieldGridSampler.ClassifyCell([Sample(0,0,RestrictedFieldSignClassification.OutsideOpposite,1), Sample(1,0,RestrictedFieldSignClassification.OutsideOpposite,1), Sample(0,1,RestrictedFieldSignClassification.OutsideOpposite,1), Sample(1,1,RestrictedFieldSignClassification.OutsideOpposite,1)]);+ var mixed = RestrictedFieldGridSampler.ClassifyCell([Sample(0,0,RestrictedFieldSignClassification.InsideOpposite,-1), Sample(1,0,RestrictedFieldSignClassification.OutsideOpposite,1), Sample(0,1,RestrictedFieldSignClassification.InsideOpposite,-1), Sample(1,1,RestrictedFieldSignClassification.OutsideOpposite,1)]);+ var boundary = RestrictedFieldGridSampler.ClassifyCell([Sample(0,0,RestrictedFieldSignClassification.Boundary,0), Sample(1,0,RestrictedFieldSignClassification.Boundary,0), Sample(0,1,RestrictedFieldSignClassification.Boundary,0), Sample(1,1,RestrictedFieldSignClassification.Boundary,0)]);++ Assert.Equal(RestrictedFieldCellClassification.Inside, inside);+ Assert.Equal(RestrictedFieldCellClassification.Outside, outside);+ Assert.Equal(RestrictedFieldCellClassification.Mixed, mixed);+ Assert.Equal(RestrictedFieldCellClassification.Boundary, boundary);+ }+[Fact]public void RestrictedField_BoxFaceVsCylinder_EvaluatesDeterministically(){diff --git a/Aetheris.Kernel.Firmament/Execution/RestrictedFieldGridSampler.cs b/Aetheris.Kernel.Firmament/Execution/RestrictedFieldGridSampler.csnew file mode 100644index 00000000..4f7aca79--- /dev/null+++ b/Aetheris.Kernel.Firmament/Execution/RestrictedFieldGridSampler.cs@@ -0,0 +1,173 @@+using Aetheris.Kernel.Core.Numerics;++namespace Aetheris.Kernel.Firmament.Execution;++internal sealed record RestrictedFieldGridOptions(int ResolutionU, int ResolutionV, bool IncludeWorldPoints = true);++internal enum RestrictedFieldCellClassification+{+ Inside,+ Outside,+ Boundary,+ Mixed,+ Unknown,+}++internal sealed record RestrictedFieldGridSample(+ int I,+ int J,+ double U,+ double V,+ RestrictedFieldSample Sample);++internal sealed record RestrictedFieldCell(+ int CellI,+ int CellJ,+ double UMin,+ double UMax,+ double VMin,+ double VMax,+ IReadOnlyList<int> CornerSampleIndices,+ RestrictedFieldCellClassification Classification,+ IReadOnlyList<string> Diagnostics);++internal sealed record RestrictedFieldGridCounts(+ int SampleCount,+ int CellCount,+ int InsideCellCount,+ int OutsideCellCount,+ int BoundaryCellCount,+ int MixedCellCount,+ int UnknownCellCount);++internal sealed record RestrictedFieldSampleGrid(+ SourceSurfaceDescriptor SourceSurface,+ int ResolutionU,+ int ResolutionV,+ IReadOnlyList<RestrictedFieldGridSample> Samples,+ IReadOnlyList<RestrictedFieldCell> Cells,+ RestrictedFieldGridCounts Counts,+ IReadOnlyList<string> Diagnostics);++internal static class RestrictedFieldGridSampler+{+ internal static RestrictedFieldSampleGrid Sample(SurfaceRestrictedField field, RestrictedFieldGridOptions options, ToleranceContext? tolerance = null)+ {+ ArgumentNullException.ThrowIfNull(field);+ ArgumentNullException.ThrowIfNull(options);++ var diagnostics = new List<string>+ {+ "grid-sampler-started",+ $"grid-resolution:{options.ResolutionU}x{options.ResolutionV}",+ "grid-cell-policy:boundary-no-disagreement=>Boundary,boundary-with-disagreement=>Mixed",+ "contour-extraction-not-implemented",+ "export-materialization-unchanged",+ };++ if (options.ResolutionU < 2 || options.ResolutionV < 2)+ {+ diagnostics.Add("invalid-grid-resolution:requires-min-2-per-axis");+ throw new ArgumentOutOfRangeException(nameof(options), "Grid resolution must be >= 2 for both axes.");+ }++ var sampleCount = options.ResolutionU * options.ResolutionV;+ var samples = new List<RestrictedFieldGridSample>(sampleCount);+ for (var j = 0; j < options.ResolutionV; j++)+ {+ for (var i = 0; i < options.ResolutionU; i++)+ {+ var u = i / (double)(options.ResolutionU - 1);+ var v = j / (double)(options.ResolutionV - 1);+ var sampled = field.Evaluate(u, v, tolerance);+ var retainedSample = options.IncludeWorldPoints+ ? sampled+ : sampled with { Point = default };+ samples.Add(new RestrictedFieldGridSample(i, j, u, v, retainedSample));+ }+ }++ var cells = new List<RestrictedFieldCell>((options.ResolutionU - 1) * (options.ResolutionV - 1));+ var inside = 0;+ var outside = 0;+ var boundary = 0;+ var mixed = 0;+ var unknown = 0;+ for (var j = 0; j < options.ResolutionV - 1; j++)+ {+ for (var i = 0; i < options.ResolutionU - 1; i++)+ {+ var bottomLeft = GetSampleIndex(i, j, options.ResolutionU);+ var bottomRight = GetSampleIndex(i + 1, j, options.ResolutionU);+ var topLeft = GetSampleIndex(i, j + 1, options.ResolutionU);+ var topRight = GetSampleIndex(i + 1, j + 1, options.ResolutionU);+ var cornerIndices = new[] { bottomLeft, bottomRight, topLeft, topRight };+ var corners = cornerIndices.Select(index => samples[index]).ToArray();+ var classification = ClassifyCell(corners);+ switch (classification)+ {+ case RestrictedFieldCellClassification.Inside: inside++; break;+ case RestrictedFieldCellClassification.Outside: outside++; break;+ case RestrictedFieldCellClassification.Boundary: boundary++; break;+ case RestrictedFieldCellClassification.Mixed: mixed++; break;+ case RestrictedFieldCellClassification.Unknown: unknown++; break;+ }++ cells.Add(new RestrictedFieldCell(+ i,+ j,+ corners.Min(s => s.U),+ corners.Max(s => s.U),+ corners.Min(s => s.V),+ corners.Max(s => s.V),+ cornerIndices,+ classification,+ []));+ }+ }++ var counts = new RestrictedFieldGridCounts(samples.Count, cells.Count, inside, outside, boundary, mixed, unknown);+ return new RestrictedFieldSampleGrid(field.SourceSurface, options.ResolutionU, options.ResolutionV, samples, cells, counts, diagnostics);+ }++ internal static RestrictedFieldCellClassification ClassifyCell(IReadOnlyList<RestrictedFieldGridSample> corners)+ {+ if (corners.Count != 4)+ {+ throw new ArgumentException("Cell classification requires exactly four corners.", nameof(corners));+ }++ if (corners.Any(c => double.IsNaN(c.Sample.Value) || c.Sample.Diagnostics.Contains("restricted-field-not-ready")))+ {+ return RestrictedFieldCellClassification.Unknown;+ }++ var hasInside = corners.Any(c => c.Sample.SignClassification == RestrictedFieldSignClassification.InsideOpposite);+ var hasOutside = corners.Any(c => c.Sample.SignClassification == RestrictedFieldSignClassification.OutsideOpposite);+ var hasBoundary = corners.Any(c => c.Sample.SignClassification == RestrictedFieldSignClassification.Boundary);++ if (hasInside && hasOutside)+ {+ return RestrictedFieldCellClassification.Mixed;+ }++ if (hasBoundary)+ {+ return (hasInside || hasOutside) ? RestrictedFieldCellClassification.Boundary : RestrictedFieldCellClassification.Boundary;+ }++ if (hasInside)+ {+ return RestrictedFieldCellClassification.Inside;+ }++ if (hasOutside)+ {+ return RestrictedFieldCellClassification.Outside;+ }++ return RestrictedFieldCellClassification.Unknown;+ }++ private static int GetSampleIndex(int i, int j, int resolutionU) => (j * resolutionU) + i;+}diff --git a/docs/cir-t2-restricted-field-grid-sampling.md b/docs/cir-t2-restricted-field-grid-sampling.mdnew file mode 100644index 00000000..1bee3421--- /dev/null+++ b/docs/cir-t2-restricted-field-grid-sampling.md@@ -0,0 +1,75 @@+# CIR-T2: restricted-field grid sampling + cell classification++## Purpose++CIR-T2 adds deterministic grid sampling over a `SurfaceRestrictedField` and cell classification over the planar `[0,1] x [0,1]` parameter domain.++This milestone answers where sign changes happen and where cells are inside/outside/boundary/mixed/unknown, while deliberately not extracting contours.++## Scope++Supported now:++- source restricted fields with planar rectangular parameterization from T1,+- regular deterministic grid sampling,+- corner-based cell classification,+- count + diagnostics reporting.++Deferred:++- marching squares contour extraction (CIR-T3),+- adaptive 2D subdivision,+- non-rectangular/non-planar source domains,+- topology, export, materialization behavior changes.++## Sampling policy++For options `(ResolutionU, ResolutionV)`:++- require both resolutions `>= 2`,+- sample in row-major order (`j` outer, `i` inner),+- `u = i / (ResolutionU - 1)`,+- `v = j / (ResolutionV - 1)`,+- evaluate each corner through `SurfaceRestrictedField.Evaluate(u,v)`.++## Cell classification policy++Each cell uses 4 corners: `(i,j)`, `(i+1,j)`, `(i,j+1)`, `(i+1,j+1)`.++- any unknown/unavailable corner => `Unknown`,+- both inside + outside present => `Mixed`,+- any boundary corner without inside/outside disagreement => `Boundary`,+- all inside => `Inside`,+- all outside => `Outside`.++This is deterministic and designed for CIR-T3 contour extraction input.++## Diagnostics++Grid result diagnostics include:++- sampler start marker,+- resolution marker,+- explicit classification policy marker,+- contour extraction not implemented,+- export/materialization unchanged.++## Geometry evidence expectation++For box-face source against opposite cylinder/sphere/torus:++- sampling is deterministic,+- counts are deterministic for a fixed resolution,+- mixed/boundary cells indicate likely trim transitions.++## JudgmentEngine decision++Not used in CIR-T2. This milestone is deterministic transformation/classification with no competing strategy selection.++## SEM-A0 status++CIR-T2 introduces no generated topology naming/provenance changes. SEM-A0 guardrails remain preserved.++## Next (CIR-T3)++Consume T2 sample/cell data with deterministic marching squares contour extraction and contour diagnostics, still without changing export/materialization behavior.