Skip to content

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.cs
new file mode 100644
index 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.cs
new file mode 100644
index 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.md
new file mode 100644
index 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.