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