Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add CIR adaptive region work-queue volume estimator
Yuechen Li28d5e4c9d966
diff --git a/Aetheris.Kernel.Core.Tests/Cir/CirAdaptiveVolumeEstimatorTests.cs b/Aetheris.Kernel.Core.Tests/Cir/CirAdaptiveVolumeEstimatorTests.csnew file mode 100644index 00000000..c710b5db--- /dev/null+++ b/Aetheris.Kernel.Core.Tests/Cir/CirAdaptiveVolumeEstimatorTests.cs@@ -0,0 +1,93 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Math;++namespace Aetheris.Kernel.Core.Tests.Cir;++public sealed class CirAdaptiveVolumeEstimatorTests+{+ [Fact]+ public void AdaptiveVolume_Box_IsReasonable()+ {+ var box = new CirBoxNode(6d, 4d, 2d);+ var tape = CirTapeLowerer.Lower(box);++ var result = CirAdaptiveVolumeEstimator.EstimateVolume(tape, box.Bounds, new CirAdaptiveVolumeOptions(MaxDepth: 5, DirectSampleGrid: 2));++ Assert.InRange(result.EstimatedVolume, 47.5d, 48.5d);+ }++ [Fact]+ public void AdaptiveVolume_BoxMinusCylinder_IsReasonable()+ {+ var box = new CirBoxNode(8d, 8d, 8d);+ var cut = new CirSubtractNode(box, new CirCylinderNode(2d, 8d));+ var tape = CirTapeLowerer.Lower(cut);+ var expected = (8d * 8d * 8d) - (System.Math.PI * 4d * 8d);++ var result = CirAdaptiveVolumeEstimator.EstimateVolume(tape, box.Bounds, new CirAdaptiveVolumeOptions(MaxDepth: 7, DirectSampleGrid: 2));++ Assert.InRange(result.EstimatedVolume, expected - 15d, expected + 15d);+ }++ [Fact]+ public void AdaptiveVolume_UsesPlannerCounters()+ {+ var box = new CirBoxNode(8d, 8d, 8d);+ var tape = CirTapeLowerer.Lower(box);+ var options = new CirAdaptiveVolumeOptions(MaxDepth: 6, DirectSampleGrid: 2);++ var insideRegion = new CirBounds(new Point3D(-1d, -1d, -1d), new Point3D(1d, 1d, 1d));+ var outsideRegion = new CirBounds(new Point3D(10d, 10d, 10d), new Point3D(12d, 12d, 12d));+ var mixedRegion = new CirBounds(new Point3D(-6d, -6d, -6d), new Point3D(6d, 6d, 6d));++ var insideResult = CirAdaptiveVolumeEstimator.EstimateVolume(tape, insideRegion, options);+ var outsideResult = CirAdaptiveVolumeEstimator.EstimateVolume(tape, outsideRegion, options);+ var mixedResult = CirAdaptiveVolumeEstimator.EstimateVolume(tape, mixedRegion, options);++ Assert.True(insideResult.RegionsClassifiedInside > 0);+ Assert.True(outsideResult.RegionsClassifiedOutside > 0);+ Assert.True(mixedResult.RegionsSubdivided > 0 || mixedResult.RegionsSampledDirectly > 0);+ }++ [Fact]+ public void AdaptiveVolume_Deterministic()+ {+ var cut = new CirSubtractNode(new CirBoxNode(8d, 8d, 8d), new CirCylinderNode(2d, 8d));+ var tape = CirTapeLowerer.Lower(cut);+ var options = new CirAdaptiveVolumeOptions(MaxDepth: 6, DirectSampleGrid: 2, MaxTraceEvents: 24);++ var first = CirAdaptiveVolumeEstimator.EstimateVolume(tape, cut.Bounds, options);+ var second = CirAdaptiveVolumeEstimator.EstimateVolume(tape, cut.Bounds, options);++ Assert.Equal(first.EstimatedVolume, second.EstimatedVolume);+ Assert.Equal(first.TotalRegionsVisited, second.TotalRegionsVisited);+ Assert.Equal(first.RegionsSubdivided, second.RegionsSubdivided);+ Assert.Equal(first.RegionsSampledDirectly, second.RegionsSampledDirectly);+ Assert.Equal(first.TraceEvents, second.TraceEvents);+ }++ [Fact]+ public void AdaptiveVolume_TraceIncludesPlannerDecision()+ {+ var cut = new CirSubtractNode(new CirBoxNode(8d, 8d, 8d), new CirCylinderNode(2d, 8d));+ var tape = CirTapeLowerer.Lower(cut);++ var result = CirAdaptiveVolumeEstimator.EstimateVolume(tape, cut.Bounds, new CirAdaptiveVolumeOptions(MaxDepth: 6, DirectSampleGrid: 2, MaxTraceEvents: 32));++ Assert.NotEmpty(result.TraceEvents);+ Assert.Contains(result.TraceEvents, e => !string.IsNullOrWhiteSpace(e.Candidate));+ Assert.Contains(result.TraceEvents, e => e.Action is CirRegionPlanAction.Subdivide or CirRegionPlanAction.SampleDirectly or CirRegionPlanAction.ClassifyInside or CirRegionPlanAction.ClassifyOutside);+ }++ [Fact]+ public void NaiveVolumeComparison()+ {+ var cut = new CirSubtractNode(new CirBoxNode(8d, 8d, 8d), new CirCylinderNode(2d, 8d));+ var tape = CirTapeLowerer.Lower(cut);+ var dense = CirVolumeEstimator.EstimateVolume(cut, resolution: 30);++ var adaptive = CirAdaptiveVolumeEstimator.EstimateVolume(tape, cut.Bounds, new CirAdaptiveVolumeOptions(MaxDepth: 7, DirectSampleGrid: 2));++ Assert.InRange(System.Math.Abs(adaptive.EstimatedVolume - dense), 0d, 25d);+ }+}diff --git a/Aetheris.Kernel.Core/Cir/CirAdaptiveVolumeEstimator.cs b/Aetheris.Kernel.Core/Cir/CirAdaptiveVolumeEstimator.csnew file mode 100644index 00000000..1142e9b4--- /dev/null+++ b/Aetheris.Kernel.Core/Cir/CirAdaptiveVolumeEstimator.cs@@ -0,0 +1,181 @@+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Core.Numerics;++namespace Aetheris.Kernel.Core.Cir;++public sealed record CirAdaptiveVolumeOptions(+ int MaxDepth = 6,+ int DirectSampleGrid = 2,+ int MaxTraceEvents = 64,+ double MinimumRegionExtent = 0.05d,+ bool TreatRejectUnknownAsSample = true)+{+ public static CirAdaptiveVolumeOptions Default { get; } = new();+}++public readonly record struct CirAdaptiveTraceEvent(+ int RegionId,+ int? ParentRegionId,+ int Depth,+ CirRegionPlanAction Action,+ string Candidate,+ FieldInterval Interval,+ string? Note);++public sealed record CirAdaptiveVolumeResult(+ double EstimatedVolume,+ CirAdaptiveVolumeOptions Options,+ int TotalRegionsVisited,+ int RegionsClassifiedInside,+ int RegionsClassifiedOutside,+ int RegionsSubdivided,+ int RegionsSampledDirectly,+ int UnknownOrRejectedRegions,+ int MaxDepthReached,+ IReadOnlyList<CirAdaptiveTraceEvent> TraceEvents,+ IReadOnlyList<string> Notes);++public static class CirAdaptiveVolumeEstimator+{+ public static CirAdaptiveVolumeResult EstimateVolume(CirTape tape, CirBounds bounds, CirAdaptiveVolumeOptions? options = null, ToleranceContext? tolerance = null)+ {+ ArgumentNullException.ThrowIfNull(tape);++ var effectiveOptions = options ?? CirAdaptiveVolumeOptions.Default;+ var effectiveTolerance = tolerance ?? ToleranceContext.Default;+ var planner = new CirRegionPlanner();+ var plannerOptions = new CirRegionPlannerOptions(effectiveOptions.MaxDepth, DirectSampleThreshold: effectiveOptions.DirectSampleGrid * effectiveOptions.DirectSampleGrid * effectiveOptions.DirectSampleGrid, effectiveOptions.MinimumRegionExtent);+ var queue = new Queue<RegionWorkItem>();+ var trace = new List<CirAdaptiveTraceEvent>(capacity: effectiveOptions.MaxTraceEvents);+ var notes = new List<string>();++ queue.Enqueue(new RegionWorkItem(0, null, bounds, 0));+ var nextId = 1;+ var totalVisited = 0;+ var inside = 0;+ var outside = 0;+ var subdivided = 0;+ var sampled = 0;+ var unknown = 0;+ var maxDepthReached = 0;+ var totalVolume = 0d;++ while (queue.Count > 0)+ {+ var item = queue.Dequeue();+ totalVisited++;+ maxDepthReached = int.Max(maxDepthReached, item.Depth);++ var plan = planner.Plan(tape, item.Region, item.Depth, plannerOptions, effectiveTolerance);+ TryRecordTrace(trace, effectiveOptions.MaxTraceEvents, item, plan);++ switch (plan.Action)+ {+ case CirRegionPlanAction.ClassifyInside:+ inside++;+ totalVolume += RegionVolume(item.Region);+ break;+ case CirRegionPlanAction.ClassifyOutside:+ outside++;+ break;+ case CirRegionPlanAction.Subdivide:+ subdivided++;+ foreach (var child in SplitLongestAxis(item.Region))+ {+ queue.Enqueue(new RegionWorkItem(nextId++, item.RegionId, child, item.Depth + 1));+ }+ break;+ case CirRegionPlanAction.MarkMixed:+ case CirRegionPlanAction.SampleDirectly:+ sampled++;+ totalVolume += SampleRegionVolume(tape, item.Region, effectiveOptions.DirectSampleGrid);+ break;+ case CirRegionPlanAction.RejectUnknown:+ unknown++;+ if (effectiveOptions.TreatRejectUnknownAsSample)+ {+ sampled++;+ totalVolume += SampleRegionVolume(tape, item.Region, effectiveOptions.DirectSampleGrid);+ }+ else+ {+ notes.Add($"Region {item.RegionId} rejected by planner and skipped: {plan.Note ?? "no note"}.");+ }+ break;+ }+ }++ return new CirAdaptiveVolumeResult(totalVolume, effectiveOptions, totalVisited, inside, outside, subdivided, sampled, unknown, maxDepthReached, trace, notes);+ }++ private static void TryRecordTrace(List<CirAdaptiveTraceEvent> trace, int maxTraceEvents, RegionWorkItem item, CirRegionPlanResult plan)+ {+ if (trace.Count >= maxTraceEvents)+ {+ return;+ }++ trace.Add(new CirAdaptiveTraceEvent(item.RegionId, item.ParentRegionId, item.Depth, plan.Action, plan.SelectedCandidate, plan.Interval, plan.Note));+ }++ private static double SampleRegionVolume(CirTape tape, CirBounds region, int grid)+ {+ var sampleGrid = int.Max(grid, 1);+ var dx = region.SizeX / sampleGrid;+ var dy = region.SizeY / sampleGrid;+ var dz = region.SizeZ / sampleGrid;+ var insideCount = 0;+ var totalSamples = sampleGrid * sampleGrid * sampleGrid;++ for (var ix = 0; ix < sampleGrid; ix++)+ for (var iy = 0; iy < sampleGrid; iy++)+ for (var iz = 0; iz < sampleGrid; iz++)+ {+ var point = new Point3D(region.Min.X + ((ix + 0.5d) * dx), region.Min.Y + ((iy + 0.5d) * dy), region.Min.Z + ((iz + 0.5d) * dz));+ if (tape.Evaluate(point) <= 0d)+ {+ insideCount++;+ }+ }++ return RegionVolume(region) * (insideCount / (double)totalSamples);+ }++ private static double RegionVolume(CirBounds region) => double.Max(region.SizeX, 0d) * double.Max(region.SizeY, 0d) * double.Max(region.SizeZ, 0d);++ private static IReadOnlyList<CirBounds> SplitLongestAxis(CirBounds region)+ {+ var sizeX = region.SizeX;+ var sizeY = region.SizeY;+ var sizeZ = region.SizeZ;++ if (sizeX >= sizeY && sizeX >= sizeZ)+ {+ var mid = (region.Min.X + region.Max.X) * 0.5d;+ return+ [+ new CirBounds(region.Min, new Point3D(mid, region.Max.Y, region.Max.Z)),+ new CirBounds(new Point3D(mid, region.Min.Y, region.Min.Z), region.Max),+ ];+ }++ if (sizeY >= sizeX && sizeY >= sizeZ)+ {+ var mid = (region.Min.Y + region.Max.Y) * 0.5d;+ return+ [+ new CirBounds(region.Min, new Point3D(region.Max.X, mid, region.Max.Z)),+ new CirBounds(new Point3D(region.Min.X, mid, region.Min.Z), region.Max),+ ];+ }++ var midZ = (region.Min.Z + region.Max.Z) * 0.5d;+ return+ [+ new CirBounds(region.Min, new Point3D(region.Max.X, region.Max.Y, midZ)),+ new CirBounds(new Point3D(region.Min.X, region.Min.Y, midZ), region.Max),+ ];+ }++ private readonly record struct RegionWorkItem(int RegionId, int? ParentRegionId, CirBounds Region, int Depth);+}