Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add CIR cone primitive with tape and Firmament lowering support

Yuechen Lia8e3df62aaf6
diff --git a/Aetheris.Kernel.Core.Tests/Cir/CirConeTests.cs b/Aetheris.Kernel.Core.Tests/Cir/CirConeTests.cs
new file mode 100644
index 00000000..47988cff
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Cir/CirConeTests.cs
@@ -0,0 +1,57 @@
+using Aetheris.Kernel.Core.Cir;
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Tests.Cir;
+
+public sealed class CirConeTests
+{
+ [Fact]
+ public void CirCone_EvaluatesInsideOutsideForFrustum()
+ {
+ var cone = new CirConeNode(bottomRadius: 4d, topRadius: 2d, height: 8d);
+
+ Assert.True(cone.Evaluate(new Point3D(0d, 0d, 0d)) < 0d);
+ Assert.True(cone.Evaluate(new Point3D(5d, 0d, 0d)) > 0d);
+ Assert.True(cone.Evaluate(new Point3D(0d, 0d, 5d)) > 0d);
+ }
+
+ [Fact]
+ public void CirCone_EvaluatesPointConeApexBehavior()
+ {
+ var cone = new CirConeNode(bottomRadius: 4d, topRadius: 0d, height: 8d);
+
+ var apex = cone.Evaluate(new Point3D(0d, 0d, 4d));
+ var nearApex = cone.Evaluate(new Point3D(0.01d, 0d, 3.99d));
+ var center = cone.Evaluate(new Point3D(0d, 0d, 0d));
+
+ Assert.False(double.IsNaN(apex) || double.IsInfinity(apex));
+ Assert.False(double.IsNaN(nearApex) || double.IsInfinity(nearApex));
+ Assert.False(double.IsNaN(center) || double.IsInfinity(center));
+ Assert.InRange(double.Abs(apex), 0d, 1e-6d);
+ Assert.True(center < 0d);
+ }
+
+ [Fact]
+ public void CirCone_RejectsInvalidParameters()
+ {
+ Assert.Throws<ArgumentOutOfRangeException>(() => new CirConeNode(-1d, 1d, 2d));
+ Assert.Throws<ArgumentOutOfRangeException>(() => new CirConeNode(1d, -1d, 2d));
+ Assert.Throws<ArgumentOutOfRangeException>(() => new CirConeNode(0d, 0d, 2d));
+ Assert.Throws<ArgumentOutOfRangeException>(() => new CirConeNode(1d, 1d, 0d));
+ }
+
+ [Fact]
+ public void CirCone_TapeLowering_EvaluatesDeterministically()
+ {
+ var node = new CirTransformNode(new CirConeNode(5d, 2d, 10d), Transform3D.CreateTranslation(new Vector3D(1d, -2d, 3d)));
+ var tapeA = CirTapeLowerer.Lower(node);
+ var tapeB = CirTapeLowerer.Lower(node);
+
+ Assert.Equal(tapeA.Instructions, tapeB.Instructions);
+ Assert.Equal(tapeA.ConePayloads, tapeB.ConePayloads);
+
+ var probe = new Point3D(1.5d, -2d, 2d);
+ Assert.Equal(tapeA.Evaluate(probe), tapeB.Evaluate(probe), 12);
+ Assert.Equal(node.Evaluate(probe), tapeA.Evaluate(probe), 9);
+ }
+}
diff --git a/Aetheris.Kernel.Core/Cir/CirNode.cs b/Aetheris.Kernel.Core/Cir/CirNode.cs
index 59f12727..e5c4cf8c 100644
--- a/Aetheris.Kernel.Core/Cir/CirNode.cs
+++ b/Aetheris.Kernel.Core/Cir/CirNode.cs
@@ -8,6 +8,7 @@ public enum CirNodeKind
Cylinder,
Sphere,
Torus,
+ Cone,
Union,
Subtract,
Intersect,
diff --git a/Aetheris.Kernel.Core/Cir/CirNodes.cs b/Aetheris.Kernel.Core/Cir/CirNodes.cs
index c5546cd5..18406cb7 100644
--- a/Aetheris.Kernel.Core/Cir/CirNodes.cs
+++ b/Aetheris.Kernel.Core/Cir/CirNodes.cs
@@ -41,6 +41,80 @@ public sealed record CirCylinderNode(double Radius, double Height) : CirNode(Cir
}
}
+
+
+public sealed record CirConeNode : CirNode
+{
+ public CirConeNode(double bottomRadius, double topRadius, double height) : base(CirNodeKind.Cone)
+ {
+ if (height <= 0d || double.IsNaN(height) || double.IsInfinity(height))
+ {
+ throw new ArgumentOutOfRangeException(nameof(height), "Cone height must be finite and > 0.");
+ }
+
+ if (bottomRadius < 0d || double.IsNaN(bottomRadius) || double.IsInfinity(bottomRadius))
+ {
+ throw new ArgumentOutOfRangeException(nameof(bottomRadius), "Cone bottom radius must be finite and >= 0.");
+ }
+
+ if (topRadius < 0d || double.IsNaN(topRadius) || double.IsInfinity(topRadius))
+ {
+ throw new ArgumentOutOfRangeException(nameof(topRadius), "Cone top radius must be finite and >= 0.");
+ }
+
+ if (bottomRadius <= 0d && topRadius <= 0d)
+ {
+ throw new ArgumentOutOfRangeException(nameof(topRadius), "At least one cone radius must be > 0.");
+ }
+
+ BottomRadius = bottomRadius;
+ TopRadius = topRadius;
+ Height = height;
+ }
+
+ public double BottomRadius { get; }
+ public double TopRadius { get; }
+ public double Height { get; }
+
+ public override CirBounds Bounds
+ {
+ get
+ {
+ var r = double.Max(BottomRadius, TopRadius);
+ var hz = Height * 0.5d;
+ return new CirBounds(new Point3D(-r, -r, -hz), new Point3D(r, r, hz));
+ }
+ }
+
+ public override double Evaluate(Point3D point) => EvaluateFiniteCone(point, BottomRadius, TopRadius, Height);
+
+ internal static double EvaluateFiniteCone(Point3D point, double bottomRadius, double topRadius, double height)
+ {
+ var hz = height * 0.5d;
+ var qx = double.Sqrt((point.X * point.X) + (point.Y * point.Y));
+ var qy = point.Z;
+
+ var k1x = topRadius;
+ var k1y = hz;
+ var k2x = topRadius - bottomRadius;
+ var k2y = height;
+
+ var caX = qx - double.Min(qx, qy < 0d ? bottomRadius : topRadius);
+ var caY = double.Abs(qy) - hz;
+
+ var dotNumerator = ((k1x - qx) * k2x) + ((k1y - qy) * k2y);
+ var dotDenominator = (k2x * k2x) + (k2y * k2y);
+ var h = dotDenominator <= 1e-18d ? 0d : Clamp(dotNumerator / dotDenominator, 0d, 1d);
+
+ var cbX = qx - k1x + (k2x * h);
+ var cbY = qy - k1y + (k2y * h);
+
+ var s = (cbX < 0d && caY < 0d) ? -1d : 1d;
+ return s * double.Sqrt(double.Min((caX * caX) + (caY * caY), (cbX * cbX) + (cbY * cbY)));
+ }
+
+ private static double Clamp(double value, double min, double max) => value < min ? min : value > max ? max : value;
+}
public sealed record CirSphereNode(double Radius) : CirNode(CirNodeKind.Sphere)
{
public override CirBounds Bounds => new(new Point3D(-Radius, -Radius, -Radius), new Point3D(Radius, Radius, Radius));
diff --git a/Aetheris.Kernel.Core/Cir/CirTape.cs b/Aetheris.Kernel.Core/Cir/CirTape.cs
index d5b1df27..457e369a 100644
--- a/Aetheris.Kernel.Core/Cir/CirTape.cs
+++ b/Aetheris.Kernel.Core/Cir/CirTape.cs
@@ -9,6 +9,7 @@ public enum CirTapeOpCode
EvalCylinder,
EvalSphere,
EvalTorus,
+ EvalCone,
Min,
Max,
Neg,
@@ -27,6 +28,7 @@ public readonly record struct CirTapeBoxPayload(double Width, double Height, dou
public readonly record struct CirTapeCylinderPayload(double Radius, double Height, Transform3D InverseTransform);
public readonly record struct CirTapeSpherePayload(double Radius, Transform3D InverseTransform);
public readonly record struct CirTapeTorusPayload(double MajorRadius, double MinorRadius, Transform3D InverseTransform);
+public readonly record struct CirTapeConePayload(double BottomRadius, double TopRadius, double Height, Transform3D InverseTransform);
public readonly record struct FieldInterval(double MinValue, double MaxValue)
{
@@ -54,6 +56,7 @@ public sealed class CirTape
IReadOnlyList<CirTapeCylinderPayload> cylinders,
IReadOnlyList<CirTapeSpherePayload> spheres,
IReadOnlyList<CirTapeTorusPayload> toruses,
+ IReadOnlyList<CirTapeConePayload> cones,
int outputSlot,
int slotCount)
{
@@ -62,6 +65,7 @@ public sealed class CirTape
CylinderPayloads = cylinders;
SpherePayloads = spheres;
TorusPayloads = toruses;
+ ConePayloads = cones;
OutputSlot = outputSlot;
SlotCount = slotCount;
}
@@ -71,6 +75,7 @@ public sealed class CirTape
public IReadOnlyList<CirTapeCylinderPayload> CylinderPayloads { get; }
public IReadOnlyList<CirTapeSpherePayload> SpherePayloads { get; }
public IReadOnlyList<CirTapeTorusPayload> TorusPayloads { get; }
+ public IReadOnlyList<CirTapeConePayload> ConePayloads { get; }
public int OutputSlot { get; }
public int SlotCount { get; }
@@ -106,6 +111,12 @@ public sealed class CirTape
slots[instruction.DestSlot] = EvaluateTorus(point, payload);
break;
}
+ case CirTapeOpCode.EvalCone:
+ {
+ var payload = ConePayloads[instruction.PayloadIndex];
+ slots[instruction.DestSlot] = EvaluateCone(point, payload);
+ break;
+ }
case CirTapeOpCode.Min:
slots[instruction.DestSlot] = double.Min(slots[instruction.InputA], slots[instruction.InputB]);
break;
@@ -143,6 +154,9 @@ public sealed class CirTape
case CirTapeOpCode.EvalTorus:
slots[instruction.DestSlot] = EvaluateTorusInterval(region, TorusPayloads[instruction.PayloadIndex]);
break;
+ case CirTapeOpCode.EvalCone:
+ slots[instruction.DestSlot] = EvaluateConeInterval(region, ConePayloads[instruction.PayloadIndex]);
+ break;
case CirTapeOpCode.Min:
{
var a = slots[instruction.InputA];
@@ -231,6 +245,12 @@ public sealed class CirTape
return double.Sqrt((qx * qx) + (point.Z * point.Z)) - payload.MinorRadius;
}
+ private static double EvaluateCone(Point3D point, CirTapeConePayload payload)
+ {
+ point = payload.InverseTransform.Apply(point);
+ return CirConeNode.EvaluateFiniteCone(point, payload.BottomRadius, payload.TopRadius, payload.Height);
+ }
+
private static FieldInterval EvaluateBoxInterval(CirBounds region, CirTapeBoxPayload payload)
{
var local = TransformBounds(region, payload.InverseTransform);
@@ -269,6 +289,22 @@ public sealed class CirTape
return new FieldInterval(minD - payload.MinorRadius, maxD - payload.MinorRadius);
}
+ private static FieldInterval EvaluateConeInterval(CirBounds region, CirTapeConePayload payload)
+ {
+ var local = TransformBounds(region, payload.InverseTransform);
+ var corners = GetCorners(local);
+ var min = double.PositiveInfinity;
+ var max = double.NegativeInfinity;
+ foreach (var c in corners)
+ {
+ var value = CirConeNode.EvaluateFiniteCone(c, payload.BottomRadius, payload.TopRadius, payload.Height);
+ min = double.Min(min, value);
+ max = double.Max(max, value);
+ }
+
+ return new FieldInterval(min, max);
+ }
+
private static CirBounds TransformBounds(CirBounds bounds, Transform3D transform)
{
var corners = GetCorners(bounds);
@@ -371,6 +407,7 @@ public static class CirTapeLowerer
state.CylinderPayloads,
state.SpherePayloads,
state.TorusPayloads,
+ state.ConePayloads,
outputSlot,
state.NextSlot);
}
@@ -403,6 +440,12 @@ public static class CirTapeLowerer
state.TorusPayloads.Add(new CirTapeTorusPayload(torus.MajorRadius, torus.MinorRadius, accumulatedInverse));
return state.Emit(CirTapeOpCode.EvalTorus, -1, -1, payloadIndex, node.Kind);
}
+ case CirConeNode cone:
+ {
+ var payloadIndex = state.ConePayloads.Count;
+ state.ConePayloads.Add(new CirTapeConePayload(cone.BottomRadius, cone.TopRadius, cone.Height, accumulatedInverse));
+ return state.Emit(CirTapeOpCode.EvalCone, -1, -1, payloadIndex, node.Kind);
+ }
case CirUnionNode union:
{
var left = LowerNode(union.Left, accumulatedInverse, state);
@@ -439,6 +482,7 @@ public static class CirTapeLowerer
public List<CirTapeCylinderPayload> CylinderPayloads { get; } = new();
public List<CirTapeSpherePayload> SpherePayloads { get; } = new();
public List<CirTapeTorusPayload> TorusPayloads { get; } = new();
+ public List<CirTapeConePayload> ConePayloads { get; } = new();
public int NextSlot { get; private set; }
public int Emit(CirTapeOpCode opCode, int inputA, int inputB, int payloadIndex, CirNodeKind sourceKind)
diff --git a/Aetheris.Kernel.Firmament/Lowering/FirmamentCirLowerer.cs b/Aetheris.Kernel.Firmament/Lowering/FirmamentCirLowerer.cs
index 388ab28a..99d77934 100644
--- a/Aetheris.Kernel.Firmament/Lowering/FirmamentCirLowerer.cs
+++ b/Aetheris.Kernel.Firmament/Lowering/FirmamentCirLowerer.cs
@@ -106,6 +106,8 @@ internal static class FirmamentCirLowerer
"sphere" when boolean.Tool.RawFields.TryGetValue("radius", out var sr) => new CirSphereNode(double.Parse(sr)),
"torus" when boolean.Tool.RawFields.TryGetValue("major_radius", out var major) && boolean.Tool.RawFields.TryGetValue("minor_radius", out var minor)
=> new CirTorusNode(double.Parse(major), double.Parse(minor)),
+ "cone" when boolean.Tool.RawFields.TryGetValue("bottom_radius", out var br) && boolean.Tool.RawFields.TryGetValue("top_radius", out var tr) && boolean.Tool.RawFields.TryGetValue("height", out var ch)
+ => new CirConeNode(double.Parse(br), double.Parse(tr), double.Parse(ch)),
_ => UnsupportedTool(boolean, diagnostics)
};
}
@@ -122,6 +124,7 @@ internal static class FirmamentCirLowerer
{ Kind: FirmamentLoweredPrimitiveKind.Cylinder, Parameters: FirmamentLoweredCylinderParameters cylinder } => new CirCylinderNode(cylinder.Radius, cylinder.Height),
{ Kind: FirmamentLoweredPrimitiveKind.Sphere, Parameters: FirmamentLoweredSphereParameters sphere } => new CirSphereNode(sphere.Radius),
{ Kind: FirmamentLoweredPrimitiveKind.Torus, Parameters: FirmamentLoweredTorusParameters torus } => new CirTorusNode(torus.MajorRadius, torus.MinorRadius),
+ { Kind: FirmamentLoweredPrimitiveKind.Cone, Parameters: FirmamentLoweredConeParameters cone } => new CirConeNode(cone.BottomRadius, cone.TopRadius, cone.Height),
_ => UnsupportedPrimitive(primitive, diagnostics)
};
diff --git a/docs/cir-cone-v1-cir-cone-primitive.md b/docs/cir-cone-v1-cir-cone-primitive.md
new file mode 100644
index 00000000..4af9c0fc
--- /dev/null
+++ b/docs/cir-cone-v1-cir-cone-primitive.md
@@ -0,0 +1,64 @@
+# CIR-CONE-V1: CIR cone primitive for Firmament path
+
+## Scope outcome
+
+This milestone adds a bounded `CirConeNode` primitive to CIR semantic and tape evaluation paths, plus Firmament→CIR lowering for cone primitives/tools.
+
+## Parameter convention
+
+`CirConeNode(bottomRadius, topRadius, height)`.
+
+- Native frame is origin-centered on Z.
+- Bottom cap plane: `z = -height/2` with radius `bottomRadius`.
+- Top cap plane: `z = +height/2` with radius `topRadius`.
+- Radius varies linearly along Z from bottom to top.
+- Allowed: frustum (both radii > 0), point cone (one radius = 0), equal radii (cylinder-like cone).
+
+Validation:
+- `height > 0` and finite,
+- `bottomRadius >= 0` finite,
+- `topRadius >= 0` finite,
+- at least one radius strictly greater than zero.
+
+## Evaluation/SDF convention
+
+- Uses a bounded finite cone signed-distance style function (same evaluator in node and tape), not a cylinder approximation.
+- Capped finite behavior is modeled directly.
+- Point-cone apex handling is stable (no NaN/Inf on tested probes).
+
+## Transform policy
+
+- No axis/orientation fields in `CirConeNode`.
+- Arbitrary placement/orientation stays in `CirTransformNode` and tape inverse payload transforms, matching existing primitive conventions.
+
+## Tape/lowering status
+
+Added:
+- `CirTapeOpCode.EvalCone`,
+- `CirTapeConePayload`,
+- point evaluation path,
+- conservative interval path (corner-sampled bound in local transformed AABB),
+- `CirTapeLowerer` support.
+
+## Firmament lowering status
+
+Firmament already has cone primitive syntax and lowered cone parameters. CIR lowering now maps:
+- primitive `cone` -> `CirConeNode`,
+- boolean tool `cone` -> `CirConeNode`.
+
+## Source-surface extraction status
+
+Deferred for V1.
+
+`SourceSurfaceExtractor` currently inventories box/cylinder/sphere/torus evidence only. Conical source-surface descriptor/evidence integration is a follow-up milestone to avoid broadening this primitive-only change.
+
+## BRep point-cone cleanup status
+
+Inspected existing BRep cone/frustum path; no low-risk apex-topology cleanup was applied in this milestone. Keeping CIR-CONE-V1 bounded; if tiny degenerate apex geometry persists in BRep point-cone construction, track as a focused BRep follow-up.
+
+## Next milestone suggestion
+
+CIR-RECOVERY-V11:
+1. update `CountersinkVariant` recognition to admit bounded cone tool patterns using `CirConeNode`,
+2. add strict coaxial/entry/depth/radius checks,
+3. wire executor cone subtract path and countersink STEP smoke in that milestone (not in V1).