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.csindex 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 CirTapeEvaluationTestsvar 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.csindex f30a6791..e3e4733e 100644--- a/Aetheris.Kernel.Core/Cir/CirTape.cs+++ b/Aetheris.Kernel.Core/Cir/CirTape.cs@@ -10,7 +10,6 @@ public enum CirTapeOpCodeMin,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 CirTapeIReadOnlyList<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 CirTapeBoxPayloads = boxes;CylinderPayloads = cylinders;SpherePayloads = spheres;- TransformPayloads = transforms;- TransformEvalPayloads = transformEvals;OutputSlot = outputSlot;SlotCount = slotCount;}@@ -58,8 +51,6 @@ public sealed class CirTapepublic 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 CirTapecase 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 CirTapeprivate 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 CirTapeprivate 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 CirTapereturn 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 CirTapeLowererArgumentNullException.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 CirTapeLowererpublic 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.mdindex 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