Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Add CIR-STEP-V1 canonical box-cylinder recognizer
Yuechen Liede19a8c65e9
diff --git a/Aetheris.Kernel.Firmament.Tests/CirBoxCylinderRecognizerTests.cs b/Aetheris.Kernel.Firmament.Tests/CirBoxCylinderRecognizerTests.csnew file mode 100644index 00000000..fb597658--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/CirBoxCylinderRecognizerTests.cs@@ -0,0 +1,109 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Core.Numerics;+using Aetheris.Kernel.Firmament.Execution;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class CirBoxCylinderRecognizerTests+{+ [Fact]+ public void Recognizes_DirectSubtract_BoxCylinder()+ {+ var input = new CirBoxCylinderRecognizerInput(new CirSubtractNode(new CirBoxNode(20, 10, 8), new CirCylinderNode(2, 20)));+ var result = CirBoxCylinderRecognizer.Recognize(input);+ Assert.True(result.Success);+ Assert.Equal(CirBoxCylinderRecognitionReason.Recognized, result.Reason);+ Assert.NotNull(result.Value);+ Assert.Equal(CirBoxCylinderAxisKind.Z, result.Value!.Axis);+ }++ [Fact]+ public void Recognizes_TranslationWrapped_Subtract_BoxCylinder()+ {+ var root = new CirSubtractNode(+ new CirTransformNode(new CirBoxNode(20, 20, 10), Transform3D.CreateTranslation(new Vector3D(5, 2, 4))),+ new CirTransformNode(new CirCylinderNode(3, 16), Transform3D.CreateTranslation(new Vector3D(4, 1, 4))));+ var result = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(root));+ Assert.True(result.Success);+ Assert.Equal(8d, result.Value!.ClearanceXPlus, 6);+ }++ [Fact]+ public void Rejects_NonSubtractRoot()+ {+ var result = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(new CirBoxNode(2,2,2)));+ Assert.False(result.Success);+ Assert.Equal(CirBoxCylinderRecognitionReason.UnsupportedRootNotSubtract, result.Reason);+ }++ [Fact]+ public void Rejects_LeftNotBox()+ {+ var result = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(new CirSubtractNode(new CirSphereNode(3), new CirCylinderNode(1, 10))));+ Assert.False(result.Success);+ Assert.Equal(CirBoxCylinderRecognitionReason.UnsupportedLeftNotBox, result.Reason);+ }++ [Fact]+ public void Rejects_RightNotCylinder()+ {+ var result = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(new CirSubtractNode(new CirBoxNode(10,10,10), new CirSphereNode(2))));+ Assert.False(result.Success);+ Assert.Equal(CirBoxCylinderRecognitionReason.UnsupportedRightNotCylinder, result.Reason);+ }++ [Fact]+ public void Rejects_UnsupportedTransform()+ {+ var rotated = new CirSubtractNode(new CirBoxNode(10,10,10), new CirTransformNode(new CirCylinderNode(2, 20), Transform3D.CreateRotationX(0.2)));+ var result = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(rotated));+ Assert.False(result.Success);+ Assert.Equal(CirBoxCylinderRecognitionReason.UnsupportedTransform, result.Reason);+ }++ [Fact]+ public void Rejects_BlindCylinder()+ {+ var root = new CirSubtractNode(new CirBoxNode(10,10,10), new CirCylinderNode(2, 8));+ var result = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(root));+ Assert.False(result.Success);+ Assert.Equal(CirBoxCylinderRecognitionReason.UnsupportedNotThroughHole, result.Reason);+ }++ [Fact]+ public void Rejects_Tangent_And_Outside()+ {+ var tangent = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(new CirSubtractNode(new CirBoxNode(10,10,10), new CirTransformNode(new CirCylinderNode(2, 20), Transform3D.CreateTranslation(new Vector3D(3, 0, 0))))));+ Assert.False(tangent.Success);+ Assert.Equal(CirBoxCylinderRecognitionReason.UnsupportedTangentOrGrazing, tangent.Reason);++ var outside = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(new CirSubtractNode(new CirBoxNode(10,10,10), new CirTransformNode(new CirCylinderNode(2, 20), Transform3D.CreateTranslation(new Vector3D(3.001 + ToleranceContext.Default.Linear, 0, 0))))));+ Assert.False(outside.Success);+ Assert.Equal(CirBoxCylinderRecognitionReason.UnsupportedCylinderOutsideBox, outside.Reason);+ }++ [Fact]+ public void Allows_Offset_ThroughHole_WithStrictClearance()+ {+ var root = new CirSubtractNode(new CirBoxNode(12, 12, 10), new CirTransformNode(new CirCylinderNode(2, 20), Transform3D.CreateTranslation(new Vector3D(1, -1, 0))));+ var result = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(root));+ Assert.True(result.Success);+ }++ [Fact]+ public void Replay_IsOptional_AndMismatchIsDiagnosticOnly()+ {+ var root = new CirSubtractNode(new CirBoxNode(12, 12, 10), new CirCylinderNode(2, 20));+ var noReplay = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(root));+ Assert.True(noReplay.Success);++ var mismatchReplay = new NativeGeometryReplayLog([+ new NativeGeometryReplayOperation(0, "base", "primitive:box", null, null, null, null, new NativeGeometryResolvedPlacement(NativeGeometryPlacementKind.None, null, null, Vector3D.Zero, Vector3D.Zero, true, null), null),+ new NativeGeometryReplayOperation(1, "cut", "boolean:subtract", "base", "box", "tool", null, new NativeGeometryResolvedPlacement(NativeGeometryPlacementKind.None, null, null, Vector3D.Zero, Vector3D.Zero, true, null), null)+ ]);+ var withReplay = CirBoxCylinderRecognizer.Recognize(new CirBoxCylinderRecognizerInput(root, mismatchReplay));+ Assert.True(withReplay.Success);+ Assert.Equal(CirBoxCylinderRecognitionReason.ReplayMismatch, withReplay.Reason);+ }+}diff --git a/Aetheris.Kernel.Firmament/Execution/CirBoxCylinderRecognizer.cs b/Aetheris.Kernel.Firmament/Execution/CirBoxCylinderRecognizer.csnew file mode 100644index 00000000..413c184d--- /dev/null+++ b/Aetheris.Kernel.Firmament/Execution/CirBoxCylinderRecognizer.cs@@ -0,0 +1,225 @@+using Aetheris.Kernel.Core.Cir;+using Aetheris.Kernel.Core.Math;+using Aetheris.Kernel.Core.Numerics;++namespace Aetheris.Kernel.Firmament.Execution;++internal enum CirBoxCylinderRecognitionReason+{+ Recognized,+ UnsupportedRootNotSubtract,+ UnsupportedLeftNotBox,+ UnsupportedRightNotCylinder,+ UnsupportedTransform,+ InvalidBoxDimensions,+ InvalidCylinderDimensions,+ UnsupportedNotThroughHole,+ UnsupportedTangentOrGrazing,+ UnsupportedCylinderOutsideBox,+ ReplayMismatch,+ UnsupportedNestedOrComposite,+ Unknown+}++internal enum CirBoxCylinderAxisKind+{+ Z+}++internal sealed record CirBoxCylinderRecognizerInput(+ CirNode Root,+ NativeGeometryReplayLog? ReplayLog = null,+ string? SourceLabel = null);++internal sealed record RecognizedBoxCylinder(+ double BoxWidth,+ double BoxHeight,+ double BoxDepth,+ double CylinderRadius,+ double CylinderHeight,+ Vector3D BoxTranslation,+ Vector3D CylinderTranslation,+ CirBoxCylinderAxisKind Axis,+ double ThroughLength,+ double ClearanceXMinus,+ double ClearanceXPlus,+ double ClearanceYMinus,+ double ClearanceYPlus);++internal sealed record CirBoxCylinderRecognitionResult(+ bool Success,+ CirBoxCylinderRecognitionReason Reason,+ string Diagnostic,+ RecognizedBoxCylinder? Value,+ IReadOnlyList<string> Diagnostics);++internal static class CirBoxCylinderRecognizer+{+ internal static CirBoxCylinderRecognitionResult Recognize(CirBoxCylinderRecognizerInput input)+ {+ ArgumentNullException.ThrowIfNull(input);+ var diagnostics = new List<string>();+ var tol = ToleranceContext.Default.Linear;++ if (input.Root is not CirSubtractNode subtract)+ {+ return Fail(CirBoxCylinderRecognitionReason.UnsupportedRootNotSubtract, "Root must be CirSubtractNode.", diagnostics);+ }++ if (subtract.Left is CirSubtractNode or CirUnionNode or CirIntersectNode || subtract.Right is CirSubtractNode or CirUnionNode or CirIntersectNode)+ {+ return Fail(CirBoxCylinderRecognitionReason.UnsupportedNestedOrComposite, "Nested/composite booleans are unsupported in CIR-STEP-V1.", diagnostics);+ }++ if (!TryUnwrapTranslation(subtract.Left, out var leftNode, out var boxTranslation))+ {+ return Fail(CirBoxCylinderRecognitionReason.UnsupportedTransform, "Subtract left operand has unsupported transform wrapper.", diagnostics);+ }++ if (!TryUnwrapTranslation(subtract.Right, out var rightNode, out var cylinderTranslation))+ {+ return Fail(CirBoxCylinderRecognitionReason.UnsupportedTransform, "Subtract right operand has unsupported transform wrapper.", diagnostics);+ }++ if (leftNode is not CirBoxNode box)+ {+ return Fail(CirBoxCylinderRecognitionReason.UnsupportedLeftNotBox, "Subtract left operand must normalize to CirBoxNode.", diagnostics);+ }++ if (rightNode is not CirCylinderNode cylinder)+ {+ return Fail(CirBoxCylinderRecognitionReason.UnsupportedRightNotCylinder, "Subtract right operand must normalize to CirCylinderNode.", diagnostics);+ }++ if (box.Width <= 0d || box.Height <= 0d || box.Depth <= 0d || !double.IsFinite(box.Width) || !double.IsFinite(box.Height) || !double.IsFinite(box.Depth))+ {+ return Fail(CirBoxCylinderRecognitionReason.InvalidBoxDimensions, "Box dimensions must be finite positive values.", diagnostics);+ }++ if (cylinder.Radius <= 0d || cylinder.Height <= 0d || !double.IsFinite(cylinder.Radius) || !double.IsFinite(cylinder.Height))+ {+ return Fail(CirBoxCylinderRecognitionReason.InvalidCylinderDimensions, "Cylinder dimensions must be finite positive values.", diagnostics);+ }++ var boxMinZ = boxTranslation.Z - (box.Depth * 0.5d);+ var boxMaxZ = boxTranslation.Z + (box.Depth * 0.5d);+ var cylinderMinZ = cylinderTranslation.Z - (cylinder.Height * 0.5d);+ var cylinderMaxZ = cylinderTranslation.Z + (cylinder.Height * 0.5d);+ if (cylinderMinZ > boxMinZ + tol || cylinderMaxZ < boxMaxZ - tol)+ {+ return Fail(CirBoxCylinderRecognitionReason.UnsupportedNotThroughHole, "Cylinder does not span full box depth.", diagnostics);+ }++ var halfW = box.Width * 0.5d;+ var halfH = box.Height * 0.5d;+ var dx = cylinderTranslation.X - boxTranslation.X;+ var dy = cylinderTranslation.Y - boxTranslation.Y;++ var clearanceXMinus = dx + halfW - cylinder.Radius;+ var clearanceXPlus = halfW - dx - cylinder.Radius;+ var clearanceYMinus = dy + halfH - cylinder.Radius;+ var clearanceYPlus = halfH - dy - cylinder.Radius;++ if (clearanceXMinus < -tol || clearanceXPlus < -tol || clearanceYMinus < -tol || clearanceYPlus < -tol)+ {+ return Fail(CirBoxCylinderRecognitionReason.UnsupportedCylinderOutsideBox, "Cylinder footprint extends outside box XY extents.", diagnostics);+ }++ if (clearanceXMinus <= tol || clearanceXPlus <= tol || clearanceYMinus <= tol || clearanceYPlus <= tol)+ {+ return Fail(CirBoxCylinderRecognitionReason.UnsupportedTangentOrGrazing, "Cylinder is tangent/grazing within tolerance and unsupported.", diagnostics);+ }++ EnrichReplayDiagnostics(input.ReplayLog, diagnostics, out var mismatch);++ var value = new RecognizedBoxCylinder(+ box.Width,+ box.Height,+ box.Depth,+ cylinder.Radius,+ cylinder.Height,+ boxTranslation,+ cylinderTranslation,+ CirBoxCylinderAxisKind.Z,+ cylinder.Height + (cylinderTranslation.Z - boxTranslation.Z),+ clearanceXMinus,+ clearanceXPlus,+ clearanceYMinus,+ clearanceYPlus);++ return new(true, mismatch ? CirBoxCylinderRecognitionReason.ReplayMismatch : CirBoxCylinderRecognitionReason.Recognized, mismatch ? "Recognized from CIR geometry with replay mismatch diagnostics." : "Recognized canonical subtract(box,cylinder) through-hole.", value, diagnostics);+ }++ private static void EnrichReplayDiagnostics(NativeGeometryReplayLog? replayLog, List<string> diagnostics, out bool mismatch)+ {+ mismatch = false;+ if (replayLog is null)+ {+ diagnostics.Add("Replay log unavailable; geometry-only recognition executed.");+ return;+ }++ var subtractOps = replayLog.Operations.Where(op => string.Equals(op.OperationKind, "boolean:subtract", StringComparison.Ordinal)).ToArray();+ if (subtractOps.Length == 0)+ {+ diagnostics.Add("Replay log contains no boolean:subtract operation.");+ mismatch = true;+ return;+ }++ var cylinderSubtract = subtractOps.FirstOrDefault(op => string.Equals(op.ToolKind, "cylinder", StringComparison.Ordinal));+ if (cylinderSubtract is null)+ {+ diagnostics.Add("Replay log subtract operations did not identify a cylinder tool kind.");+ mismatch = true;+ return;+ }++ diagnostics.Add($"Replay context: opIndex={cylinderSubtract.OpIndex}, feature='{cylinderSubtract.FeatureId}', source='{cylinderSubtract.SourceFeatureId}', toolKind='{cylinderSubtract.ToolKind}'.");+ }++ private static bool TryUnwrapTranslation(CirNode node, out CirNode unwrapped, out Vector3D translation)+ {+ unwrapped = node;+ translation = Vector3D.Zero;+ while (unwrapped is CirTransformNode transformNode)+ {+ if (!TryExtractPureTranslation(transformNode.Transform, out var step))+ {+ unwrapped = node;+ translation = Vector3D.Zero;+ return false;+ }++ translation += step;+ unwrapped = transformNode.Child;+ }++ return true;+ }++ private static bool TryExtractPureTranslation(Transform3D transform, out Vector3D translation)+ {+ var origin = transform.Apply(Point3D.Origin);+ var x = transform.Apply(new Point3D(1d, 0d, 0d));+ var y = transform.Apply(new Point3D(0d, 1d, 0d));+ var z = transform.Apply(new Point3D(0d, 0d, 1d));+ const double eps = 1e-9d;+ if (!NearlyEqual(x - origin, new Vector3D(1d, 0d, 0d), eps)+ || !NearlyEqual(y - origin, new Vector3D(0d, 1d, 0d), eps)+ || !NearlyEqual(z - origin, new Vector3D(0d, 0d, 1d), eps))+ {+ translation = Vector3D.Zero;+ return false;+ }++ translation = origin - Point3D.Origin;+ return true;+ }++ private static bool NearlyEqual(Vector3D a, Vector3D b, double eps)+ => Math.Abs(a.X - b.X) <= eps && Math.Abs(a.Y - b.Y) <= eps && Math.Abs(a.Z - b.Z) <= eps;++ private static CirBoxCylinderRecognitionResult Fail(CirBoxCylinderRecognitionReason reason, string diagnostic, List<string> diagnostics)+ => new(false, reason, diagnostic, null, diagnostics);+}diff --git a/docs/cir-step-v1-box-cylinder-recognizer.md b/docs/cir-step-v1-box-cylinder-recognizer.mdnew file mode 100644index 00000000..c9c73102--- /dev/null+++ b/docs/cir-step-v1-box-cylinder-recognizer.md@@ -0,0 +1,56 @@+# CIR-STEP-V1 Box-Cylinder Recognizer++## Scope+Production recognizer for canonical CIR shape:+- `CirSubtractNode(Box, Cylinder)`+- optional identity/pure-translation wrappers (`CirTransformNode`) around operands.++This milestone does **not** build BRep, export STEP, or wire rematerializer behavior.++## Inputs+`CirBoxCylinderRecognizerInput`:+- required: `CirNode Root` (authoritative geometry)+- optional: `NativeGeometryReplayLog ReplayLog` for provenance diagnostics+- optional: `SourceLabel`++`NativeGeometryState`, lowering plans, and execution-result adapters are intentionally deferred to CIR-STEP-V2.++## Accepted shape+Accepted only when all are true:+1. root is subtract,+2. lhs normalizes to `CirBoxNode`, rhs normalizes to `CirCylinderNode`,+3. wrappers (if any) are identity/pure-translation only,+4. dimensions finite positive,+5. cylinder is canonical Z-axis (no rotation allowed),+6. cylinder spans full box depth (through-hole policy),+7. strict XY clearance interior to box (offset allowed).++## Rejection policy+Stable reason-coded rejects include:+- non-subtract root,+- lhs non-box / rhs non-cylinder,+- unsupported transforms,+- invalid dimensions,+- not-through hole,+- tangent/grazing,+- outside-box footprint,+- nested/composite booleans.++Tolerance uses `ToleranceContext.Default.Linear` and classifies near-boundary as unsupported conservatively.++## Replay policy+Replay is optional and diagnostic-only:+- recognition decisions are based on CIR node geometry,+- replay enriches diagnostics with op/feature/source/tool details,+- replay mismatch does not force success and does not override geometry,+- if geometry succeeds but replay contradicts tool kind, recognizer returns success with `ReplayMismatch` reason.++## Relationship to FrictionLab X3/X3.1/X4+This production recognizer directly implements lab findings:+- real lowered fixture shape includes transform wrappers,+- root CIR node is geometry authority,+- replay is optional provenance,+- state/plan/result adapters are v2 follow-up.++## Next step (CIR-STEP-V2)+Add adapter layer from execution/lowering artifacts into recognizer input and consume recognized normalized result in direct box-with-round-hole BRep builder path.