Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Implement CIR-T3 marching-squares contour extraction

Yuechen Liaff00098ddc3
diff --git a/Aetheris.Kernel.Firmament.Tests/SurfaceRestrictedFieldMarchingSquaresTests.cs b/Aetheris.Kernel.Firmament.Tests/SurfaceRestrictedFieldMarchingSquaresTests.cs
new file mode 100644
index 00000000..12732355
--- /dev/null
+++ b/Aetheris.Kernel.Firmament.Tests/SurfaceRestrictedFieldMarchingSquaresTests.cs
@@ -0,0 +1,115 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Firmament.Execution;
+
+namespace Aetheris.Kernel.Firmament.Tests;
+
+public sealed class SurfaceRestrictedFieldMarchingSquaresTests
+{
+ [Fact]
+ public void MarchingSquares_BoxFaceVsCylinder_ProducesSegments()
+ {
+ var (field, grid) = CreateGrid(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirCylinderNode(2, 20)));
+ var result = RestrictedFieldMarchingSquaresExtractor.Extract(grid, field.Parameterization);
+
+ Assert.True(result.Success);
+ Assert.True(result.SegmentCount > 0);
+ Assert.All(result.Segments, seg =>
+ {
+ Assert.InRange(seg.A.U, 0d, 1d);
+ Assert.InRange(seg.A.V, 0d, 1d);
+ Assert.InRange(seg.B.U, 0d, 1d);
+ Assert.InRange(seg.B.V, 0d, 1d);
+ });
+ Assert.False(result.ContourStitchingImplemented);
+ Assert.False(result.AnalyticSnapImplemented);
+ Assert.False(result.ExactExportAvailable);
+ }
+
+ [Fact]
+ public void MarchingSquares_BoxFaceVsSphere_ProducesSegments()
+ {
+ var (field, grid) = CreateGrid(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(6)));
+ var result = RestrictedFieldMarchingSquaresExtractor.Extract(grid, field.Parameterization);
+
+ Assert.True(result.Success);
+ Assert.True(result.SegmentCount > 0);
+ }
+
+ [Fact]
+ public void MarchingSquares_BoxFaceVsTorus_ProducesSegmentsOrPreciseNoContour()
+ {
+ var (field, grid) = CreateGrid(new CirSubtractNode(new CirBoxNode(12, 12, 12), new CirTorusNode(4, 1)));
+ var result = RestrictedFieldMarchingSquaresExtractor.Extract(grid, field.Parameterization);
+
+ if (result.SegmentCount > 0)
+ {
+ Assert.True(result.Success);
+ }
+ else
+ {
+ Assert.Contains("no-contour-segments-detected", result.Diagnostics);
+ }
+ }
+
+ [Fact]
+ public void MarchingSquares_DeterministicOrdering()
+ {
+ var (field, grid) = CreateGrid(new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(6)));
+ var a = RestrictedFieldMarchingSquaresExtractor.Extract(grid, field.Parameterization);
+ var b = RestrictedFieldMarchingSquaresExtractor.Extract(grid, field.Parameterization);
+
+ Assert.Equal(a.SegmentCount, b.SegmentCount);
+ Assert.Equal(
+ a.Segments.Select(s => (s.CellI, s.CellJ, s.A.U, s.A.V, s.B.U, s.B.V)),
+ b.Segments.Select(s => (s.CellI, s.CellJ, s.A.U, s.A.V, s.B.U, s.B.V)));
+ }
+
+ [Fact]
+ public void MarchingSquares_SkipsInsideOutsideOnlyCells()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10, 10, 10), new CirSphereNode(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));
+
+ var result = RestrictedFieldMarchingSquaresExtractor.Extract(grid, field.Parameterization);
+ Assert.Equal(0, result.SegmentCount);
+ Assert.Contains("no-contour-segments-detected", result.Diagnostics);
+ }
+
+ [Fact]
+ public void MarchingSquares_AmbiguousCasesAreDiagnosed()
+ {
+ static RestrictedFieldGridSample Sample(int i, int j, double value)
+ => new(i, j, i, j, new RestrictedFieldSample(i, j, default, value, value < 0 ? RestrictedFieldSignClassification.InsideOpposite : RestrictedFieldSignClassification.OutsideOpposite, ["evaluation-available"]));
+
+ var samples = new[]
+ {
+ Sample(0,0,-1), Sample(1,0,1),
+ Sample(0,1,1), Sample(1,1,-1),
+ };
+
+ var cell = new RestrictedFieldCell(0, 0, 0, 1, 0, 1, [0, 1, 2, 3], RestrictedFieldCellClassification.Mixed, []);
+ var grid = new RestrictedFieldSampleGrid(
+ new SourceSurfaceDescriptor(SurfacePatchFamily.Planar, "synthetic", null, null, Aetheris.Kernel.Core.Math.Transform3D.Identity, "test", "test", null, FacePatchOrientationRole.Forward),
+ 2,
+ 2,
+ samples,
+ [cell],
+ new RestrictedFieldGridCounts(4, 1, 0, 0, 0, 1, 0),
+ ["grid-sampler-started"]);
+
+ var result = RestrictedFieldMarchingSquaresExtractor.Extract(grid);
+ Assert.True(result.SegmentCount > 0);
+ Assert.Contains(result.Diagnostics, d => d.StartsWith("contour-ambiguous-cell-count:", StringComparison.Ordinal));
+ Assert.Contains(result.Segments.SelectMany(s => s.Diagnostics), d => d.StartsWith("ambiguous-cell", StringComparison.Ordinal));
+ }
+
+ private static (SurfaceRestrictedField field, RestrictedFieldSampleGrid grid) CreateGrid(CirSubtractNode root)
+ {
+ 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(33, 33));
+ return (field, grid);
+ }
+}
diff --git a/Aetheris.Kernel.Firmament/Execution/RestrictedFieldMarchingSquaresExtractor.cs b/Aetheris.Kernel.Firmament/Execution/RestrictedFieldMarchingSquaresExtractor.cs
new file mode 100644
index 00000000..9b9a221a
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Execution/RestrictedFieldMarchingSquaresExtractor.cs
@@ -0,0 +1,192 @@
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+
+namespace Aetheris.Kernel.Firmament.Execution;
+
+internal enum RestrictedFieldContourExtractionMethod
+{
+ MarchingSquares,
+}
+
+internal sealed record SurfaceTrimContourPoint2D(double U, double V, double? ValueEstimate = null);
+
+internal sealed record SurfaceTrimContourPoint3D(Point3D Point, double SourceU, double SourceV);
+
+internal sealed record SurfaceTrimContourSegment2D(
+ int CellI,
+ int CellJ,
+ SurfaceTrimContourPoint2D A,
+ SurfaceTrimContourPoint2D B,
+ RestrictedFieldCellClassification Classification,
+ IReadOnlyList<string> Diagnostics,
+ SurfaceTrimContourPoint3D? A3D = null,
+ SurfaceTrimContourPoint3D? B3D = null);
+
+internal sealed record SurfaceTrimContourExtractionResult(
+ bool Success,
+ RestrictedFieldContourExtractionMethod Method,
+ int SegmentCount,
+ IReadOnlyList<SurfaceTrimContourSegment2D> Segments,
+ IReadOnlyList<string> Diagnostics,
+ bool ContourStitchingImplemented = false,
+ bool AnalyticSnapImplemented = false,
+ bool ExactExportAvailable = false);
+
+internal static class RestrictedFieldMarchingSquaresExtractor
+{
+ internal static SurfaceTrimContourExtractionResult Extract(RestrictedFieldSampleGrid grid, PlanarRectangleParameterization? parameterization = null, ToleranceContext? tolerance = null)
+ {
+ ArgumentNullException.ThrowIfNull(grid);
+
+ var tol = tolerance ?? ToleranceContext.Default;
+ var segments = new List<SurfaceTrimContourSegment2D>();
+ var diagnostics = new List<string> { "contour-extraction-started:method-marching-squares" };
+ var skippedUnknown = 0;
+ var ambiguous = 0;
+ var boundaryCells = 0;
+
+ foreach (var cell in grid.Cells.OrderBy(c => c.CellJ).ThenBy(c => c.CellI))
+ {
+ if (cell.Classification == RestrictedFieldCellClassification.Unknown)
+ {
+ skippedUnknown++;
+ continue;
+ }
+
+ if (cell.Classification is RestrictedFieldCellClassification.Inside or RestrictedFieldCellClassification.Outside)
+ {
+ continue;
+ }
+
+ if (cell.Classification == RestrictedFieldCellClassification.Boundary)
+ {
+ boundaryCells++;
+ }
+
+ var corners = cell.CornerSampleIndices.Select(i => grid.Samples[i]).ToArray(); // BL, BR, TL, TR
+ var cornerValues = corners.Select(c => c.Sample.Value).ToArray();
+ var cornerSigns = cornerValues.Select(v => ClassifySign(v, tol)).ToArray();
+
+ var edgeHits = new List<(int edge, SurfaceTrimContourPoint2D point, SurfaceTrimContourPoint3D? point3D)>();
+ TryAddEdgeHit(0, corners[0], corners[1], tol, parameterization, edgeHits); // bottom
+ TryAddEdgeHit(1, corners[1], corners[3], tol, parameterization, edgeHits); // right
+ TryAddEdgeHit(2, corners[2], corners[3], tol, parameterization, edgeHits); // top
+ TryAddEdgeHit(3, corners[0], corners[2], tol, parameterization, edgeHits); // left
+
+ if (edgeHits.Count < 2)
+ {
+ continue;
+ }
+
+ var localDiagnostics = new List<string>();
+ if (edgeHits.Count > 2)
+ {
+ ambiguous++;
+ localDiagnostics.Add("ambiguous-cell:multi-edge-intersections");
+ }
+
+ edgeHits.Sort((a, b) => a.edge.CompareTo(b.edge));
+ if (edgeHits.Count == 2)
+ {
+ segments.Add(new SurfaceTrimContourSegment2D(cell.CellI, cell.CellJ, edgeHits[0].point, edgeHits[1].point, cell.Classification, localDiagnostics, edgeHits[0].point3D, edgeHits[1].point3D));
+ continue;
+ }
+
+ // Deterministic saddle handling: use asymptotic-decider style center sign to pair edges.
+ var center = 0.25d * (cornerValues[0] + cornerValues[1] + cornerValues[2] + cornerValues[3]);
+ localDiagnostics.Add($"ambiguous-center:{center:R}");
+ var centerInside = center < -tol.Linear;
+ var pairing = centerInside
+ ? new[] { (0, 3), (1, 2) }
+ : new[] { (0, 1), (2, 3) };
+
+ foreach (var (ea, eb) in pairing)
+ {
+ var a = edgeHits.FirstOrDefault(h => h.edge == ea);
+ var b = edgeHits.FirstOrDefault(h => h.edge == eb);
+ if (a == default || b == default)
+ {
+ continue;
+ }
+
+ segments.Add(new SurfaceTrimContourSegment2D(cell.CellI, cell.CellJ, a.point, b.point, cell.Classification, localDiagnostics, a.point3D, b.point3D));
+ }
+ }
+
+ diagnostics.Add($"contour-segment-count:{segments.Count}");
+ diagnostics.Add($"contour-skipped-unknown-cell-count:{skippedUnknown}");
+ diagnostics.Add($"contour-ambiguous-cell-count:{ambiguous}");
+ diagnostics.Add($"contour-boundary-cell-count:{boundaryCells}");
+ diagnostics.Add("contour-stitching-not-implemented");
+ diagnostics.Add("contour-analytic-snap-not-implemented");
+ diagnostics.Add("contour-exact-export-not-available");
+
+ var success = segments.Count > 0 || grid.Counts.MixedCellCount == 0;
+ if (segments.Count == 0)
+ {
+ diagnostics.Add("no-contour-segments-detected");
+ }
+
+ return new SurfaceTrimContourExtractionResult(success, RestrictedFieldContourExtractionMethod.MarchingSquares, segments.Count, segments, diagnostics);
+ }
+
+ private static int ClassifySign(double value, ToleranceContext tol)
+ => double.Abs(value) <= tol.Linear ? 0 : value < 0d ? -1 : 1;
+
+ private static void TryAddEdgeHit(
+ int edgeId,
+ RestrictedFieldGridSample a,
+ RestrictedFieldGridSample b,
+ ToleranceContext tol,
+ PlanarRectangleParameterization? parameterization,
+ List<(int edge, SurfaceTrimContourPoint2D point, SurfaceTrimContourPoint3D? point3D)> hits)
+ {
+ var va = a.Sample.Value;
+ var vb = b.Sample.Value;
+ var sa = ClassifySign(va, tol);
+ var sb = ClassifySign(vb, tol);
+
+ if (sa == 0 && sb == 0)
+ {
+ return;
+ }
+
+ double t;
+ if (sa == 0)
+ {
+ t = 0d;
+ }
+ else if (sb == 0)
+ {
+ t = 1d;
+ }
+ else if (sa == sb)
+ {
+ return;
+ }
+ else
+ {
+ var denom = va - vb;
+ if (ToleranceMath.AlmostZero(denom, tol))
+ {
+ t = 0.5d;
+ }
+ else
+ {
+ t = va / (va - vb);
+ }
+ }
+
+ t = double.Clamp(t, 0d, 1d);
+ var u = a.U + (b.U - a.U) * t;
+ var v = a.V + (b.V - a.V) * t;
+ var value = a.Sample.Value + (b.Sample.Value - a.Sample.Value) * t;
+ SurfaceTrimContourPoint3D? point3D = null;
+ if (parameterization is { } p)
+ {
+ point3D = new SurfaceTrimContourPoint3D(p.Evaluate(u, v), u, v);
+ }
+
+ hits.Add((edgeId, new SurfaceTrimContourPoint2D(u, v, value), point3D));
+ }
+}
diff --git a/docs/cir-t3-marching-squares-contours.md b/docs/cir-t3-marching-squares-contours.md
new file mode 100644
index 00000000..c0079c69
--- /dev/null
+++ b/docs/cir-t3-marching-squares-contours.md
@@ -0,0 +1,69 @@
+# CIR-T3 — Deterministic marching-squares contour extraction over restricted-field grids
+
+## Purpose
+
+CIR-T3 adds a deterministic, numerical contour extraction stage that consumes the CIR-T2 `RestrictedFieldSampleGrid` and computes approximate zero-crossing segments in source UV space.
+
+This milestone answers: **where does `g(u,v)=0` approximately cross the sampled planar parameter domain?**
+
+## Scope and constraints
+
+Implemented:
+- Marching squares over planar rectangular restricted-field grids.
+- Deterministic cell scan order (row-major by `CellJ`, then `CellI`).
+- Linear interpolation on crossed cell edges using sampled scalar values.
+- Deterministic ambiguity diagnostics and pair selection.
+- Explicit non-goal diagnostics (stitching/snap/export unavailable).
+
+Not implemented (deferred):
+- contour stitching into loops,
+- analytic snap / exact curve recognition,
+- BRep topology emission,
+- STEP export behavior changes,
+- seam-aware parameter domains and non-planar source parameter spaces.
+
+## Marching-squares policy
+
+- Input is **only** `RestrictedFieldSampleGrid` from CIR-T2. No resampling is performed.
+- Cells classified `Inside` / `Outside` are skipped.
+- `Unknown` cells are skipped and counted in diagnostics.
+- `Mixed` and `Boundary` cells are processed for possible edge intersections.
+- Edge crossings are found from endpoint values/signs with tolerance-aware boundary handling.
+
+## Interpolation policy
+
+For edge endpoints `(a, b)` with scalar values `(va, vb)`:
+- if one endpoint is boundary-valued, use that endpoint directly,
+- if signs differ, compute `t = va / (va - vb)`,
+- if denominator is near-zero, use midpoint `t=0.5`,
+- clamp `t` to `[0,1]` defensively.
+
+The extracted UV location is linearly interpolated from the edge endpoint UVs.
+
+## Ambiguous / boundary handling
+
+Cells with more than two edge intersections are treated as ambiguous saddles.
+
+T3 resolves these deterministically using a center-value decider (`avg(corner values)`), records ambiguity diagnostics, and emits deterministic segment pairings. This keeps behavior stable while preserving explicit diagnostics for future refinement in T4.
+
+## Output model
+
+Extraction returns `SurfaceTrimContourExtractionResult` containing:
+- method (`MarchingSquares`),
+- ordered 2D segments (`SurfaceTrimContourSegment2D`),
+- optional lifted 3D endpoints when parameterization is provided,
+- aggregate diagnostics,
+- explicit `ContourStitchingImplemented=false`, `AnalyticSnapImplemented=false`, `ExactExportAvailable=false`.
+
+## Numerical status
+
+This is a numerical trim-oracle output only.
+Contours are approximate polyline segments in UV; no exact analytic claim is made.
+
+## SEM-A0 status
+
+CIR-T3 introduces no generated topology naming and no provenance model expansion. SEM-A0 guardrails remain preserved.
+
+## Recommended CIR-T4
+
+Add deterministic contour stitching from segments into open/closed polyline chains, including junction diagnostics and continuity tolerances, while keeping analytic snap explicitly deferred.