Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add M12 boolean pipeline scaffolding and tests

Yuechen Li72bb68c84d24
diff --git a/Aetheris.Kernel.Core.Tests/Brep/Boolean/BrepBooleanTests.cs b/Aetheris.Kernel.Core.Tests/Brep/Boolean/BrepBooleanTests.cs
new file mode 100644
index 00000000..7205b9b2
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Brep/Boolean/BrepBooleanTests.cs
@@ -0,0 +1,96 @@
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Brep.Boolean;
+using Aetheris.Kernel.Core.Diagnostics;
+
+namespace Aetheris.Kernel.Core.Tests.Brep.Boolean;
+
+public sealed class BrepBooleanTests
+{
+ [Fact]
+ public void Execute_NullRequest_FailsWithInvalidArgumentDiagnostic()
+ {
+ var result = BrepBoolean.Execute(request: null);
+
+ Assert.False(result.IsSuccess);
+ var diagnostic = Assert.Single(result.Diagnostics);
+ Assert.Equal(KernelDiagnosticCode.InvalidArgument, diagnostic.Code);
+ Assert.Equal("Boolean request must be provided.", diagnostic.Message);
+ Assert.Equal("BrepBoolean.ValidateInputs", diagnostic.Source);
+ }
+
+ [Fact]
+ public void Execute_NullBodyInRequest_FailsPredictably()
+ {
+ var right = BrepPrimitives.CreateBox(1d, 1d, 1d).Value;
+ var request = new BooleanRequest(null!, right, BooleanOperation.Union);
+
+ var result = BrepBoolean.Execute(request);
+
+ Assert.False(result.IsSuccess);
+ var diagnostic = Assert.Single(result.Diagnostics);
+ Assert.Equal(KernelDiagnosticCode.InvalidArgument, diagnostic.Code);
+ Assert.Equal("Boolean Union: left body must be provided.", diagnostic.Message);
+ Assert.Equal("BrepBoolean.ValidateInputs", diagnostic.Source);
+ }
+
+ [Fact]
+ public void Execute_DifferentBodies_ReturnsNotImplementedWithoutThrowing()
+ {
+ var left = BrepPrimitives.CreateBox(2d, 2d, 2d).Value;
+ var right = BrepPrimitives.CreateBox(3d, 3d, 3d).Value;
+
+ var exception = Record.Exception(() => BrepBoolean.Execute(new BooleanRequest(left, right, BooleanOperation.Union)));
+
+ Assert.Null(exception);
+
+ var result = BrepBoolean.Execute(new BooleanRequest(left, right, BooleanOperation.Union));
+ Assert.False(result.IsSuccess);
+
+ var diagnostic = Assert.Single(result.Diagnostics);
+ Assert.Equal(KernelDiagnosticCode.NotImplemented, diagnostic.Code);
+ Assert.Equal("Boolean Union: general B-rep boolean intersection/rebuild is not implemented in M12.", diagnostic.Message);
+ Assert.Equal("BrepBoolean.RebuildResult", diagnostic.Source);
+ }
+
+ [Fact]
+ public void Intersect_SameBodyInstance_SucceedsAndReturnsSameInstance()
+ {
+ var body = BrepPrimitives.CreateBox(2d, 3d, 4d).Value;
+
+ var result = BrepBoolean.Intersect(body, body);
+
+ Assert.True(result.IsSuccess);
+ Assert.Same(body, result.Value);
+
+ var validation = BrepBindingValidator.Validate(result.Value, requireAllEdgeAndFaceBindings: true);
+ Assert.True(validation.IsSuccess);
+ }
+
+ [Fact]
+ public void Union_SameBodyInstance_SucceedsAndReturnsSameInstance()
+ {
+ var body = BrepPrimitives.CreateCylinder(1d, 2d).Value;
+
+ var result = BrepBoolean.Union(body, body);
+
+ Assert.True(result.IsSuccess);
+ Assert.Same(body, result.Value);
+
+ var validation = BrepBindingValidator.Validate(result.Value, requireAllEdgeAndFaceBindings: true);
+ Assert.True(validation.IsSuccess);
+ }
+
+ [Fact]
+ public void Subtract_SameBodyInstance_ReturnsNotImplemented()
+ {
+ var body = BrepPrimitives.CreateSphere(1d).Value;
+
+ var result = BrepBoolean.Subtract(body, body);
+
+ Assert.False(result.IsSuccess);
+ var diagnostic = Assert.Single(result.Diagnostics);
+ Assert.Equal(KernelDiagnosticCode.NotImplemented, diagnostic.Code);
+ Assert.Equal("Boolean Subtract: same-body subtraction requires an empty-body representation that is not available in M12.", diagnostic.Message);
+ Assert.Equal("BrepBoolean.RebuildResult", diagnostic.Source);
+ }
+}
diff --git a/Aetheris.Kernel.Core/Brep/Boolean/BrepBoolean.cs b/Aetheris.Kernel.Core/Brep/Boolean/BrepBoolean.cs
new file mode 100644
index 00000000..9f682301
--- /dev/null
+++ b/Aetheris.Kernel.Core/Brep/Boolean/BrepBoolean.cs
@@ -0,0 +1,194 @@
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Numerics;
+using Aetheris.Kernel.Core.Results;
+
+namespace Aetheris.Kernel.Core.Brep.Boolean;
+
+public enum BooleanOperation
+{
+ Union,
+ Subtract,
+ Intersect,
+}
+
+public sealed record BooleanRequest(
+ BrepBody Left,
+ BrepBody Right,
+ BooleanOperation Operation,
+ ToleranceContext? Tolerance = null);
+
+public sealed record BooleanAnalysis(
+ BooleanOperation Operation,
+ bool IsSameBodyInstance,
+ string? ShortcutReason);
+
+public sealed record BooleanIntersectionData(
+ BooleanAnalysis Analysis,
+ bool IsComputed,
+ int CandidatePairCount);
+
+public sealed record BooleanClassificationData(
+ BooleanIntersectionData Intersections,
+ bool IsComputed,
+ int FragmentCount);
+
+public sealed record BooleanRebuildData(
+ BooleanClassificationData Classification,
+ BrepBody? RebuiltBody,
+ IReadOnlyList<KernelDiagnostic> Diagnostics);
+
+/// <summary>
+/// M12 boolean pipeline scaffold.
+/// Only same-instance Union/Intersect shortcuts are supported in this milestone.
+/// All other requests return deterministic NotImplemented diagnostics.
+/// </summary>
+public static class BrepBoolean
+{
+ public static KernelResult<BrepBody> Union(BrepBody left, BrepBody right)
+ => Execute(new BooleanRequest(left, right, BooleanOperation.Union));
+
+ public static KernelResult<BrepBody> Subtract(BrepBody left, BrepBody right)
+ => Execute(new BooleanRequest(left, right, BooleanOperation.Subtract));
+
+ public static KernelResult<BrepBody> Intersect(BrepBody left, BrepBody right)
+ => Execute(new BooleanRequest(left, right, BooleanOperation.Intersect));
+
+ public static KernelResult<BrepBody> Execute(BooleanRequest? request)
+ {
+ var validation = ValidateInputs(request);
+ if (!validation.IsSuccess)
+ {
+ return KernelResult<BrepBody>.Failure(validation.Diagnostics);
+ }
+
+ var analysis = AnalyzeInputs(validation.Value);
+ var intersections = ComputeIntersections(analysis);
+ var classification = ClassifyFragments(intersections);
+ var rebuild = RebuildResult(validation.Value, classification);
+ if (rebuild.Diagnostics.Any(d => d.Severity == KernelDiagnosticSeverity.Error))
+ {
+ return KernelResult<BrepBody>.Failure(rebuild.Diagnostics);
+ }
+
+ if (rebuild.RebuiltBody is null)
+ {
+ return KernelResult<BrepBody>.Failure([
+ CreateInternalError("Pipeline completed without a rebuilt body.", source: "BrepBoolean.RebuildResult"),
+ ]);
+ }
+
+ return ValidateOutput(rebuild.RebuiltBody, rebuild.Diagnostics);
+ }
+
+ private static KernelResult<BooleanRequest> ValidateInputs(BooleanRequest? request)
+ {
+ if (request is null)
+ {
+ return KernelResult<BooleanRequest>.Failure([
+ CreateInvalidArgument("Boolean request must be provided.", source: "BrepBoolean.ValidateInputs"),
+ ]);
+ }
+
+ var diagnostics = new List<KernelDiagnostic>();
+ if (request.Left is null)
+ {
+ diagnostics.Add(CreateInvalidArgument($"Boolean {request.Operation}: left body must be provided.", source: "BrepBoolean.ValidateInputs"));
+ }
+
+ if (request.Right is null)
+ {
+ diagnostics.Add(CreateInvalidArgument($"Boolean {request.Operation}: right body must be provided.", source: "BrepBoolean.ValidateInputs"));
+ }
+
+ return diagnostics.Count > 0
+ ? KernelResult<BooleanRequest>.Failure(diagnostics)
+ : KernelResult<BooleanRequest>.Success(request);
+ }
+
+ private static BooleanAnalysis AnalyzeInputs(BooleanRequest request)
+ {
+ var isSameBodyInstance = ReferenceEquals(request.Left, request.Right);
+ var shortcutReason = isSameBodyInstance
+ ? $"Boolean {request.Operation}: same-body shortcut candidate."
+ : null;
+
+ return new BooleanAnalysis(request.Operation, isSameBodyInstance, shortcutReason);
+ }
+
+ private static BooleanIntersectionData ComputeIntersections(BooleanAnalysis analysis)
+ {
+ var candidatePairCount = analysis.IsSameBodyInstance ? 1 : 0;
+ return new BooleanIntersectionData(analysis, IsComputed: true, candidatePairCount);
+ }
+
+ private static BooleanClassificationData ClassifyFragments(BooleanIntersectionData intersections)
+ {
+ var fragmentCount = intersections.Analysis.IsSameBodyInstance ? 1 : 0;
+ return new BooleanClassificationData(intersections, IsComputed: true, fragmentCount);
+ }
+
+ private static BooleanRebuildData RebuildResult(BooleanRequest request, BooleanClassificationData classification)
+ {
+ var operation = request.Operation;
+ if (classification.Intersections.Analysis.IsSameBodyInstance)
+ {
+ return operation switch
+ {
+ BooleanOperation.Union or BooleanOperation.Intersect => new BooleanRebuildData(
+ classification,
+ RebuiltBody: request.Left,
+ Diagnostics: Array.Empty<KernelDiagnostic>()),
+ BooleanOperation.Subtract => new BooleanRebuildData(
+ classification,
+ RebuiltBody: null,
+ Diagnostics:
+ [
+ CreateNotImplemented(
+ $"Boolean {operation}: same-body subtraction requires an empty-body representation that is not available in M12.",
+ source: "BrepBoolean.RebuildResult"),
+ ]),
+ _ => new BooleanRebuildData(
+ classification,
+ RebuiltBody: null,
+ Diagnostics:
+ [
+ CreateInternalError($"Boolean {operation}: unexpected operation.", source: "BrepBoolean.RebuildResult"),
+ ]),
+ };
+ }
+
+ return new BooleanRebuildData(
+ classification,
+ RebuiltBody: null,
+ Diagnostics:
+ [
+ CreateNotImplemented(
+ $"Boolean {operation}: general B-rep boolean intersection/rebuild is not implemented in M12.",
+ source: "BrepBoolean.RebuildResult"),
+ ]);
+ }
+
+ private static KernelResult<BrepBody> ValidateOutput(BrepBody body, IReadOnlyList<KernelDiagnostic> diagnostics)
+ {
+ var validation = BrepBindingValidator.Validate(body, requireAllEdgeAndFaceBindings: true);
+ if (!validation.IsSuccess)
+ {
+ return KernelResult<BrepBody>.Failure(validation.Diagnostics);
+ }
+
+ var mergedDiagnostics = diagnostics.Count == 0
+ ? validation.Diagnostics
+ : [.. diagnostics, .. validation.Diagnostics];
+
+ return KernelResult<BrepBody>.Success(body, mergedDiagnostics);
+ }
+
+ private static KernelDiagnostic CreateInvalidArgument(string message, string source)
+ => new(KernelDiagnosticCode.InvalidArgument, KernelDiagnosticSeverity.Error, message, source);
+
+ private static KernelDiagnostic CreateNotImplemented(string message, string source)
+ => new(KernelDiagnosticCode.NotImplemented, KernelDiagnosticSeverity.Error, message, source);
+
+ private static KernelDiagnostic CreateInternalError(string message, string source)
+ => new(KernelDiagnosticCode.InternalError, KernelDiagnosticSeverity.Error, message, source);
+}
diff --git a/docs/milestones.md b/docs/milestones.md
index 7899a653..31c47fb8 100644
--- a/docs/milestones.md
+++ b/docs/milestones.md
@@ -97,3 +97,12 @@
- [x] Seam strategy: periodic side faces use one explicit seam edge referenced twice in the side loop; cap boundaries are represented as closed circular edges.
- [x] Add focused tests for validation/diagnostics, full-angle semantics, seam behavior, topology/geometry expectations, traversal safety, and strict binding validation.
- [x] Explicitly defer partial revolve, axis-touching/axis-crossing profiles, generalized polyline/curve revolves, and self-intersection handling.
+
+## M12 — Boolean Infrastructure v1 (Pipeline Scaffolding, Not Full Booleans)
+
+- [x] Add explicit boolean operation contracts (`BooleanOperation`, `BooleanRequest`) and a shared `BrepBoolean.Execute` entry point returning `KernelResult<BrepBody>`.
+- [x] Introduce staged boolean pipeline scaffolding (`ValidateInputs`, `AnalyzeInputs`, `ComputeIntersections`, `ClassifyFragments`, `RebuildResult`, `ValidateOutput`) plus minimal intermediate data types for stage handoff.
+- [x] Support tiny end-to-end identity shortcuts for same-instance `Union` and `Intersect`; outputs are validated in strict mode via `BrepBindingValidator` before success is returned.
+- [x] Return deterministic structured `NotImplemented` diagnostics for all non-supported M12 boolean requests, including same-instance `Subtract` (empty-body representation deferred).
+- [x] Add focused unit tests locking supported shortcuts, unsupported behavior, deterministic diagnostics, and no-throw behavior for routine unsupported cases.
+- [x] Explicitly defer general B-rep/B-rep intersection, fragment splitting/classification, and robust rebuild/healing to M13.