Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Implement CIR-E2 self-contained tape transform flattening

Yuechen Li97bee4e326d1
diff --git a/Aetheris.Kernel.Core.Tests/Cir/CirTapeEvaluationTests.cs b/Aetheris.Kernel.Core.Tests/Cir/CirTapeEvaluationTests.cs
index bc94abb3..73aa2c6a 100644
--- a/Aetheris.Kernel.Core.Tests/Cir/CirTapeEvaluationTests.cs
+++ b/Aetheris.Kernel.Core.Tests/Cir/CirTapeEvaluationTests.cs
@@ -7,47 +7,60 @@ namespace Aetheris.Kernel.Core.Tests.Cir;
public sealed class CirTapeEvaluationTests
{
[Fact]
- public void Tape_Box_MatchesRecursiveEvaluate()
+ public void Tape_Transform_NoRecursiveChildEvaluation()
{
- var node = new CirBoxNode(10d, 8d, 6d);
- AssertTapeMatches(node, new Point3D(0d, 0d, 0d), new Point3D(6d, 0d, 0d), new Point3D(5d, 0d, 0d));
- }
+ var node = new CirTransformNode(new CirBoxNode(4d, 2d, 6d), Transform3D.CreateTranslation(new Vector3D(2d, -1d, 3d)));
+ var tape = CirTapeLowerer.Lower(node);
- [Fact]
- public void Tape_Cylinder_MatchesRecursiveEvaluate()
- {
- var node = new CirCylinderNode(3d, 10d);
- AssertTapeMatches(node, new Point3D(1d, 1d, 0d), new Point3D(4d, 0d, 0d), new Point3D(3d, 0d, 0d));
+ Assert.DoesNotContain(tape.Instructions, i => i.SourceKind == CirNodeKind.Transform);
+ Assert.All(tape.BoxPayloads, payload => Assert.NotEqual(Transform3D.Identity, payload.InverseTransform));
}
[Fact]
- public void Tape_Sphere_MatchesRecursiveEvaluate()
+ public void Tape_Transform_MatchesRecursiveEvaluate()
{
- var node = new CirSphereNode(5d);
- AssertTapeMatches(node, new Point3D(0d, 0d, 0d), new Point3D(6d, 0d, 0d), new Point3D(5d, 0d, 0d));
+ var transform = Transform3D.CreateTranslation(new Vector3D(2d, -1d, 3d)) * Transform3D.CreateRotationZ(double.Pi / 6d);
+ var node = new CirTransformNode(new CirBoxNode(4d, 2d, 6d), transform);
+ AssertTapeMatches(node, new Point3D(2d, -1d, 3d), new Point3D(7d, -1d, 3d), new Point3D(4d, 0d, 3d));
}
[Fact]
- public void Tape_BoxMinusCylinder_MatchesRecursiveEvaluate()
+ public void Tape_NestedTransform_MatchesRecursiveEvaluate()
{
- var node = new CirSubtractNode(new CirBoxNode(20d, 20d, 20d), new CirCylinderNode(3d, 24d));
- AssertTapeMatches(node, new Point3D(8d, 0d, 0d), new Point3D(0d, 0d, 0d), new Point3D(3d, 0d, 0d));
+ var node = new CirTransformNode(
+ new CirTransformNode(
+ new CirSphereNode(2.5d),
+ Transform3D.CreateRotationY(double.Pi / 4d) * Transform3D.CreateTranslation(new Vector3D(0.5d, 0d, 1d))),
+ Transform3D.CreateTranslation(new Vector3D(3d, -1d, 2d)) * Transform3D.CreateRotationX(double.Pi / 3d));
+
+ AssertTapeMatches(node, new Point3D(3d, -1d, 2d), new Point3D(4.5d, -0.5d, 2.25d), new Point3D(0d, 0d, 0d));
}
[Fact]
- public void Tape_UnionIntersect_MatchesRecursiveEvaluate()
+ public void Tape_BooleanUnderTransform_MatchesRecursiveEvaluate()
{
- var union = new CirUnionNode(new CirSphereNode(3d), new CirBoxNode(4d, 4d, 4d));
- var node = new CirIntersectNode(union, new CirCylinderNode(4d, 6d));
- AssertTapeMatches(node, new Point3D(0d, 0d, 0d), new Point3D(4d, 4d, 0d), new Point3D(0d, 0d, 3d));
+ var booleanNode = new CirSubtractNode(new CirBoxNode(10d, 8d, 6d), new CirCylinderNode(2d, 10d));
+ var node = new CirTransformNode(booleanNode, Transform3D.CreateTranslation(new Vector3D(1d, 2d, -1d)) * Transform3D.CreateRotationZ(double.Pi / 8d));
+
+ AssertTapeMatches(node, new Point3D(1d, 2d, -1d), new Point3D(5d, 2d, -1d), new Point3D(1d, 5d, -1d));
}
[Fact]
- public void Tape_Transform_MatchesRecursiveEvaluate()
+ public void Tape_AllCurrentNodes_MatchRecursiveEvaluate()
{
- var transform = Transform3D.CreateTranslation(new Vector3D(2d, -1d, 3d)) * Transform3D.CreateRotationZ(double.Pi / 6d);
- var node = new CirTransformNode(new CirBoxNode(4d, 2d, 6d), transform);
- AssertTapeMatches(node, new Point3D(2d, -1d, 3d), new Point3D(7d, -1d, 3d), new Point3D(4d, 0d, 3d));
+ var transformedCylinder = new CirTransformNode(
+ new CirCylinderNode(1.5d, 9d),
+ Transform3D.CreateTranslation(new Vector3D(-2d, 0.5d, 1d)) * Transform3D.CreateRotationY(double.Pi / 5d));
+ var union = new CirUnionNode(new CirSphereNode(3d), transformedCylinder);
+ var subtract = new CirSubtractNode(union, new CirBoxNode(2.5d, 7d, 2d));
+ var node = new CirIntersectNode(subtract, new CirTransformNode(new CirBoxNode(10d, 10d, 10d), Transform3D.CreateTranslation(new Vector3D(0.5d, -0.5d, 0d))));
+
+ AssertTapeMatches(node,
+ new Point3D(0d, 0d, 0d),
+ new Point3D(1d, 2d, -1d),
+ new Point3D(-3d, 0.5d, 1d),
+ new Point3D(4d, 4d, 4d),
+ new Point3D(-5d, -2d, 2d));
}
[Fact]
@@ -76,7 +89,9 @@ public sealed class CirTapeEvaluationTests
var tape = CirTapeLowerer.Lower(node);
foreach (var point in points)
{
- Assert.Equal(node.Evaluate(point), tape.Evaluate(point), 12);
+ var expected = node.Evaluate(point);
+ var actual = tape.Evaluate(point);
+ Assert.InRange(double.Abs(expected - actual), 0d, 1e-6d);
}
}
}
diff --git a/Aetheris.Kernel.Core/Cir/CirTape.cs b/Aetheris.Kernel.Core/Cir/CirTape.cs
index f30a6791..e3e4733e 100644
--- a/Aetheris.Kernel.Core/Cir/CirTape.cs
+++ b/Aetheris.Kernel.Core/Cir/CirTape.cs
@@ -10,7 +10,6 @@ public enum CirTapeOpCode
Min,
Max,
Neg,
- EvalTransform,
}
public readonly record struct CirTapeInstruction(
@@ -22,11 +21,9 @@ public readonly record struct CirTapeInstruction(
CirNodeKind SourceKind,
int LoweringIndex);
-public readonly record struct CirTapeBoxPayload(double Width, double Height, double Depth);
-public readonly record struct CirTapeCylinderPayload(double Radius, double Height);
-public readonly record struct CirTapeSpherePayload(double Radius);
-public readonly record struct CirTapeTransformPayload(Transform3D InverseTransform);
-public readonly record struct CirTapeTransformEvalPayload(CirNode Child, Transform3D InverseTransform);
+public readonly record struct CirTapeBoxPayload(double Width, double Height, double Depth, Transform3D InverseTransform);
+public readonly record struct CirTapeCylinderPayload(double Radius, double Height, Transform3D InverseTransform);
+public readonly record struct CirTapeSpherePayload(double Radius, Transform3D InverseTransform);
/// <summary>
/// Linear MIR/runtime representation for CIR point evaluation.
@@ -39,8 +36,6 @@ public sealed class CirTape
IReadOnlyList<CirTapeBoxPayload> boxes,
IReadOnlyList<CirTapeCylinderPayload> cylinders,
IReadOnlyList<CirTapeSpherePayload> spheres,
- IReadOnlyList<CirTapeTransformPayload> transforms,
- IReadOnlyList<CirTapeTransformEvalPayload> transformEvals,
int outputSlot,
int slotCount)
{
@@ -48,8 +43,6 @@ public sealed class CirTape
BoxPayloads = boxes;
CylinderPayloads = cylinders;
SpherePayloads = spheres;
- TransformPayloads = transforms;
- TransformEvalPayloads = transformEvals;
OutputSlot = outputSlot;
SlotCount = slotCount;
}
@@ -58,8 +51,6 @@ public sealed class CirTape
public IReadOnlyList<CirTapeBoxPayload> BoxPayloads { get; }
public IReadOnlyList<CirTapeCylinderPayload> CylinderPayloads { get; }
public IReadOnlyList<CirTapeSpherePayload> SpherePayloads { get; }
- public IReadOnlyList<CirTapeTransformPayload> TransformPayloads { get; }
- public IReadOnlyList<CirTapeTransformEvalPayload> TransformEvalPayloads { get; }
public int OutputSlot { get; }
public int SlotCount { get; }
@@ -98,12 +89,6 @@ public sealed class CirTape
case CirTapeOpCode.Neg:
slots[instruction.DestSlot] = -slots[instruction.InputA];
break;
- case CirTapeOpCode.EvalTransform:
- {
- var payload = TransformEvalPayloads[instruction.PayloadIndex];
- slots[instruction.DestSlot] = payload.Child.Evaluate(payload.InverseTransform.Apply(point));
- break;
- }
default:
throw new InvalidOperationException($"Unsupported CIR tape opcode: {instruction.OpCode}.");
}
@@ -114,6 +99,7 @@ public sealed class CirTape
private static double EvaluateBox(Point3D point, CirTapeBoxPayload payload)
{
+ point = payload.InverseTransform.Apply(point);
var hx = payload.Width * 0.5d;
var hy = payload.Height * 0.5d;
var hz = payload.Depth * 0.5d;
@@ -130,6 +116,7 @@ public sealed class CirTape
private static double EvaluateCylinder(Point3D point, CirTapeCylinderPayload payload)
{
+ point = payload.InverseTransform.Apply(point);
var radial = double.Sqrt((point.X * point.X) + (point.Y * point.Y));
var dr = radial - payload.Radius;
var dz = double.Abs(point.Z) - (payload.Height * 0.5d);
@@ -140,8 +127,11 @@ public sealed class CirTape
return outside + inside;
}
- private static double EvaluateSphere(Point3D point, CirTapeSpherePayload payload) =>
- double.Sqrt((point.X * point.X) + (point.Y * point.Y) + (point.Z * point.Z)) - payload.Radius;
+ private static double EvaluateSphere(Point3D point, CirTapeSpherePayload payload)
+ {
+ point = payload.InverseTransform.Apply(point);
+ return double.Sqrt((point.X * point.X) + (point.Y * point.Y) + (point.Z * point.Z)) - payload.Radius;
+ }
}
public static class CirTapeLowerer
@@ -154,67 +144,62 @@ public static class CirTapeLowerer
ArgumentNullException.ThrowIfNull(node);
var state = new LoweringState();
- var outputSlot = LowerNode(node, state);
+ var outputSlot = LowerNode(node, Transform3D.Identity, state);
return new CirTape(
state.Instructions,
state.BoxPayloads,
state.CylinderPayloads,
state.SpherePayloads,
- state.TransformPayloads,
- state.TransformEvalPayloads,
outputSlot,
state.NextSlot);
}
- private static int LowerNode(CirNode node, LoweringState state)
+ private static int LowerNode(CirNode node, Transform3D accumulatedInverse, LoweringState state)
{
switch (node)
{
case CirBoxNode box:
{
var payloadIndex = state.BoxPayloads.Count;
- state.BoxPayloads.Add(new CirTapeBoxPayload(box.Width, box.Height, box.Depth));
+ state.BoxPayloads.Add(new CirTapeBoxPayload(box.Width, box.Height, box.Depth, accumulatedInverse));
return state.Emit(CirTapeOpCode.EvalBox, -1, -1, payloadIndex, node.Kind);
}
case CirCylinderNode cylinder:
{
var payloadIndex = state.CylinderPayloads.Count;
- state.CylinderPayloads.Add(new CirTapeCylinderPayload(cylinder.Radius, cylinder.Height));
+ state.CylinderPayloads.Add(new CirTapeCylinderPayload(cylinder.Radius, cylinder.Height, accumulatedInverse));
return state.Emit(CirTapeOpCode.EvalCylinder, -1, -1, payloadIndex, node.Kind);
}
case CirSphereNode sphere:
{
var payloadIndex = state.SpherePayloads.Count;
- state.SpherePayloads.Add(new CirTapeSpherePayload(sphere.Radius));
+ state.SpherePayloads.Add(new CirTapeSpherePayload(sphere.Radius, accumulatedInverse));
return state.Emit(CirTapeOpCode.EvalSphere, -1, -1, payloadIndex, node.Kind);
}
case CirUnionNode union:
{
- var left = LowerNode(union.Left, state);
- var right = LowerNode(union.Right, state);
+ var left = LowerNode(union.Left, accumulatedInverse, state);
+ var right = LowerNode(union.Right, accumulatedInverse, state);
return state.Emit(CirTapeOpCode.Min, left, right, -1, node.Kind);
}
case CirSubtractNode subtract:
{
- var left = LowerNode(subtract.Left, state);
- var right = LowerNode(subtract.Right, state);
+ var left = LowerNode(subtract.Left, accumulatedInverse, state);
+ var right = LowerNode(subtract.Right, accumulatedInverse, state);
var negRight = state.Emit(CirTapeOpCode.Neg, right, -1, -1, node.Kind);
return state.Emit(CirTapeOpCode.Max, left, negRight, -1, node.Kind);
}
case CirIntersectNode intersect:
{
- var left = LowerNode(intersect.Left, state);
- var right = LowerNode(intersect.Right, state);
+ var left = LowerNode(intersect.Left, accumulatedInverse, state);
+ var right = LowerNode(intersect.Right, accumulatedInverse, state);
return state.Emit(CirTapeOpCode.Max, left, right, -1, node.Kind);
}
case CirTransformNode transform:
{
- var payloadIndex = state.TransformEvalPayloads.Count;
- // CIR-E1 transitional caveat: transform execution keeps a child-node reference and
- // performs recursive child evaluation. E2 is expected to flatten this into pure tape ops.
- state.TransformEvalPayloads.Add(new CirTapeTransformEvalPayload(transform.Child, transform.Transform.Inverse()));
- return state.Emit(CirTapeOpCode.EvalTransform, -1, -1, payloadIndex, node.Kind);
+ var nextAccumulatedInverse = accumulatedInverse * transform.Transform.Inverse();
+ return LowerNode(transform.Child, nextAccumulatedInverse, state);
}
default:
throw new InvalidOperationException($"Unsupported CIR node kind for tape lowering: {node.Kind}.");
@@ -227,8 +212,6 @@ public static class CirTapeLowerer
public List<CirTapeBoxPayload> BoxPayloads { get; } = new();
public List<CirTapeCylinderPayload> CylinderPayloads { get; } = new();
public List<CirTapeSpherePayload> SpherePayloads { get; } = new();
- public List<CirTapeTransformPayload> TransformPayloads { get; } = new();
- public List<CirTapeTransformEvalPayload> TransformEvalPayloads { get; } = new();
public int NextSlot { get; private set; }
public int Emit(CirTapeOpCode opCode, int inputA, int inputB, int payloadIndex, CirNodeKind sourceKind)
diff --git a/docs/cir-e0-evaluation-runtime.md b/docs/cir-e0-evaluation-runtime.md
index de337ba8..11fe008f 100644
--- a/docs/cir-e0-evaluation-runtime.md
+++ b/docs/cir-e0-evaluation-runtime.md
@@ -270,27 +270,24 @@ Definition of done for CIR-E1:
This is not a deprecation notice for `CirNode`; it is an execution-path reframing.
-### 13.3 Transform caveat (E1 transitional behavior)
+### 13.3 Transform handling after CIR-E2
-E1 `EvalTransform` is correct but not fully flat:
+CIR-E2 removes the transitional recursive transform escape hatch from tape evaluation.
-- lowering emits transform payload (inverse transform) and retains a child `CirNode` reference,
-- tape execution evaluates the transformed point by recursively calling `Child.Evaluate(...)`.
+Chosen strategy: **Option B (baked local inverse transform per primitive payload)**.
-Why acceptable for E1:
+- lowering carries an accumulated inverse transform while traversing the tree,
+- `CirTransformNode` composes that accumulator and lowers only its child (no emitted transform opcode),
+- primitive tape payloads (`EvalBox`/`EvalCylinder`/`EvalSphere`) now store the accumulated inverse transform,
+- tape execution applies that payload transform before primitive SDF evaluation.
-- preserves correctness and deterministic parity while tape infrastructure lands,
-- avoids premature broad refactor of transform/subtree lowering policy.
+Resulting runtime shape:
-Why transitional:
+- tape remains straight-line SSA for current node kinds,
+- transform evaluation is fully self-contained in tape data/instructions,
+- tape point evaluation no longer calls `CirNode.Evaluate` for supported nodes.
-- this leaves recursion in the runtime hot path,
-- it weakens the “all execution is explicit in tape instructions” goal,
-- it complicates future interval/pruning/compiled-delegate tiers that assume flat instruction ownership.
-
-E2 direction:
-
-- flatten transform execution into tape-native instruction flow (or equivalent frame model) so transformed children no longer require recursive node calls at runtime.
+This preserves deterministic lowering and prepares interval evaluation and later bytecode/register compaction work by keeping execution ownership inside tape runtime data.
### 13.4 Lowering target policy going forward