Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add M05 analytic geometry primitives and tests

Yuechen Li5f9870dce454
diff --git a/Aetheris.Kernel.Core.Tests/Geometry/CurvePrimitivesTests.cs b/Aetheris.Kernel.Core.Tests/Geometry/CurvePrimitivesTests.cs
new file mode 100644
index 00000000..f0a7e640
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Geometry/CurvePrimitivesTests.cs
@@ -0,0 +1,81 @@
+using Aetheris.Kernel.Core.Geometry.Curves;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+
+namespace Aetheris.Kernel.Core.Tests.Geometry;
+
+public sealed class CurvePrimitivesTests
+{
+ [Fact]
+ public void Line_EvaluateAndTangent_FollowDirection()
+ {
+ var line = new Line3Curve(new Point3D(1, 2, 3), Direction3D.Create(new Vector3D(2, 0, 0)));
+
+ Assert.Equal(new Point3D(1, 2, 3), line.Evaluate(0));
+ Assert.Equal(new Point3D(3, 2, 3), line.Evaluate(2));
+ Assert.Equal(new Point3D(-1, 2, 3), line.Evaluate(-2));
+ Assert.Equal(line.Direction, line.Tangent(0));
+ Assert.Equal(line.Direction, line.Tangent(10));
+ }
+
+ [Theory]
+ [InlineData(0)]
+ [InlineData(-1)]
+ [InlineData(double.NaN)]
+ [InlineData(double.PositiveInfinity)]
+ public void Circle_InvalidRadius_Throws(double radius)
+ {
+ Assert.Throws<ArgumentOutOfRangeException>(() =>
+ new Circle3Curve(Point3D.Origin, Direction3D.Create(new Vector3D(0, 0, 1)), radius, Direction3D.Create(new Vector3D(1, 0, 0))));
+ }
+
+ [Fact]
+ public void Circle_Evaluate_KnownAnglesAndOrientation()
+ {
+ var circle = new Circle3Curve(
+ center: Point3D.Origin,
+ normal: Direction3D.Create(new Vector3D(0, 0, 1)),
+ radius: 2,
+ referenceAxis: Direction3D.Create(new Vector3D(1, 0, 0)));
+
+ AssertPoint(circle.Evaluate(0), new Point3D(2, 0, 0));
+ AssertPoint(circle.Evaluate(double.Pi / 2d), new Point3D(0, 2, 0));
+ AssertPoint(circle.Evaluate(double.Pi), new Point3D(-2, 0, 0));
+
+ var tangentAtZero = circle.Tangent(0);
+ AssertVector(tangentAtZero, new Vector3D(0, 2, 0));
+
+ var cross = circle.XAxis.ToVector().Cross(circle.YAxis.ToVector());
+ AssertVector(cross, circle.Normal.ToVector());
+ }
+
+ [Theory]
+ [InlineData(0)]
+ [InlineData(1.1)]
+ [InlineData(2.7)]
+ public void Circle_EvaluatedPoints_StayAtRadius(double angle)
+ {
+ var circle = new Circle3Curve(
+ center: new Point3D(4, -3, 1),
+ normal: Direction3D.Create(new Vector3D(0, 0, 1)),
+ radius: 3,
+ referenceAxis: Direction3D.Create(new Vector3D(1, 0, 0)));
+
+ var point = circle.Evaluate(angle);
+ var distance = (point - circle.Center).Length;
+
+ Assert.True(ToleranceMath.AlmostEqual(distance, circle.Radius, ToleranceContext.Default));
+ }
+
+ private static void AssertPoint(Point3D actual, Point3D expected)
+ {
+ AssertVector(actual - expected, Vector3D.Zero);
+ }
+
+ private static void AssertVector(Vector3D actual, Vector3D expected)
+ {
+ Assert.True(ToleranceMath.AlmostEqual(actual.X, expected.X, ToleranceContext.Default));
+ Assert.True(ToleranceMath.AlmostEqual(actual.Y, expected.Y, ToleranceContext.Default));
+ Assert.True(ToleranceMath.AlmostEqual(actual.Z, expected.Z, ToleranceContext.Default));
+ }
+}
diff --git a/Aetheris.Kernel.Core.Tests/Geometry/ParameterIntervalTests.cs b/Aetheris.Kernel.Core.Tests/Geometry/ParameterIntervalTests.cs
new file mode 100644
index 00000000..31bc1543
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Geometry/ParameterIntervalTests.cs
@@ -0,0 +1,36 @@
+using Aetheris.Kernel.Core.Geometry;
+
+namespace Aetheris.Kernel.Core.Tests.Geometry;
+
+public sealed class ParameterIntervalTests
+{
+ [Fact]
+ public void Constructor_ValidRange_AllowsEqualOrIncreasingBounds()
+ {
+ var degenerate = new ParameterInterval(2, 2);
+ var regular = new ParameterInterval(-1, 5);
+
+ Assert.Equal(2, degenerate.Start);
+ Assert.Equal(2, degenerate.End);
+ Assert.Equal(-1, regular.Start);
+ Assert.Equal(5, regular.End);
+ }
+
+ [Fact]
+ public void Constructor_InvalidRange_Throws()
+ {
+ Assert.Throws<ArgumentOutOfRangeException>(() => new ParameterInterval(5, 4));
+ }
+
+ [Fact]
+ public void Contains_InclusiveBoundarySemantics()
+ {
+ var interval = new ParameterInterval(1, 3);
+
+ Assert.True(interval.Contains(1));
+ Assert.True(interval.Contains(3));
+ Assert.True(interval.Contains(2));
+ Assert.False(interval.Contains(0.5));
+ Assert.False(interval.Contains(3.5));
+ }
+}
diff --git a/Aetheris.Kernel.Core.Tests/Geometry/SurfacePrimitivesTests.cs b/Aetheris.Kernel.Core.Tests/Geometry/SurfacePrimitivesTests.cs
new file mode 100644
index 00000000..7f95ae2b
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Geometry/SurfacePrimitivesTests.cs
@@ -0,0 +1,132 @@
+using Aetheris.Kernel.Core.Geometry.Surfaces;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+
+namespace Aetheris.Kernel.Core.Tests.Geometry;
+
+public sealed class SurfacePrimitivesTests
+{
+ [Fact]
+ public void Plane_EvaluateAndNormal_AreConsistent()
+ {
+ var plane = new PlaneSurface(
+ origin: new Point3D(1, 2, 3),
+ normal: Direction3D.Create(new Vector3D(0, 0, 1)),
+ uAxis: Direction3D.Create(new Vector3D(1, 0, 0)));
+
+ var point = plane.Evaluate(2, -3);
+
+ AssertPoint(point, new Point3D(3, -1, 3));
+ AssertVector(plane.Normal.ToVector(), new Vector3D(0, 0, 1));
+ Assert.True(ToleranceMath.AlmostEqual(plane.Normal.ToVector().Length, 1, ToleranceContext.Default));
+ }
+
+ [Theory]
+ [InlineData(0)]
+ [InlineData(-1)]
+ [InlineData(double.NaN)]
+ [InlineData(double.PositiveInfinity)]
+ public void Cylinder_InvalidRadius_Throws(double radius)
+ {
+ Assert.Throws<ArgumentOutOfRangeException>(() =>
+ new CylinderSurface(Point3D.Origin, Direction3D.Create(new Vector3D(0, 0, 1)), radius, Direction3D.Create(new Vector3D(1, 0, 0))));
+ }
+
+ [Fact]
+ public void Cylinder_EvaluateAndNormal_AreCorrect()
+ {
+ var cylinder = new CylinderSurface(
+ origin: Point3D.Origin,
+ axis: Direction3D.Create(new Vector3D(0, 0, 1)),
+ radius: 2,
+ referenceAxis: Direction3D.Create(new Vector3D(1, 0, 0)));
+
+ AssertPoint(cylinder.Evaluate(0, 3), new Point3D(2, 0, 3));
+ AssertPoint(cylinder.Evaluate(double.Pi / 2d, 1), new Point3D(0, 2, 1));
+
+ var point = cylinder.Evaluate(1.234, -2.5);
+ var axialProjection = cylinder.Axis.ToVector() * ((point - cylinder.Origin).Dot(cylinder.Axis.ToVector()));
+ var radial = (point - cylinder.Origin) - axialProjection;
+
+ Assert.True(ToleranceMath.AlmostEqual(radial.Length, cylinder.Radius, ToleranceContext.Default));
+
+ var normal = cylinder.Normal(double.Pi / 2d).ToVector();
+ AssertVector(normal, new Vector3D(0, 1, 0));
+ Assert.True(ToleranceMath.AlmostEqual(normal.Length, 1, ToleranceContext.Default));
+ }
+
+ [Theory]
+ [InlineData(0)]
+ [InlineData(-1)]
+ [InlineData(double.NaN)]
+ [InlineData(double.PositiveInfinity)]
+ public void Sphere_InvalidRadius_Throws(double radius)
+ {
+ Assert.Throws<ArgumentOutOfRangeException>(() =>
+ new SphereSurface(Point3D.Origin, Direction3D.Create(new Vector3D(0, 0, 1)), radius, Direction3D.Create(new Vector3D(1, 0, 0))));
+ }
+
+ [Fact]
+ public void Sphere_EvaluateAndNormal_AreCorrect()
+ {
+ var sphere = new SphereSurface(
+ center: Point3D.Origin,
+ axis: Direction3D.Create(new Vector3D(0, 0, 1)),
+ radius: 3,
+ referenceAxis: Direction3D.Create(new Vector3D(1, 0, 0)));
+
+ AssertPoint(sphere.Evaluate(0, 0), new Point3D(3, 0, 0));
+ AssertPoint(sphere.Evaluate(double.Pi / 2d, 0), new Point3D(0, 3, 0));
+ AssertPoint(sphere.Evaluate(0, double.Pi / 2d), new Point3D(0, 0, 3));
+
+ var point = sphere.Evaluate(1.2, -0.7);
+ Assert.True(ToleranceMath.AlmostEqual((point - sphere.Center).Length, sphere.Radius, ToleranceContext.Default));
+
+ var normal = sphere.Normal(1.2, -0.7).ToVector();
+ var radial = Direction3D.Create(point - sphere.Center).ToVector();
+ AssertVector(normal, radial);
+ Assert.True(ToleranceMath.AlmostEqual(normal.Length, 1, ToleranceContext.Default));
+ }
+
+ [Theory]
+ [InlineData(0)]
+ [InlineData(-0.1)]
+ [InlineData(double.NaN)]
+ [InlineData(double.Pi / 2d)]
+ public void Cone_InvalidSemiAngle_Throws(double semiAngle)
+ {
+ Assert.Throws<ArgumentOutOfRangeException>(() =>
+ new ConeSurface(Point3D.Origin, Direction3D.Create(new Vector3D(0, 0, 1)), semiAngle, Direction3D.Create(new Vector3D(1, 0, 0))));
+ }
+
+ [Fact]
+ public void Cone_EvaluateAndNormal_ArePlausible()
+ {
+ var semiAngle = double.Pi / 6d;
+ var cone = new ConeSurface(
+ apex: Point3D.Origin,
+ axis: Direction3D.Create(new Vector3D(0, 0, 1)),
+ semiAngleRadians: semiAngle,
+ referenceAxis: Direction3D.Create(new Vector3D(1, 0, 0)));
+
+ var point = cone.Evaluate(0, 4);
+ AssertPoint(point, new Point3D(4 * double.Tan(semiAngle), 0, 4));
+
+ var sample = cone.Evaluate(1.1, 3);
+ var radialLength = double.Sqrt((sample.X * sample.X) + (sample.Y * sample.Y));
+ Assert.True(ToleranceMath.AlmostEqual(radialLength, sample.Z * double.Tan(semiAngle), ToleranceContext.Default));
+
+ var normal = cone.Normal(0).ToVector();
+ Assert.True(ToleranceMath.AlmostEqual(normal.Length, 1, ToleranceContext.Default));
+ Assert.True(normal.X > 0);
+ }
+
+ private static void AssertPoint(Point3D actual, Point3D expected) => AssertVector(actual - expected, Vector3D.Zero);
+
+ private static void AssertVector(Vector3D actual, Vector3D expected)
+ {
+ Assert.True(ToleranceMath.AlmostEqual(actual.X, expected.X, ToleranceContext.Default));
+ Assert.True(ToleranceMath.AlmostEqual(actual.Y, expected.Y, ToleranceContext.Default));
+ Assert.True(ToleranceMath.AlmostEqual(actual.Z, expected.Z, ToleranceContext.Default));
+ }
+}
diff --git a/Aetheris.Kernel.Core/Geometry/Curves/Circle3Curve.cs b/Aetheris.Kernel.Core/Geometry/Curves/Circle3Curve.cs
new file mode 100644
index 00000000..7c9b4af4
--- /dev/null
+++ b/Aetheris.Kernel.Core/Geometry/Curves/Circle3Curve.cs
@@ -0,0 +1,66 @@
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Geometry.Curves;
+
+/// <summary>
+/// Circle parameterization: P(t) = Center + Radius * (cos(t) * XAxis + sin(t) * YAxis),
+/// where YAxis = Normal x XAxis.
+/// </summary>
+public readonly record struct Circle3Curve
+{
+ private readonly Direction3D _xAxis;
+ private readonly Direction3D _yAxis;
+
+ public Circle3Curve(Point3D center, Direction3D normal, double radius, Direction3D referenceAxis)
+ {
+ if (!double.IsFinite(radius) || radius <= 0d)
+ {
+ throw new ArgumentOutOfRangeException(nameof(radius), "Radius must be finite and greater than zero.");
+ }
+
+ var n = normal.ToVector();
+ var reference = referenceAxis.ToVector();
+ var projected = reference - (n * reference.Dot(n));
+
+ if (!Direction3D.TryCreate(projected, out var xAxis))
+ {
+ throw new ArgumentOutOfRangeException(nameof(referenceAxis), "Reference axis must not be parallel to the normal.");
+ }
+
+ if (!Direction3D.TryCreate(n.Cross(xAxis.ToVector()), out var yAxis))
+ {
+ throw new ArgumentOutOfRangeException(nameof(normal), "Normal must define a valid circle plane.");
+ }
+
+ Center = center;
+ Normal = normal;
+ Radius = radius;
+ _xAxis = xAxis;
+ _yAxis = yAxis;
+ }
+
+ public Point3D Center { get; }
+
+ public Direction3D Normal { get; }
+
+ public double Radius { get; }
+
+ public Direction3D XAxis => _xAxis;
+
+ public Direction3D YAxis => _yAxis;
+
+ public Point3D Evaluate(double angleRadians)
+ {
+ var cosine = double.Cos(angleRadians);
+ var sine = double.Sin(angleRadians);
+ var offset = (_xAxis.ToVector() * (Radius * cosine)) + (_yAxis.ToVector() * (Radius * sine));
+ return Center + offset;
+ }
+
+ public Vector3D Tangent(double angleRadians)
+ {
+ var cosine = double.Cos(angleRadians);
+ var sine = double.Sin(angleRadians);
+ return (_xAxis.ToVector() * (-Radius * sine)) + (_yAxis.ToVector() * (Radius * cosine));
+ }
+}
diff --git a/Aetheris.Kernel.Core/Geometry/Curves/Line3Curve.cs b/Aetheris.Kernel.Core/Geometry/Curves/Line3Curve.cs
new file mode 100644
index 00000000..1a1c6f30
--- /dev/null
+++ b/Aetheris.Kernel.Core/Geometry/Curves/Line3Curve.cs
@@ -0,0 +1,10 @@
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Geometry.Curves;
+
+public readonly record struct Line3Curve(Point3D Origin, Direction3D Direction)
+{
+ public Point3D Evaluate(double t) => Origin + (Direction.ToVector() * t);
+
+ public Direction3D Tangent(double t) => Direction;
+}
diff --git a/Aetheris.Kernel.Core/Geometry/ParameterInterval.cs b/Aetheris.Kernel.Core/Geometry/ParameterInterval.cs
new file mode 100644
index 00000000..ae15be56
--- /dev/null
+++ b/Aetheris.Kernel.Core/Geometry/ParameterInterval.cs
@@ -0,0 +1,47 @@
+using Aetheris.Kernel.Core.Numerics;
+
+namespace Aetheris.Kernel.Core.Geometry;
+
+/// <summary>
+/// Represents an inclusive 1D parameter interval [Start, End].
+/// Degenerate intervals (Start == End) are allowed.
+/// </summary>
+public readonly record struct ParameterInterval
+{
+ public ParameterInterval(double start, double end)
+ {
+ if (!double.IsFinite(start))
+ {
+ throw new ArgumentOutOfRangeException(nameof(start), "Start must be finite.");
+ }
+
+ if (!double.IsFinite(end))
+ {
+ throw new ArgumentOutOfRangeException(nameof(end), "End must be finite.");
+ }
+
+ if (end < start)
+ {
+ throw new ArgumentOutOfRangeException(nameof(end), "End must be greater than or equal to Start.");
+ }
+
+ Start = start;
+ End = end;
+ }
+
+ public double Start { get; }
+
+ public double End { get; }
+
+ public bool Contains(double value, ToleranceContext? toleranceContext = null)
+ {
+ if (!double.IsFinite(value))
+ {
+ return false;
+ }
+
+ var context = toleranceContext ?? ToleranceContext.Default;
+ return ToleranceMath.GreaterThanOrAlmostEqual(value, Start, context)
+ && ToleranceMath.LessThanOrAlmostEqual(value, End, context);
+ }
+}
diff --git a/Aetheris.Kernel.Core/Geometry/Surfaces/ConeSurface.cs b/Aetheris.Kernel.Core/Geometry/Surfaces/ConeSurface.cs
new file mode 100644
index 00000000..b60b3117
--- /dev/null
+++ b/Aetheris.Kernel.Core/Geometry/Surfaces/ConeSurface.cs
@@ -0,0 +1,62 @@
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Geometry.Surfaces;
+
+/// <summary>
+/// Right circular cone parameterization with apex at Apex:
+/// S(u,v) = Apex + v * Axis + (v * tan(SemiAngleRadians)) * (cos(u) * XAxis + sin(u) * YAxis), for v >= 0.
+/// </summary>
+public readonly record struct ConeSurface
+{
+ private readonly Direction3D _xAxis;
+ private readonly Direction3D _yAxis;
+
+ public ConeSurface(Point3D apex, Direction3D axis, double semiAngleRadians, Direction3D referenceAxis)
+ {
+ if (!double.IsFinite(semiAngleRadians) || semiAngleRadians <= 0d || semiAngleRadians >= (double.Pi / 2d))
+ {
+ throw new ArgumentOutOfRangeException(nameof(semiAngleRadians), "Semi-angle must be finite and in the range (0, pi/2). ");
+ }
+
+ var axisVector = axis.ToVector();
+ var reference = referenceAxis.ToVector();
+ var projected = reference - (axisVector * reference.Dot(axisVector));
+
+ if (!Direction3D.TryCreate(projected, out var xAxis))
+ {
+ throw new ArgumentOutOfRangeException(nameof(referenceAxis), "Reference axis must not be parallel to cone axis.");
+ }
+
+ if (!Direction3D.TryCreate(axisVector.Cross(xAxis.ToVector()), out var yAxis))
+ {
+ throw new ArgumentOutOfRangeException(nameof(axis), "Axis must define a valid cone frame.");
+ }
+
+ Apex = apex;
+ Axis = axis;
+ SemiAngleRadians = semiAngleRadians;
+ _xAxis = xAxis;
+ _yAxis = yAxis;
+ }
+
+ public Point3D Apex { get; }
+
+ public Direction3D Axis { get; }
+
+ public double SemiAngleRadians { get; }
+
+ public Point3D Evaluate(double u, double v)
+ {
+ var radialMagnitude = v * double.Tan(SemiAngleRadians);
+ var radial = (_xAxis.ToVector() * (radialMagnitude * double.Cos(u))) + (_yAxis.ToVector() * (radialMagnitude * double.Sin(u)));
+ var axial = Axis.ToVector() * v;
+ return Apex + axial + radial;
+ }
+
+ public Direction3D Normal(double u)
+ {
+ var radial = (_xAxis.ToVector() * double.Cos(u)) + (_yAxis.ToVector() * double.Sin(u));
+ var outward = radial - (Axis.ToVector() * double.Tan(SemiAngleRadians));
+ return Direction3D.Create(outward);
+ }
+}
diff --git a/Aetheris.Kernel.Core/Geometry/Surfaces/CylinderSurface.cs b/Aetheris.Kernel.Core/Geometry/Surfaces/CylinderSurface.cs
new file mode 100644
index 00000000..9a6abd68
--- /dev/null
+++ b/Aetheris.Kernel.Core/Geometry/Surfaces/CylinderSurface.cs
@@ -0,0 +1,64 @@
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Geometry.Surfaces;
+
+/// <summary>
+/// Cylinder parameterization: S(u,v) = Origin + v * Axis + Radius * (cos(u) * XAxis + sin(u) * YAxis),
+/// where YAxis = Axis x XAxis.
+/// </summary>
+public readonly record struct CylinderSurface
+{
+ private readonly Direction3D _xAxis;
+ private readonly Direction3D _yAxis;
+
+ public CylinderSurface(Point3D origin, Direction3D axis, double radius, Direction3D referenceAxis)
+ {
+ if (!double.IsFinite(radius) || radius <= 0d)
+ {
+ throw new ArgumentOutOfRangeException(nameof(radius), "Radius must be finite and greater than zero.");
+ }
+
+ var axisVector = axis.ToVector();
+ var reference = referenceAxis.ToVector();
+ var projected = reference - (axisVector * reference.Dot(axisVector));
+
+ if (!Direction3D.TryCreate(projected, out var xAxis))
+ {
+ throw new ArgumentOutOfRangeException(nameof(referenceAxis), "Reference axis must not be parallel to cylinder axis.");
+ }
+
+ if (!Direction3D.TryCreate(axisVector.Cross(xAxis.ToVector()), out var yAxis))
+ {
+ throw new ArgumentOutOfRangeException(nameof(axis), "Axis must define a valid cylinder frame.");
+ }
+
+ Origin = origin;
+ Axis = axis;
+ Radius = radius;
+ _xAxis = xAxis;
+ _yAxis = yAxis;
+ }
+
+ public Point3D Origin { get; }
+
+ public Direction3D Axis { get; }
+
+ public double Radius { get; }
+
+ public Direction3D XAxis => _xAxis;
+
+ public Direction3D YAxis => _yAxis;
+
+ public Point3D Evaluate(double u, double v)
+ {
+ var radial = (_xAxis.ToVector() * (Radius * double.Cos(u))) + (_yAxis.ToVector() * (Radius * double.Sin(u)));
+ var axial = Axis.ToVector() * v;
+ return Origin + axial + radial;
+ }
+
+ public Direction3D Normal(double u)
+ {
+ var radial = (_xAxis.ToVector() * double.Cos(u)) + (_yAxis.ToVector() * double.Sin(u));
+ return Direction3D.Create(radial);
+ }
+}
diff --git a/Aetheris.Kernel.Core/Geometry/Surfaces/PlaneSurface.cs b/Aetheris.Kernel.Core/Geometry/Surfaces/PlaneSurface.cs
new file mode 100644
index 00000000..8788a366
--- /dev/null
+++ b/Aetheris.Kernel.Core/Geometry/Surfaces/PlaneSurface.cs
@@ -0,0 +1,44 @@
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Geometry.Surfaces;
+
+/// <summary>
+/// Plane parameterization: S(u,v) = Origin + u * UAxis + v * VAxis, with VAxis = Normal x UAxis.
+/// </summary>
+public readonly record struct PlaneSurface
+{
+ private readonly Direction3D _uAxis;
+ private readonly Direction3D _vAxis;
+
+ public PlaneSurface(Point3D origin, Direction3D normal, Direction3D uAxis)
+ {
+ var n = normal.ToVector();
+ var uReference = uAxis.ToVector();
+ var projected = uReference - (n * uReference.Dot(n));
+
+ if (!Direction3D.TryCreate(projected, out var normalizedU))
+ {
+ throw new ArgumentOutOfRangeException(nameof(uAxis), "U axis must not be parallel to normal.");
+ }
+
+ if (!Direction3D.TryCreate(n.Cross(normalizedU.ToVector()), out var normalizedV))
+ {
+ throw new ArgumentOutOfRangeException(nameof(normal), "Normal must define a valid plane basis.");
+ }
+
+ Origin = origin;
+ Normal = normal;
+ _uAxis = normalizedU;
+ _vAxis = normalizedV;
+ }
+
+ public Point3D Origin { get; }
+
+ public Direction3D Normal { get; }
+
+ public Direction3D UAxis => _uAxis;
+
+ public Direction3D VAxis => _vAxis;
+
+ public Point3D Evaluate(double u, double v) => Origin + (_uAxis.ToVector() * u) + (_vAxis.ToVector() * v);
+}
diff --git a/Aetheris.Kernel.Core/Geometry/Surfaces/SphereSurface.cs b/Aetheris.Kernel.Core/Geometry/Surfaces/SphereSurface.cs
new file mode 100644
index 00000000..760b657c
--- /dev/null
+++ b/Aetheris.Kernel.Core/Geometry/Surfaces/SphereSurface.cs
@@ -0,0 +1,68 @@
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Geometry.Surfaces;
+
+/// <summary>
+/// Sphere parameterization:
+/// S(u,v) = Center + Radius * (cos(v) * cos(u) * XAxis + cos(v) * sin(u) * YAxis + sin(v) * Axis),
+/// where u is azimuth around Axis and v is elevation from the equatorial plane.
+/// </summary>
+public readonly record struct SphereSurface
+{
+ private readonly Direction3D _xAxis;
+ private readonly Direction3D _yAxis;
+
+ public SphereSurface(Point3D center, Direction3D axis, double radius, Direction3D referenceAxis)
+ {
+ if (!double.IsFinite(radius) || radius <= 0d)
+ {
+ throw new ArgumentOutOfRangeException(nameof(radius), "Radius must be finite and greater than zero.");
+ }
+
+ var axisVector = axis.ToVector();
+ var reference = referenceAxis.ToVector();
+ var projected = reference - (axisVector * reference.Dot(axisVector));
+
+ if (!Direction3D.TryCreate(projected, out var xAxis))
+ {
+ throw new ArgumentOutOfRangeException(nameof(referenceAxis), "Reference axis must not be parallel to sphere axis.");
+ }
+
+ if (!Direction3D.TryCreate(axisVector.Cross(xAxis.ToVector()), out var yAxis))
+ {
+ throw new ArgumentOutOfRangeException(nameof(axis), "Axis must define a valid sphere frame.");
+ }
+
+ Center = center;
+ Axis = axis;
+ Radius = radius;
+ _xAxis = xAxis;
+ _yAxis = yAxis;
+ }
+
+ public Point3D Center { get; }
+
+ public Direction3D Axis { get; }
+
+ public double Radius { get; }
+
+ public Point3D Evaluate(double u, double v)
+ {
+ var cosV = double.Cos(v);
+ var sinV = double.Sin(v);
+ var cosU = double.Cos(u);
+ var sinU = double.Sin(u);
+
+ var offset = (_xAxis.ToVector() * (Radius * cosV * cosU))
+ + (_yAxis.ToVector() * (Radius * cosV * sinU))
+ + (Axis.ToVector() * (Radius * sinV));
+
+ return Center + offset;
+ }
+
+ public Direction3D Normal(double u, double v)
+ {
+ var point = Evaluate(u, v);
+ return Direction3D.Create(point - Center);
+ }
+}
diff --git a/docs/architecture-overview.md b/docs/architecture-overview.md
index fd85aed1..e1e78a93 100644
--- a/docs/architecture-overview.md
+++ b/docs/architecture-overview.md
@@ -16,3 +16,5 @@ This package map is directional only and may evolve with milestone outcomes.
- Boundaries are favored over deep abstraction in early milestones.
- Kernel remains independent from UI and persistence concerns.
- Kernel operations should return structured result/diagnostic envelopes for expected outcomes instead of throwing ad hoc exceptions.
+
+- Until M06, analytic geometry primitives remain separate from topology entities; binding/association is intentionally deferred.
diff --git a/docs/milestones.md b/docs/milestones.md
index ce234fd0..ae419ad2 100644
--- a/docs/milestones.md
+++ b/docs/milestones.md
@@ -36,3 +36,12 @@
- [x] Add reference-integrity validator v0 (dangling references and local loop/coedge consistency only).
- [x] Add unit tests, including a cube-like topology graph skeleton validation test.
- [x] Explicitly defer geometry binding and manifold-level correctness checks to future milestones.
+
+
+## M05 — Analytic Geometry Primitives v1 (No Topology Binding)
+
+- [x] Add minimal analytic geometry parameter helpers for stable parameter-domain usage (`ParameterInterval`).
+- [x] Add exact analytic curve primitives (`Line3Curve`, `Circle3Curve`) with explicit parameterization conventions and evaluation APIs.
+- [x] Add exact analytic surface primitives (`PlaneSurface`, `CylinderSurface`, `SphereSurface`, `ConeSurface`) with constructor validation and documented parameter conventions.
+- [x] Add focused geometry unit tests that lock evaluation behavior/orientation conventions and invalid-construction guardrails.
+- [x] Explicitly defer topology-geometry binding to M06.