Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Get around codex bug for CIR lab report

Yuechen Li5aba4c0e3742
diff --git a/Aetheris.Firmament.FrictionLab/CIRLab/CIRBoxCylinderRecognitionLab.cs b/Aetheris.Firmament.FrictionLab/CIRLab/CIRBoxCylinderRecognitionLab.cs
new file mode 100644
index 00000000..b2009a29
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/CIRLab/CIRBoxCylinderRecognitionLab.cs
@@ -0,0 +1,120 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+
+namespace Aetheris.FrictionLab;
+
+public static class CirBoxCylinderRecognitionLab
+{
+ public static CirBoxCylinderRecognitionLabResult Recognize(CirNode root, bool allowTranslationWrappers = true, double? linearTolerance = null)
+ {
+ var tol = linearTolerance ?? ToleranceContext.Default.Linear;
+ if (!TryUnwrap(root, allowTranslationWrappers, out var subtractNode, out _, out var reason))
+ {
+ return Fail(reason, "Expected root subtract of box and cylinder.");
+ }
+ if (subtractNode is not CirSubtractNode subtract)
+ {
+ return Fail(CirLabRecognitionReason.RootNotSubtract, "Expected root subtract of box and cylinder.");
+ }
+
+ if (!TryUnwrap(subtract.Left, allowTranslationWrappers, out var leftNode, out var leftTranslation, out reason))
+ {
+ return Fail(reason, "Subtract lhs transform normalization failed.");
+ }
+
+ if (leftNode is not CirBoxNode box)
+ {
+ return Fail(CirLabRecognitionReason.BaseNotBox, "Subtract lhs must normalize to CirBoxNode.");
+ }
+
+ if (!TryUnwrap(subtract.Right, allowTranslationWrappers, out var rightNode, out var rightTranslation, out reason))
+ {
+ return Fail(reason, "Subtract rhs transform normalization failed.");
+ }
+
+ if (rightNode is not CirCylinderNode cylinder)
+ {
+ return Fail(CirLabRecognitionReason.ToolNotCylinder, "Subtract rhs must normalize to CirCylinderNode.");
+ }
+
+ if (box.Width <= 0d || box.Height <= 0d || box.Depth <= 0d || cylinder.Radius <= 0d || cylinder.Height <= 0d)
+ {
+ return Fail(CirLabRecognitionReason.InvalidDimensions, "All box/cylinder dimensions must be positive.");
+ }
+
+ var axis = "Z"; // native CirCylinderNode axis convention
+ var dz = rightTranslation.Z - leftTranslation.Z;
+ var through = cylinder.Height + (2d * tol) >= box.Depth &&
+ (rightTranslation.Z - (cylinder.Height * 0.5d)) <= (-box.Depth * 0.5d + leftTranslation.Z + tol) &&
+ (rightTranslation.Z + (cylinder.Height * 0.5d)) >= (box.Depth * 0.5d + leftTranslation.Z - tol);
+ if (!through)
+ {
+ return Fail(CirLabRecognitionReason.NotThrough, "Cylinder does not span full box depth.");
+ }
+
+ var dx = Math.Abs(rightTranslation.X - leftTranslation.X);
+ var dy = Math.Abs(rightTranslation.Y - leftTranslation.Y);
+ var maxX = (box.Width * 0.5d) - cylinder.Radius;
+ var maxY = (box.Height * 0.5d) - cylinder.Radius;
+ if (dx >= maxX - tol || dy >= maxY - tol)
+ {
+ return Fail(CirLabRecognitionReason.TangentOrOutside, "Cylinder is tangent/grazing/outside XY clearance envelope.");
+ }
+
+ return new(true, CirLabRecognitionReason.None, "Recognized canonical box-cylinder through-hole subtract.", box, leftTranslation, cylinder, rightTranslation, axis, dz + cylinder.Height, new CirSubtractNode(new CirTransformNode(box, Transform3D.CreateTranslation(leftTranslation)), new CirTransformNode(cylinder, Transform3D.CreateTranslation(rightTranslation))));
+ }
+
+ private static bool TryUnwrap(CirNode node, bool allowTranslationWrappers, out CirNode unwrapped, out Vector3D translation, out CirLabRecognitionReason reason)
+ {
+ unwrapped = node;
+ translation = Vector3D.Zero;
+ reason = CirLabRecognitionReason.None;
+
+ while (unwrapped is CirTransformNode t)
+ {
+ if (!allowTranslationWrappers || !TryExtractPureTranslation(t.Transform, out var step))
+ {
+ reason = CirLabRecognitionReason.UnsupportedTransform;
+ return false;
+ }
+
+ translation += step;
+ unwrapped = t.Child;
+ }
+
+ if (unwrapped is CirSubtractNode s)
+ {
+ reason = CirLabRecognitionReason.None;
+ unwrapped = s;
+ return true;
+ }
+
+ return true;
+ }
+
+ public static bool TryExtractPureTranslation(Transform3D transform, out Vector3D translation)
+ {
+ var o = 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));
+ var eps = 1e-9d;
+ if (!NearlyEqual(x - o, new Vector3D(1d, 0d, 0d), eps)
+ || !NearlyEqual(y - o, new Vector3D(0d, 1d, 0d), eps)
+ || !NearlyEqual(z - o, new Vector3D(0d, 0d, 1d), eps))
+ {
+ translation = Vector3D.Zero;
+ return false;
+ }
+
+ translation = o - 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 CirBoxCylinderRecognitionLabResult Fail(CirLabRecognitionReason reason, string diagnostic)
+ => new(false, reason, diagnostic, null, Vector3D.Zero, null, Vector3D.Zero, null, 0d, null);
+}
diff --git a/Aetheris.Firmament.FrictionLab/CIRLab/CIRBoxCylinderRecognitionLabResult.cs b/Aetheris.Firmament.FrictionLab/CIRLab/CIRBoxCylinderRecognitionLabResult.cs
new file mode 100644
index 00000000..3c4e1553
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/CIRLab/CIRBoxCylinderRecognitionLabResult.cs
@@ -0,0 +1,16 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.FrictionLab;
+
+public sealed record CirBoxCylinderRecognitionLabResult(
+ bool Success,
+ CirLabRecognitionReason Reason,
+ string Diagnostic,
+ CirBoxNode? Box,
+ Vector3D BoxTranslation,
+ CirCylinderNode? Cylinder,
+ Vector3D CylinderTranslation,
+ string? Axis,
+ double ThroughLength,
+ CirNode? NormalizedRoot);
diff --git a/Aetheris.Firmament.FrictionLab/CIRLab/CIRLabDiagnostics.cs b/Aetheris.Firmament.FrictionLab/CIRLab/CIRLabDiagnostics.cs
new file mode 100644
index 00000000..09574a08
--- /dev/null
+++ b/Aetheris.Firmament.FrictionLab/CIRLab/CIRLabDiagnostics.cs
@@ -0,0 +1,14 @@
+namespace Aetheris.FrictionLab;
+
+public enum CirLabRecognitionReason
+{
+ None,
+ RootNotSubtract,
+ BaseNotBox,
+ ToolNotCylinder,
+ UnsupportedTransform,
+ UnsupportedAxis,
+ NotThrough,
+ TangentOrOutside,
+ InvalidDimensions
+}
diff --git a/Aetheris.FrictionLab.Tests/CIRLab/CirBoxCylinderConventionLabTests.cs b/Aetheris.FrictionLab.Tests/CIRLab/CirBoxCylinderConventionLabTests.cs
new file mode 100644
index 00000000..052aca29
--- /dev/null
+++ b/Aetheris.FrictionLab.Tests/CIRLab/CirBoxCylinderConventionLabTests.cs
@@ -0,0 +1,26 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.FrictionLab.Tests.CIRLab;
+
+public sealed class CirBoxCylinderConventionLabTests
+{
+ [Fact]
+ public void Box_IsCenteredOnOrigin_WithHalfExtents()
+ {
+ var box = new CirBoxNode(10d, 6d, 4d);
+ Assert.Equal(new Point3D(-5d, -3d, -2d), box.Bounds.Min);
+ Assert.Equal(new Point3D(5d, 3d, 2d), box.Bounds.Max);
+ Assert.True(box.Evaluate(Point3D.Origin) < 0d);
+ }
+
+ [Fact]
+ public void Cylinder_IsZAxisCenteredOnOrigin_WithHalfHeightExtents()
+ {
+ var cylinder = new CirCylinderNode(3d, 8d);
+ Assert.Equal(new Point3D(-3d, -3d, -4d), cylinder.Bounds.Min);
+ Assert.Equal(new Point3D(3d, 3d, 4d), cylinder.Bounds.Max);
+ Assert.True(cylinder.Evaluate(new Point3D(0d, 0d, 3d)) < 0d);
+ Assert.True(cylinder.Evaluate(new Point3D(3.1d, 0d, 0d)) > 0d);
+ }
+}
diff --git a/Aetheris.FrictionLab.Tests/CIRLab/CirBoxCylinderRecognitionLabTests.cs b/Aetheris.FrictionLab.Tests/CIRLab/CirBoxCylinderRecognitionLabTests.cs
new file mode 100644
index 00000000..efbed0d8
--- /dev/null
+++ b/Aetheris.FrictionLab.Tests/CIRLab/CirBoxCylinderRecognitionLabTests.cs
@@ -0,0 +1,37 @@
+using Aetheris.FrictionLab;
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.FrictionLab.Tests.CIRLab;
+
+public sealed class CirBoxCylinderRecognitionLabTests
+{
+ [Fact]
+ public void Recognizes_DirectCanonicalSubtract()
+ {
+ var root = new CirSubtractNode(new CirBoxNode(10d, 8d, 6d), new CirCylinderNode(2d, 8d));
+ var result = CirBoxCylinderRecognitionLab.Recognize(root);
+ Assert.True(result.Success);
+ Assert.Equal("Z", result.Axis);
+ }
+
+ [Fact]
+ public void Recognizes_TranslatedOperands()
+ {
+ var box = new CirTransformNode(new CirBoxNode(10d, 8d, 6d), Transform3D.CreateTranslation(new Vector3D(2d, 1d, 5d)));
+ var cyl = new CirTransformNode(new CirCylinderNode(2d, 8d), Transform3D.CreateTranslation(new Vector3D(2.5d, 1.5d, 5d)));
+ var root = new CirSubtractNode(box, cyl);
+ var result = CirBoxCylinderRecognitionLab.Recognize(root);
+ Assert.True(result.Success);
+ }
+
+ [Fact]
+ public void Rejects_NonTranslationTransform()
+ {
+ var box = new CirTransformNode(new CirBoxNode(10d, 8d, 6d), Transform3D.CreateRotationX(Math.PI / 4d));
+ var root = new CirSubtractNode(box, new CirCylinderNode(2d, 8d));
+ var result = CirBoxCylinderRecognitionLab.Recognize(root);
+ Assert.False(result.Success);
+ Assert.Equal(CirLabRecognitionReason.UnsupportedTransform, result.Reason);
+ }
+}
diff --git a/Aetheris.FrictionLab.Tests/CIRLab/CirBoxCylinderUnsupportedCasesLabTests.cs b/Aetheris.FrictionLab.Tests/CIRLab/CirBoxCylinderUnsupportedCasesLabTests.cs
new file mode 100644
index 00000000..6a008401
--- /dev/null
+++ b/Aetheris.FrictionLab.Tests/CIRLab/CirBoxCylinderUnsupportedCasesLabTests.cs
@@ -0,0 +1,27 @@
+using Aetheris.FrictionLab;
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.FrictionLab.Tests.CIRLab;
+
+public sealed class CirBoxCylinderUnsupportedCasesLabTests
+{
+ [Theory]
+ [MemberData(nameof(Cases))]
+ public void Rejects_Unsupported(CirNode root, CirLabRecognitionReason expected)
+ {
+ var result = CirBoxCylinderRecognitionLab.Recognize(root);
+ Assert.False(result.Success);
+ Assert.Equal(expected, result.Reason);
+ }
+
+ public static IEnumerable<object[]> Cases()
+ {
+ yield return [new CirUnionNode(new CirBoxNode(10d, 8d, 6d), new CirCylinderNode(2d, 8d)), CirLabRecognitionReason.RootNotSubtract];
+ yield return [new CirSubtractNode(new CirSphereNode(3d), new CirCylinderNode(2d, 8d)), CirLabRecognitionReason.BaseNotBox];
+ yield return [new CirSubtractNode(new CirBoxNode(10d, 8d, 6d), new CirSphereNode(2d)), CirLabRecognitionReason.ToolNotCylinder];
+ yield return [new CirSubtractNode(new CirBoxNode(10d, 8d, 6d), new CirCylinderNode(2d, 4d)), CirLabRecognitionReason.NotThrough];
+ yield return [new CirSubtractNode(new CirBoxNode(10d, 8d, 6d), new CirTransformNode(new CirCylinderNode(2d, 8d), Transform3D.CreateTranslation(new Vector3D(3d, 0d, 0d)))), CirLabRecognitionReason.TangentOrOutside];
+ yield return [new CirSubtractNode(new CirBoxNode(10d, 8d, 6d), new CirTransformNode(new CirCylinderNode(2d, 8d), Transform3D.CreateTranslation(new Vector3D(7d, 0d, 0d)))), CirLabRecognitionReason.TangentOrOutside];
+ }
+}
diff --git a/Aetheris.FrictionLab.Tests/CIRLab/Reports/cir-brep-x3-box-cylinder-recognition-lab.md b/Aetheris.FrictionLab.Tests/CIRLab/Reports/cir-brep-x3-box-cylinder-recognition-lab.md
new file mode 100644
index 00000000..cb02f76e
--- /dev/null
+++ b/Aetheris.FrictionLab.Tests/CIRLab/Reports/cir-brep-x3-box-cylinder-recognition-lab.md
@@ -0,0 +1,110 @@
+# CIR-BREP-X3 — FrictionLab canonical box-cylinder recognition experiments
+
+## Scope
+Lab-only experiments in `Aetheris.Firmament.FrictionLab/CIRLab` and `Aetheris.FrictionLab.Tests/CIRLab`.
+
+## 1) Exact CIR shape
+- Hypothesis: recognize `CirSubtractNode(CirBoxNode, CirCylinderNode)` with optional pure translations.
+- Experiments: direct node + translated wrappers tests.
+- Evidence: direct and translated cases pass; non-subtract rejected.
+- Conclusion: first production recognizer should require subtract(box,cylinder) after optional translation-unwrapping.
+- Recommendation: accept only identity/pure-translation wrappers in v1.
+- Confidence: High.
+
+## 2) Box/Cylinder coordinate conventions
+- Experiments: bounds/evaluate assertions.
+- Evidence: box centered at origin with half extents; cylinder centered at origin, Z-axis, half-height in ±Z.
+- Conclusion: CIR primitive conventions are origin-centered signed-distance primitives.
+- Recommendation: normalize around these conventions, then apply extracted translations.
+- Confidence: High.
+
+## 3) Through-hole requirement
+- Experiments: short cylinder rejection, spanning cylinder acceptance.
+- Evidence: height/depth and end-cap coverage checks separate through vs blind.
+- Conclusion: v1 should require full through depth with tolerance band.
+- Recommendation: reject blind/partial/miss.
+- Confidence: High.
+
+## 4) Allowed axes
+- Evidence: `CirCylinderNode` encodes only canonical Z axis; no intrinsic arbitrary-axis field.
+- Conclusion: axis variation must come from transforms.
+- Recommendation: v1 supports only native Z-axis cases (plus translation).
+- Confidence: High.
+
+## 5) Transforms
+- Experiments: pure translation vs rotation wrappers.
+- Evidence: translation unwrap is safe; rotation wrapper rejected.
+- Conclusion: detect pure translation by transformed basis vectors.
+- Recommendation: reject rotation/nonuniform/shear in v1 with explicit reason.
+- Confidence: High.
+
+## 6) Firmament lowering shape for `boolean_box_cylinder_hole`
+- Evidence (source inspection): lowerer always emits primitive local-frame + placement via `CirTransformNode`, then boolean `CirSubtractNode`.
+- Conclusion: real path is frequently subtract of transformed operands, not always literal raw primitives.
+- Recommendation: recognizer should include wrapper normalization.
+- Confidence: Medium-High.
+
+## 7) Recognition entrypoint
+- Evidence: CIR node tree has enough for canonical v1 (shape + transforms + dimensions).
+- Conclusion: node-first recognizer is sufficient for first scope.
+- Recommendation: implement node recognizer first; add plan/replay adapter only if needed.
+- Confidence: Medium.
+
+## 8) What counts as box
+- Evidence: accepted only `CirBoxNode`; non-box lhs rejected in tests.
+- Recommendation: strict `CirBoxNode` for v1.
+- Confidence: High.
+
+## 9) What counts as cylinder
+- Evidence: accepted only `CirCylinderNode`; sphere tool rejected.
+- Recommendation: strict finite circular `CirCylinderNode` only.
+- Confidence: High.
+
+## 10) Hole position constraints
+- Experiments: centered, offset-valid, tangent, outside.
+- Evidence: strict interior clearance inequalities reject tangent/grazing/outside.
+- Recommendation: allow offsets when strict clearance holds; do not force centered-only.
+- Confidence: High.
+
+## 11) Tolerances
+- Evidence: experiments use `ToleranceContext.Default.Linear` from kernel numerics.
+- Recommendation: use shared tolerance context; classify near-boundary as tangent/unsupported conservatively.
+- Confidence: High.
+
+## 12) Recognizer return shape
+- Evidence: lab result record carries success/reason/diagnostic, normalized primitives+translations, axis, through-length.
+- Recommendation: production result should be structured, not bool.
+- Confidence: High.
+
+## 13) Recognition vs builder coupling
+- Evidence: lab recognizes and returns normalized parameters without building BRep.
+- Conclusion: separation is practical.
+- Recommendation: recognizer returns normalized params; builder consumes them.
+- Confidence: High.
+
+## 14) Unsupported variants behavior
+- Evidence: unsupported test matrix exercises stable reason codes.
+- Recommendation: no fallback/guess; return explicit unsupported reason vocabulary.
+- Confidence: High.
+
+## 15) Production test needs
+- Recommendation matrix:
+ - success: direct subtract, translated subtract
+ - rejects: non-subtract, lhs non-box, rhs non-cylinder, unsupported transform, blind/not-through, tangent/outside
+ - tolerances: near-boundary around clearance threshold
+- Confidence: High.
+
+## Recommended production recognizer policy
+Recognize only canonical `subtract(box,cylinder)` after unwrapping identity/pure-translation transforms; require positive dimensions, Z-axis cylinder convention, strict through-hole depth coverage, and strict XY interior clearance with shared tolerance.
+
+## Recommended production recognizer result shape
+`Success`, `ReasonCode`, `Diagnostic`, normalized `Box` dimensions, normalized `Cylinder` radius/height, `BoxTranslation`, `CylinderTranslation`, `Axis`, `ThroughLength`, optional source-node references.
+
+## Recommended production test matrix
+Copy/adapt all CIRLab tests under `Aetheris.FrictionLab.Tests/CIRLab` into production recognizer suite once production implementation starts.
+
+## Known deferred cases
+- Rotated cylinders/boxes.
+- Nonuniform-scaled/sheared transforms.
+- Lowering-plan/native replay metadata adapters.
+- Multi-hole/composite boolean chains.