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