Skip to content

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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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);
+}