Skip to content

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.cs
index 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.cs
new file mode 100644
index 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.md
new file mode 100644
index 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.