Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR-M0 constructive IR proof-of-concept

Yuechen Li40b521aeb45f
diff --git a/Aetheris.Kernel.Core.Tests/Cir/CirEvaluationTests.cs b/Aetheris.Kernel.Core.Tests/Cir/CirEvaluationTests.cs
new file mode 100644
index 00000000..ab166641
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Cir/CirEvaluationTests.cs
@@ -0,0 +1,64 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Tests.Cir;
+
+public sealed class CirEvaluationTests
+{
+ [Fact]
+ public void CIR_Box_EvaluatePoints()
+ {
+ var box = new CirBoxNode(10d, 8d, 6d);
+
+ Assert.True(box.Evaluate(new Point3D(0d, 0d, 0d)) < 0d);
+ Assert.True(box.Evaluate(new Point3D(6d, 0d, 0d)) > 0d);
+ Assert.Equal(0d, box.Evaluate(new Point3D(5d, 0d, 0d)), 6);
+ }
+
+ [Fact]
+ public void CIR_Cylinder_EvaluatePoints()
+ {
+ var cylinder = new CirCylinderNode(3d, 10d);
+
+ Assert.True(cylinder.Evaluate(new Point3D(1d, 1d, 0d)) < 0d);
+ Assert.True(cylinder.Evaluate(new Point3D(4d, 0d, 0d)) > 0d);
+ Assert.Equal(0d, cylinder.Evaluate(new Point3D(3d, 0d, 0d)), 6);
+ }
+
+ [Fact]
+ public void CIR_BoxMinusCylinder_EvaluatePoints()
+ {
+ var box = new CirBoxNode(20d, 20d, 20d);
+ var cylinder = new CirCylinderNode(3d, 24d);
+ var cut = new CirSubtractNode(box, cylinder);
+
+ Assert.True(cut.Evaluate(new Point3D(8d, 0d, 0d)) < 0d);
+ Assert.True(cut.Evaluate(new Point3D(0d, 0d, 0d)) > 0d);
+ Assert.True(cut.Evaluate(new Point3D(12d, 0d, 0d)) > 0d);
+ Assert.True(double.Abs(cut.Evaluate(new Point3D(3d, 0d, 0d))) < 1e-6);
+ }
+
+ [Fact]
+ public void CIR_BoxMinusCylinder_ApproximateVolume_IsReasonable()
+ {
+ var box = new CirBoxNode(20d, 20d, 20d);
+ var cylinder = new CirCylinderNode(3d, 24d);
+ var cut = new CirSubtractNode(box, cylinder);
+
+ var boxEstimate = CirVolumeEstimator.EstimateVolume(box, resolution: 40);
+ var cutEstimate = CirVolumeEstimator.EstimateVolume(cut, resolution: 40);
+
+ var expectedBox = 20d * 20d * 20d;
+ var expectedCut = expectedBox - (double.Pi * 3d * 3d * 20d);
+
+ Assert.InRange(boxEstimate, expectedBox * 0.97d, expectedBox * 1.03d);
+ Assert.InRange(cutEstimate, expectedCut * 0.94d, expectedCut * 1.06d);
+ }
+
+ [Fact]
+ public void CIR_DoesNotAffectExistingBRepPath()
+ {
+ var box = Aetheris.Kernel.Core.Brep.BrepPrimitives.CreateBox(10d, 10d, 10d);
+ Assert.True(box.IsSuccess);
+ }
+}
diff --git a/Aetheris.Kernel.Core/Cir/CirNode.cs b/Aetheris.Kernel.Core/Cir/CirNode.cs
new file mode 100644
index 00000000..3e75afdf
--- /dev/null
+++ b/Aetheris.Kernel.Core/Cir/CirNode.cs
@@ -0,0 +1,33 @@
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Cir;
+
+internal enum CirNodeKind
+{
+ Box,
+ Cylinder,
+ Sphere,
+ Union,
+ Subtract,
+ Intersect,
+ Transform,
+}
+
+internal readonly record struct CirBounds(Point3D Min, Point3D Max)
+{
+ public double SizeX => Max.X - Min.X;
+ public double SizeY => Max.Y - Min.Y;
+ public double SizeZ => Max.Z - Min.Z;
+
+ public static CirBounds Union(CirBounds left, CirBounds right) =>
+ new(
+ new Point3D(double.Min(left.Min.X, right.Min.X), double.Min(left.Min.Y, right.Min.Y), double.Min(left.Min.Z, right.Min.Z)),
+ new Point3D(double.Max(left.Max.X, right.Max.X), double.Max(left.Max.Y, right.Max.Y), double.Max(left.Max.Z, right.Max.Z)));
+}
+
+internal abstract record CirNode(CirNodeKind Kind)
+{
+ public abstract CirBounds Bounds { get; }
+
+ public abstract double Evaluate(Point3D point);
+}
diff --git a/Aetheris.Kernel.Core/Cir/CirNodes.cs b/Aetheris.Kernel.Core/Cir/CirNodes.cs
new file mode 100644
index 00000000..3da68cc5
--- /dev/null
+++ b/Aetheris.Kernel.Core/Cir/CirNodes.cs
@@ -0,0 +1,128 @@
+using System.Linq;
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Cir;
+
+internal sealed record CirBoxNode(double Width, double Height, double Depth) : CirNode(CirNodeKind.Box)
+{
+ public override CirBounds Bounds => new(new Point3D(-Width * 0.5d, -Height * 0.5d, -Depth * 0.5d), new Point3D(Width * 0.5d, Height * 0.5d, Depth * 0.5d));
+
+ public override double Evaluate(Point3D point)
+ {
+ var hx = Width * 0.5d;
+ var hy = Height * 0.5d;
+ var hz = Depth * 0.5d;
+ var dx = double.Abs(point.X) - hx;
+ var dy = double.Abs(point.Y) - hy;
+ var dz = double.Abs(point.Z) - hz;
+ var outsideX = double.Max(dx, 0d);
+ var outsideY = double.Max(dy, 0d);
+ var outsideZ = double.Max(dz, 0d);
+ var outside = double.Sqrt((outsideX * outsideX) + (outsideY * outsideY) + (outsideZ * outsideZ));
+ var inside = double.Min(double.Max(dx, double.Max(dy, dz)), 0d);
+ return outside + inside;
+ }
+}
+
+internal sealed record CirCylinderNode(double Radius, double Height) : CirNode(CirNodeKind.Cylinder)
+{
+ public override CirBounds Bounds => new(new Point3D(-Radius, -Radius, -Height * 0.5d), new Point3D(Radius, Radius, Height * 0.5d));
+
+ public override double Evaluate(Point3D point)
+ {
+ var radial = double.Sqrt((point.X * point.X) + (point.Y * point.Y));
+ var dr = radial - Radius;
+ var dz = double.Abs(point.Z) - (Height * 0.5d);
+ var outsideR = double.Max(dr, 0d);
+ var outsideZ = double.Max(dz, 0d);
+ var outside = double.Sqrt((outsideR * outsideR) + (outsideZ * outsideZ));
+ var inside = double.Min(double.Max(dr, dz), 0d);
+ return outside + inside;
+ }
+}
+
+internal sealed record CirSphereNode(double Radius) : CirNode(CirNodeKind.Sphere)
+{
+ public override CirBounds Bounds => new(new Point3D(-Radius, -Radius, -Radius), new Point3D(Radius, Radius, Radius));
+
+ public override double Evaluate(Point3D point) => double.Sqrt((point.X * point.X) + (point.Y * point.Y) + (point.Z * point.Z)) - Radius;
+}
+
+internal sealed record CirUnionNode(CirNode Left, CirNode Right) : CirNode(CirNodeKind.Union)
+{
+ public override CirBounds Bounds => CirBounds.Union(Left.Bounds, Right.Bounds);
+ public override double Evaluate(Point3D point) => double.Min(Left.Evaluate(point), Right.Evaluate(point));
+}
+
+internal sealed record CirSubtractNode(CirNode Left, CirNode Right) : CirNode(CirNodeKind.Subtract)
+{
+ public override CirBounds Bounds => Left.Bounds;
+ public override double Evaluate(Point3D point) => double.Max(Left.Evaluate(point), -Right.Evaluate(point));
+}
+
+internal sealed record CirIntersectNode(CirNode Left, CirNode Right) : CirNode(CirNodeKind.Intersect)
+{
+ public override CirBounds Bounds => CirBounds.Union(Left.Bounds, Right.Bounds);
+ public override double Evaluate(Point3D point) => double.Max(Left.Evaluate(point), Right.Evaluate(point));
+}
+
+internal sealed record CirTransformNode(CirNode Child, Transform3D Transform) : CirNode(CirNodeKind.Transform)
+{
+ public override CirBounds Bounds
+ {
+ get
+ {
+ var b = Child.Bounds;
+ var corners = new[]
+ {
+ new Point3D(b.Min.X, b.Min.Y, b.Min.Z),
+ new Point3D(b.Min.X, b.Min.Y, b.Max.Z),
+ new Point3D(b.Min.X, b.Max.Y, b.Min.Z),
+ new Point3D(b.Min.X, b.Max.Y, b.Max.Z),
+ new Point3D(b.Max.X, b.Min.Y, b.Min.Z),
+ new Point3D(b.Max.X, b.Min.Y, b.Max.Z),
+ new Point3D(b.Max.X, b.Max.Y, b.Min.Z),
+ new Point3D(b.Max.X, b.Max.Y, b.Max.Z),
+ };
+
+ var transformed = corners.Select(TransformPoint).ToArray();
+ return new CirBounds(
+ new Point3D(transformed.Min(p => p.X), transformed.Min(p => p.Y), transformed.Min(p => p.Z)),
+ new Point3D(transformed.Max(p => p.X), transformed.Max(p => p.Y), transformed.Max(p => p.Z)));
+ }
+ }
+
+ public override double Evaluate(Point3D point)
+ {
+ var inverse = Transform.Inverse();
+ return Child.Evaluate(inverse.Apply(point));
+ }
+
+ private Point3D TransformPoint(Point3D p) => Transform.Apply(p);
+}
+
+internal static class CirVolumeEstimator
+{
+ public static double EstimateVolume(CirNode node, int resolution)
+ {
+ var bounds = node.Bounds;
+ var dx = bounds.SizeX / resolution;
+ var dy = bounds.SizeY / resolution;
+ var dz = bounds.SizeZ / resolution;
+ var cellVolume = dx * dy * dz;
+ var insideCount = 0;
+
+ for (var ix = 0; ix < resolution; ix++)
+ for (var iy = 0; iy < resolution; iy++)
+ for (var iz = 0; iz < resolution; iz++)
+ {
+ var p = new Point3D(bounds.Min.X + ((ix + 0.5d) * dx), bounds.Min.Y + ((iy + 0.5d) * dy), bounds.Min.Z + ((iz + 0.5d) * dz));
+ if (node.Evaluate(p) <= 0d)
+ {
+ insideCount++;
+ }
+ }
+
+ return insideCount * cellVolume;
+ }
+}
diff --git a/docs/cir-m0-design.md b/docs/cir-m0-design.md
new file mode 100644
index 00000000..0bc8d06a
--- /dev/null
+++ b/docs/cir-m0-design.md
@@ -0,0 +1,55 @@
+# CIR-M0: Constructive Intermediate Representation (Design + POC)
+
+## 1) What CIR is
+
+CIR is a typed constructive geometry MIR for Aetheris: an internal geometry tree composed of primitive and CSG nodes that can be evaluated lazily for analysis without first materializing full BRep topology.
+
+## 2) What CIR is not
+
+CIR is not:
+- Firmament source syntax,
+- STEP or any interchange format,
+- a direct replacement for BRep topology,
+- a stable public authoring API.
+
+## 3) Relationship to Firmament
+
+Firmament currently parses and lowers to primitive/boolean execution plans. CIR would fit between parsed model and backend execution as a canonical internal geometry MIR (`Firmament -> AST/ParsedModel -> CIR -> backend`).
+
+## 4) Relationship to Forge
+
+Forge and StandardLibrary shape generators can eventually emit CIR subtrees when a path only needs geometric analysis (containment/volume/map/section) before committing to topology materialization.
+
+## 5) Relationship to BRep
+
+BRep remains the authoritative materialized solid backend for existing production flows. CIR is currently side-by-side and does not replace or mutate existing BRep execution.
+
+## 6) Relationship to Boolean engine
+
+In CIR, boolean operations are cheap tree composition (`Union/Subtract/Intersect`) via implicit-field composition rules. This allows direct evaluators to run without immediate BRep reconstruction.
+
+## 7) Relationship to analyzer tools
+
+Point containment and approximate volume can evaluate directly from CIR node `Evaluate(point)` over node bounds. This POC includes deterministic grid-sampled volume estimation that bypasses BRep containment.
+
+## 8) Risks / blockers
+
+- **Materialization complexity:** reliable CIR->BRep extraction for broad geometry/trimmed surfaces remains a major follow-up.
+- **Signed distance semantics:** CSG `min/max` composition yields a signed implicit field, but not guaranteed exact SDF everywhere.
+- **Dual-kernel risk:** introducing CIR plus BRep risks duplicated semantics unless one path becomes canonical with bounded adapters.
+- **PMI intent continuity:** semantic/manufacturing intent currently hangs off feature/operation flows, not CIR nodes; traceability policy is needed.
+- **Migration strategy:** rolling in CIR incrementally needs strict scope boundaries so production path behavior remains stable.
+
+## 9) Recommended CIR-M1
+
+1. Add an **experimental Firmament->CIR lowerer** for bounded ops (`box`, `cylinder`, `subtract`, optional `translate`).
+2. Add a CIR analyzer API for containment + coarse volume with reproducible tolerances.
+3. Add a bounded CIR->BRep adapter only for already-supported safe subset (`box`, `cylinder`, `box-cylinder subtract`) and compare outputs to existing BRep boolean results.
+4. Define node-level metadata hooks for preserving feature identity/intent lineage.
+
+## POC status summary
+
+- Implemented CIR node kinds: `Box`, `Cylinder`, `Sphere`, `Union`, `Subtract`, `Intersect`, `Transform`.
+- Implemented node bounds + point evaluate + deterministic grid volume estimator.
+- Prototype does **not** implement CIR->BRep extraction or STEP export.
+- Existing production Firmament/BRep flow is unchanged.