Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Preserve helical trims and reject unsupported rational B-splines

Yuechen Liccafac976121
diff --git a/Aetheris.Kernel.Core.Tests/Brep/BrepHelicalRibTests.cs b/Aetheris.Kernel.Core.Tests/Brep/BrepHelicalRibTests.cs
new file mode 100644
index 00000000..1c1b8bea
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Brep/BrepHelicalRibTests.cs
@@ -0,0 +1,235 @@
+using Aetheris.Kernel.Core.Brep;
+using Aetheris.Kernel.Core.Brep.Features;
+using Aetheris.Kernel.Core.Brep.Tessellation;
+using Aetheris.Kernel.Core.Geometry;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Step242;
+using System.Diagnostics;
+using System.Text;
+using System.Text.Json;
+
+namespace Aetheris.Kernel.Core.Tests.Brep;
+
+public sealed class BrepHelicalRibTests
+{
+ [Theory]
+ [InlineData(1)]
+ [InlineData(4)]
+ [InlineData(24)]
+ public void CompleteTurnRibProducesOneClosedManifoldBody(int turns)
+ {
+ const double pitch = 1.25d;
+ const double width = 1.1d;
+ var span = turns * pitch;
+ var parameters = new HelicalRibParameters(Point3D.Origin,
+ Direction3D.Create(new Vector3D(0, 0, 1)),
+ Direction3D.Create(new Vector3D(1, 0, 0)),
+ -1d, span + width + 1d, 3.2d, 4d, pitch,
+ width / 2d, span + width / 2d, width, 0.1d);
+ var rib = HelicalRibGeometry.Create(parameters);
+ Assert.True(rib.IsSuccess);
+ var result = BrepHelicalRib.Create(rib.Value);
+ Assert.True(result.IsSuccess, string.Join(Environment.NewLine, result.Diagnostics));
+ Assert.Equal(4 * turns + 5, result.Value.Body.Topology.Faces.Count());
+ Assert.Equal(8 * turns + 9, result.Value.Body.Topology.Edges.Count());
+ Assert.Equal(4 * turns + 6, result.Value.Body.Topology.Vertices.Count());
+ Assert.Same(rib.Value, result.Value.Authority);
+ Assert.Equal(3 * turns, result.Value.QualifiedSideFaces.Count);
+ Assert.All(result.Value.QualifiedSideFaces.Values, surface =>
+ {
+ Assert.Equal(parameters.PitchMm, surface.Authority.Parameters.PitchMm);
+ Assert.True(surface.CertifiedDeviationBoundMm <= surface.RequestedToleranceMm);
+ });
+ foreach (var edge in result.Value.Body.Topology.Edges)
+ {
+ var uses = result.Value.Body.Topology.Coedges.Where(item => item.EdgeId == edge.Id).ToArray();
+ Assert.Equal(2, uses.Length);
+ Assert.NotEqual(uses[0].IsReversed, uses[1].IsReversed);
+ }
+ var pcurves = BrepPcurveValidator.Validate(result.Value.Body, 1e-6d);
+ Assert.True(pcurves.IsValid, string.Join(Environment.NewLine, pcurves.Diagnostics.Take(12)));
+ }
+
+ [Theory]
+ [InlineData(1)]
+ [InlineData(24)]
+ public void CanonicalRibExportsAndReimports(int turns)
+ {
+ const double width = 1.1d;
+ var span = turns * 1.25d;
+ var parameters = new HelicalRibParameters(Point3D.Origin,
+ Direction3D.Create(new Vector3D(0, 0, 1)),
+ Direction3D.Create(new Vector3D(1, 0, 0)),
+ -1d, span + width + 1d, 3.2d, 4d, 1.25d,
+ width / 2d, span + width / 2d, width, 0.1d);
+ var rib = HelicalRibGeometry.Create(parameters).Value;
+ var body = BrepHelicalRib.Create(rib).Value.Body;
+ var export = Step242Exporter.ExportBody(body, new Step242ExportOptions { BrepExportPreflightMode = BrepExportPreflightMode.Enforce });
+ Assert.True(export.IsSuccess, string.Join(Environment.NewLine, export.Diagnostics));
+ var imported = Step242Importer.ImportBody(export.Value);
+ Assert.True(imported.IsSuccess, string.Join(Environment.NewLine, imported.Diagnostics));
+ Assert.True(BrepExportPreflight.Validate(imported.Value).IsValid);
+ Assert.Equal(body.Topology.Faces.Count(), imported.Value.Topology.Faces.Count());
+ var points = imported.Value.Topology.Vertices.Select(vertex =>
+ {
+ Assert.True(imported.Value.TryGetVertexPoint(vertex.Id, out var point));
+ return point;
+ }).ToArray();
+ Assert.Contains(points, point => double.Abs(point.X - 4d) < 1e-6d && double.Abs(point.Z - 0.5d) < 1e-6d);
+ Assert.Contains(points, point => double.Abs(point.X - 3.2d) < 1e-6d && double.Abs(point.Z) < 1e-6d);
+ Assert.Contains(points, point => double.Abs(point.X - 3.2d) < 1e-6d && double.Abs(point.Z - 1.25d) < 1e-6d);
+ Assert.Contains(points, point => double.Abs(point.Z + 1d) < 1e-6d);
+ Assert.Contains(points, point => double.Abs(point.Z - (span + width + 1d)) < 1e-6d);
+ }
+
+ [Theory]
+ [InlineData(1)]
+ [InlineData(24)]
+ public void DisplayTessellatorCoversEveryFace(int turns)
+ {
+ const double width = 1.1d;
+ var span = turns * 1.25d;
+ var parameters = new HelicalRibParameters(Point3D.Origin,
+ Direction3D.Create(new Vector3D(0, 0, 1)),
+ Direction3D.Create(new Vector3D(1, 0, 0)),
+ -1d, span + width + 1d, 3.2d, 4d, 1.25d,
+ width / 2d, span + width / 2d, width, 0.1d);
+ var body = BrepHelicalRib.Create(HelicalRibGeometry.Create(parameters).Value).Value.Body;
+ var mesh = BrepDisplayTessellator.TessellateBounded(body, executionTimeout: TimeSpan.FromSeconds(30));
+ Assert.True(mesh.IsSuccess, string.Join(Environment.NewLine, mesh.Diagnostics.Take(12)));
+ Assert.Equal(body.Topology.Faces.Count(), mesh.Value.FacePatches.Count);
+ Assert.All(mesh.Value.FacePatches, patch => Assert.NotEmpty(patch.TriangleIndices));
+ var rootRadius = 3.2d;
+ var crestRadius = 4d;
+ var widthSlope = (0.1d - width) / (crestRadius - rootRadius);
+ var ribSectionMoment = width * (crestRadius * crestRadius - rootRadius * rootRadius) / 2d
+ + widthSlope * ((double.Pow(crestRadius, 3) - double.Pow(rootRadius, 3)) / 3d
+ - rootRadius * (crestRadius * crestRadius - rootRadius * rootRadius) / 2d);
+ var expectedVolume = double.Pi * rootRadius * rootRadius * (span + width + 2d)
+ + turns * 2d * double.Pi * ribSectionMoment;
+ Assert.InRange(SignedMeshVolume(mesh.Value) / expectedVolume, 0.99d, 1.01d);
+ }
+
+ [Theory]
+ [InlineData(1.25d, 4d, false)]
+ [InlineData(1.5d, 4d, false)]
+ [InlineData(1.25d, 4.2d, false)]
+ [InlineData(1.25d, 4d, true)]
+ public void ChangedPitchDepthAndAxisRemainManifold(double pitch, double crestRadius, bool rotated)
+ {
+ var axis = rotated ? Direction3D.Create(new Vector3D(0, 1, 0)) : Direction3D.Create(new Vector3D(0, 0, 1));
+ var radial = rotated ? Direction3D.Create(new Vector3D(0, 0, 1)) : Direction3D.Create(new Vector3D(1, 0, 0));
+ var parameters = new HelicalRibParameters(new Point3D(10, 20, 30), axis, radial,
+ -1d, 4d * pitch + 2.1d, 3.2d, crestRadius, pitch,
+ 0.55d, 4d * pitch + 0.55d, 1.1d, 0.1d, 0.4d);
+ var rib = HelicalRibGeometry.Create(parameters);
+ Assert.True(rib.IsSuccess, string.Join(Environment.NewLine, rib.Diagnostics));
+ var result = BrepHelicalRib.Create(rib.Value);
+ Assert.True(result.IsSuccess, string.Join(Environment.NewLine, result.Diagnostics));
+ Assert.Equal(21, result.Value.Body.Topology.Faces.Count());
+ Assert.Equal(3, result.Value.SeamSplits);
+ Assert.Equal(pitch, result.Value.Authority.MinimumAdjacentTurnClearanceMm + 1.1d, 9);
+ Assert.True(BrepPcurveValidator.Validate(result.Value.Body, 1e-6d).IsValid);
+ }
+
+ [Fact]
+ public void RejectsSupportEndContactBeforeTopologyAssembly()
+ {
+ var parameters = new HelicalRibParameters(Point3D.Origin,
+ Direction3D.Create(new Vector3D(0, 0, 1)),
+ Direction3D.Create(new Vector3D(1, 0, 0)),
+ 0d, 6.1d, 3.2d, 4d, 1.25d, 0.55d, 5.55d, 1.1d, 0.1d);
+ var rib = HelicalRibGeometry.Create(parameters);
+ Assert.True(rib.IsSuccess);
+ var result = BrepHelicalRib.Create(rib.Value);
+ Assert.False(result.IsSuccess);
+ Assert.Contains(result.Diagnostics, diagnostic => diagnostic.Message.Contains("support-end-contact-unsupported"));
+ }
+
+ [Fact]
+ public void WriteCanonicalWitnessWhenRequested()
+ {
+ var output = Environment.GetEnvironmentVariable("AETHERIS_HELICAL_RIB_ARTIFACT_DIR");
+ if (string.IsNullOrWhiteSpace(output)) return;
+ Directory.CreateDirectory(output);
+ var parameters = new HelicalRibParameters(Point3D.Origin,
+ Direction3D.Create(new Vector3D(0, 0, 1)),
+ Direction3D.Create(new Vector3D(1, 0, 0)),
+ -1d, 32.1d, 3.2d, 4d, 1.25d,
+ 0.55d, 30.55d, 1.1d, 0.1d);
+ var timer = Stopwatch.StartNew();
+ var rib = HelicalRibGeometry.Create(parameters).Value;
+ var result = BrepHelicalRib.Create(rib);
+ Assert.True(result.IsSuccess, string.Join(Environment.NewLine, result.Diagnostics));
+ var buildMs = timer.Elapsed.TotalMilliseconds;
+ timer.Restart();
+ var mesh = BrepDisplayTessellator.TessellateBounded(result.Value.Body,
+ executionTimeout: TimeSpan.FromSeconds(60));
+ Assert.True(mesh.IsSuccess, string.Join(Environment.NewLine, mesh.Diagnostics));
+ var tessellationMs = timer.Elapsed.TotalMilliseconds;
+ timer.Restart();
+ var step = Step242Exporter.ExportBody(result.Value.Body,
+ new Step242ExportOptions { BrepExportPreflightMode = BrepExportPreflightMode.Enforce });
+ Assert.True(step.IsSuccess, string.Join(Environment.NewLine, step.Diagnostics));
+ var exportMs = timer.Elapsed.TotalMilliseconds;
+ var stepPath = Path.Combine(output, "helical-rib-24.step");
+ File.WriteAllText(stepPath, step.Value);
+ timer.Restart();
+ var imported = Step242Importer.ImportBody(step.Value);
+ Assert.True(imported.IsSuccess, string.Join(Environment.NewLine, imported.Diagnostics));
+ var reimportMs = timer.Elapsed.TotalMilliseconds;
+ var buildTimes = new List<object>();
+ foreach (var turns in new[] { 1, 4, 24 })
+ {
+ var variant = parameters with
+ {
+ AxialEndMm = turns * 1.25d + 0.55d,
+ SupportAxialMaxMm = turns * 1.25d + 2.1d
+ };
+ timer.Restart();
+ var variantResult = BrepHelicalRib.Create(HelicalRibGeometry.Create(variant).Value);
+ Assert.True(variantResult.IsSuccess, string.Join(Environment.NewLine, variantResult.Diagnostics));
+ buildTimes.Add(new { turns, milliseconds = timer.Elapsed.TotalMilliseconds });
+ }
+ var obj = new StringBuilder();
+ var vertexOffset = 1;
+ foreach (var patch in mesh.Value.FacePatches)
+ {
+ obj.AppendLine($"g Face_{patch.FaceId.Value}");
+ foreach (var point in patch.Positions)
+ obj.AppendLine(FormattableString.Invariant($"v {point.X:R} {point.Y:R} {point.Z:R}"));
+ for (var i = 0; i < patch.TriangleIndices.Count; i += 3)
+ obj.AppendLine($"f {vertexOffset + patch.TriangleIndices[i]} {vertexOffset + patch.TriangleIndices[i + 1]} {vertexOffset + patch.TriangleIndices[i + 2]}");
+ vertexOffset += patch.Positions.Count;
+ }
+ File.WriteAllText(Path.Combine(output, "helical-rib-24.obj"), obj.ToString());
+ var report = new
+ {
+ turns = 24,
+ faces = result.Value.Body.Topology.Faces.Count(),
+ edges = result.Value.Body.Topology.Edges.Count(),
+ vertices = result.Value.Body.Topology.Vertices.Count(),
+ seamSplits = result.Value.SeamSplits,
+ triangles = mesh.Value.FacePatches.Sum(patch => patch.TriangleIndices.Count / 3),
+ buildMs, tessellationMs, exportMs, reimportMs, buildTimes,
+ stepBytes = new FileInfo(stepPath).Length,
+ signedMeshVolume = SignedMeshVolume(mesh.Value)
+ };
+ File.WriteAllText(Path.Combine(output, "helical-rib-24.json"), JsonSerializer.Serialize(report, new JsonSerializerOptions { WriteIndented = true }));
+ }
+
+ private static double SignedMeshVolume(DisplayTessellationResult mesh)
+ {
+ var volume = 0d;
+ foreach (var patch in mesh.FacePatches)
+ for (var i = 0; i < patch.TriangleIndices.Count; i += 3)
+ {
+ var a = patch.Positions[patch.TriangleIndices[i]];
+ var b = patch.Positions[patch.TriangleIndices[i + 1]];
+ var c = patch.Positions[patch.TriangleIndices[i + 2]];
+ volume += new Vector3D(a.X, a.Y, a.Z).Dot(
+ new Vector3D(b.X, b.Y, b.Z).Cross(new Vector3D(c.X, c.Y, c.Z))) / 6d;
+ }
+ return volume;
+ }
+}
diff --git a/Aetheris.Kernel.Core.Tests/Geometry/HelicalRibGeometryTests.cs b/Aetheris.Kernel.Core.Tests/Geometry/HelicalRibGeometryTests.cs
new file mode 100644
index 00000000..b111f896
--- /dev/null
+++ b/Aetheris.Kernel.Core.Tests/Geometry/HelicalRibGeometryTests.cs
@@ -0,0 +1,150 @@
+using Aetheris.Kernel.Core.Geometry;
+using Aetheris.Kernel.Core.Geometry.Curves;
+using Aetheris.Kernel.Core.Geometry.Surfaces;
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Tests.Geometry;
+
+public sealed class HelicalRibGeometryTests
+{
+ private static readonly Direction3D Z = Direction3D.Create(new Vector3D(0, 0, 1));
+ private static readonly Direction3D X = Direction3D.Create(new Vector3D(1, 0, 0));
+
+ private static HelicalRibParameters Witness(double span = 30d, double pitch = 1.25d,
+ double crestRadius = 4d, double rootWidth = 1.1d) => new(
+ Point3D.Origin, Z, X, 0d, span + rootWidth,
+ 3.2d, crestRadius, pitch, rootWidth / 2d,
+ span + rootWidth / 2d, rootWidth, 0.1d);
+
+ [Fact]
+ public void OneAndManyTurnsHaveExactFrameProfileAndDerivedLead()
+ {
+ foreach (var span in new[] { 1.25d, 30d })
+ {
+ var result = HelicalRibGeometry.Create(Witness(span));
+ Assert.True(result.IsSuccess, string.Join("; ", result.Diagnostics));
+ var rib = result.Value;
+ Assert.Equal(span / 1.25d, rib.Turns, 12);
+ Assert.Equal(1.25d, rib.LeadMm);
+ Assert.Equal(0.15d, rib.MinimumAdjacentTurnClearanceMm, 12);
+
+ foreach (var role in Enum.GetValues<HelicalRibBoundaryRole>())
+ {
+ var helix = rib.Boundary(role);
+ var first = helix.Evaluate(helix.StartAngleRadians);
+ var last = helix.Evaluate(helix.EndAngleRadians);
+ Assert.Equal(span, last.Z - first.Z, 10);
+ Assert.Equal(helix.RadiusMm, double.Hypot(first.X, first.Y), 10);
+ Assert.Equal(helix.RadiusMm, double.Hypot(last.X, last.Y), 10);
+ }
+ var mid = rib.Parameters.StartAngleRadians + (rib.EndAngleRadians - rib.Parameters.StartAngleRadians) * 0.37d;
+ Assert.Equal(rib.Boundary(HelicalRibBoundaryRole.LeadingCrest).Evaluate(mid),
+ rib.Evaluate(HelicalRibSideRole.Crest, mid, 0d));
+ Assert.Equal(rib.Boundary(HelicalRibBoundaryRole.TrailingCrest).Evaluate(mid),
+ rib.Evaluate(HelicalRibSideRole.Crest, mid, 1d));
+ Assert.Equal(4, rib.CapCorners(false).Count);
+ }
+ }
+
+ [Fact]
+ public void PitchLengthDepthAndRigidFrameChangeGeometryDeterministically()
+ {
+ var original = HelicalRibGeometry.Create(Witness()).Value;
+ var faster = HelicalRibGeometry.Create(Witness(pitch: 1.5d)).Value;
+ var longer = HelicalRibGeometry.Create(Witness(span: 35d)).Value;
+ var deeper = HelicalRibGeometry.Create(Witness(crestRadius: 4.2d)).Value;
+ Assert.Equal(24d, original.Turns);
+ Assert.Equal(20d, faster.Turns);
+ Assert.Equal(28d, longer.Turns);
+ Assert.Equal(4.2d, deeper.Boundary(HelicalRibBoundaryRole.LeadingCrest).RadiusMm);
+ Assert.Equal(3.2d, deeper.Boundary(HelicalRibBoundaryRole.LeadingRoot).RadiusMm);
+
+ var transformed = Witness() with {
+ AxisOrigin = new Point3D(7d, -4d, 2d),
+ Axis = Direction3D.Create(new Vector3D(1d, 0d, 0d)),
+ StartRadial = Direction3D.Create(new Vector3D(0d, 1d, 0d))
+ };
+ var rotated = HelicalRibGeometry.Create(transformed).Value;
+ var p = rotated.Boundary(HelicalRibBoundaryRole.LeadingRoot).Evaluate(rotated.Parameters.StartAngleRadians);
+ Assert.Equal(7d + transformed.AxialStartMm - transformed.RootWidthMm / 2d, p.X, 10);
+ Assert.Equal(-4d + 3.2d, p.Y, 10);
+ Assert.Equal(2d, p.Z, 10);
+ }
+
+ [Theory]
+ [InlineData(0d, 30d, 1.1d, "pitch")]
+ [InlineData(-1d, 30d, 1.1d, "pitch")]
+ [InlineData(1.25d, 0d, 1.1d, "span")]
+ [InlineData(1.25d, 30d, 1.25d, "adjacent-turn-overlap")]
+ public void InvalidIntentHasSpecificDiagnostic(double pitch, double span, double rootWidth, string code)
+ {
+ var p = Witness(span, pitch, rootWidth: rootWidth);
+ var result = HelicalRibGeometry.Create(p);
+ Assert.False(result.IsSuccess);
+ Assert.Contains(result.Diagnostics, d => d.Message.Contains($"helical-rib-{code}", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void OutOfSupportAndInvertedDepthAreRejected()
+ {
+ var outside = HelicalRibGeometry.Create(Witness() with { SupportAxialMaxMm = 30d });
+ var inverted = HelicalRibGeometry.Create(Witness(crestRadius: 3.2d));
+ Assert.Contains(outside.Diagnostics, d => d.Message.Contains("support-extent", StringComparison.Ordinal));
+ Assert.Contains(inverted.Diagnostics, d => d.Message.Contains("radii", StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void PeriodicAngularWrapPreservesRadialPositionAndAdvancesOnePitch()
+ {
+ var rib = HelicalRibGeometry.Create(Witness()).Value;
+ var helix = rib.Boundary(HelicalRibBoundaryRole.TrailingCrest);
+ var first = helix.Evaluate(helix.StartAngleRadians);
+ var next = helix.Evaluate(helix.StartAngleRadians + 2d * double.Pi);
+ Assert.InRange(double.Abs(first.X - next.X), 0d, 1e-12d);
+ Assert.InRange(double.Abs(first.Y - next.Y), 0d, 1e-12d);
+ Assert.Equal(1.25d, next.Z - first.Z, 10);
+ }
+
+ [Fact]
+ public void NonRationalBoundaryRealizationIsCertifiedAndRepeatable()
+ {
+ var rib = HelicalRibGeometry.Create(Witness()).Value;
+ var helix = rib.Boundary(HelicalRibBoundaryRole.LeadingCrest);
+ var first = HelicalRibBoundaryRealizer.Realize(helix);
+ var second = HelicalRibBoundaryRealizer.Realize(helix);
+ Assert.True(first.IsSuccess, string.Join("; ", first.Diagnostics));
+ Assert.True(second.IsSuccess);
+ Assert.InRange(first.Value.CertifiedDeviationBoundMm, 0d, 1e-6d);
+ Assert.Equal(first.Value.Curve.ControlPoints, second.Value.Curve.ControlPoints);
+ Assert.True(first.Value.SegmentCount > 20);
+ for (var i = 0; i <= 80; i++)
+ {
+ var angle = helix.StartAngleRadians + (helix.EndAngleRadians - helix.StartAngleRadians) * i / 80d;
+ var deviation = (first.Value.Curve.Evaluate(angle) - helix.Evaluate(angle)).Length;
+ Assert.InRange(deviation, 0d, first.Value.CertifiedDeviationBoundMm);
+ }
+ }
+
+ [Fact]
+ public void AllThreeRuledHelicalSidesRemainWithinCertifiedSurfaceBound()
+ {
+ var rib = HelicalRibGeometry.Create(Witness()).Value;
+ foreach (var role in Enum.GetValues<HelicalRibSideRole>())
+ {
+ var realized = HelicalRibSurfaceRealizer.Realize(rib, role);
+ Assert.True(realized.IsSuccess, string.Join("; ", realized.Diagnostics));
+ Assert.InRange(realized.Value.CertifiedDeviationBoundMm, 0d, 1e-6d);
+ Assert.False(realized.Value.Surface.IsRational);
+ for (var i = 0; i <= 40; i++)
+ {
+ var angle = rib.Parameters.StartAngleRadians
+ + (rib.EndAngleRadians - rib.Parameters.StartAngleRadians) * i / 40d;
+ foreach (var v in new[] { 0d, 0.3d, 1d })
+ {
+ var error = (realized.Value.Surface.Evaluate(angle, v) - rib.Evaluate(role, angle, v)).Length;
+ Assert.InRange(error, 0d, realized.Value.CertifiedDeviationBoundMm);
+ }
+ }
+ }
+ }
+}
diff --git a/Aetheris.Kernel.Core/Brep/Features/BrepHelicalRib.cs b/Aetheris.Kernel.Core/Brep/Features/BrepHelicalRib.cs
new file mode 100644
index 00000000..795c754a
--- /dev/null
+++ b/Aetheris.Kernel.Core/Brep/Features/BrepHelicalRib.cs
@@ -0,0 +1,283 @@
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Geometry;
+using Aetheris.Kernel.Core.Geometry.Curves;
+using Aetheris.Kernel.Core.Geometry.Surfaces;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Results;
+using Aetheris.Kernel.Core.Topology;
+
+namespace Aetheris.Kernel.Core.Brep.Features;
+
+public sealed record BrepHelicalRibResult(
+ HelicalRibGeometry Authority,
+ BrepBody Body,
+ IReadOnlyDictionary<FaceId, string> FaceRoles,
+ IReadOnlyDictionary<EdgeId, string> EdgeRoles,
+ IReadOnlyDictionary<FaceId, QualifiedHelicalRibSurface> QualifiedSideFaces,
+ int SeamSplits);
+
+/// <summary>
+/// Direct known-topology construction for complete-turn, single-start ribs.
+/// The cylinder skin is partitioned into N+1 exposed bands; no support face
+/// remains beneath the rib. This does not invoke a sweep or Boolean operator.
+/// </summary>
+public static class BrepHelicalRib
+{
+ private readonly record struct Use(EdgeId Edge, bool Reverse, PcurveGeometry? Pcurve = null);
+
+ public static KernelResult<BrepHelicalRibResult> Create(HelicalRibGeometry rib)
+ {
+ ArgumentNullException.ThrowIfNull(rib);
+ var turnsRounded = double.Round(rib.Turns);
+ if (turnsRounded < 1d || turnsRounded > 40d || double.Abs(rib.Turns - turnsRounded) > 1e-9d)
+ return Failure("complete-turns-required", "X1 admits one to forty complete turns; the rib axial span must be an integer multiple of pitch.");
+ var p = rib.Parameters;
+ if (p.AxialStartMm - p.RootWidthMm / 2d - p.SupportAxialMinMm <= 1e-6d
+ || p.SupportAxialMaxMm - p.AxialEndMm - p.RootWidthMm / 2d <= 1e-6d)
+ return Failure("support-end-contact-unsupported", "X1 requires exposed support-cylinder margins before and after the rib footprint.");
+ try { return Build(rib, (int)turnsRounded); }
+ catch (Exception ex) when (ex is ArgumentException or InvalidOperationException or OverflowException)
+ {
+ return Failure("construction-failed", ex.Message);
+ }
+ }
+
+ private static KernelResult<BrepHelicalRibResult> Build(HelicalRibGeometry rib, int turns)
+ {
+ var p = rib.Parameters;
+ var builder = new TopologyBuilder();
+ var geometry = new BrepGeometryStore();
+ var bindings = new BrepBindingModel();
+ var points = new Dictionary<VertexId, Point3D>();
+ var faceRoles = new Dictionary<FaceId, string>();
+ var edgeRoles = new Dictionary<EdgeId, string>();
+ var qualifiedSideFaces = new Dictionary<FaceId, QualifiedHelicalRibSurface>();
+ var faces = new List<FaceId>();
+ var nextCurve = 1;
+ var nextSurface = 1;
+ var cylinderId = new SurfaceGeometryId(nextSurface++);
+ var seamRadial = Direction3D.Create(
+ p.StartRadial.ToVector() * double.Cos(p.StartAngleRadians)
+ + p.Axis.ToVector().Cross(p.StartRadial.ToVector()) * double.Sin(p.StartAngleRadians));
+ var cylinder = new CylinderSurface(p.AxisOrigin, p.Axis, p.RootRadiusMm, seamRadial);
+ geometry.AddSurface(cylinderId, SurfaceGeometry.FromCylinder(cylinder));
+
+ VertexId Vertex(Point3D point)
+ {
+ var id = builder.AddVertex();
+ points.Add(id, point);
+ return id;
+ }
+
+ EdgeId Edge(VertexId from, VertexId to, CurveGeometry curve, ParameterInterval trim, string role)
+ {
+ var id = builder.AddEdge(from, to);
+ var curveId = new CurveGeometryId(nextCurve++);
+ geometry.AddCurve(curveId, curve);
+ bindings.AddEdgeBinding(new(id, curveId, trim));
+ edgeRoles.Add(id, role);
+ return id;
+ }
+
+ EdgeId Straight(VertexId from, VertexId to, string role)
+ {
+ var a = points[from];
+ var b = points[to];
+ var length = (b - a).Length;
+ return Edge(from, to, CurveGeometry.FromLine(new Line3Curve(a, Direction3D.Create(b - a))),
+ new ParameterInterval(0d, length), role);
+ }
+
+ FaceId Face(string role, SurfaceGeometryId surfaceId, params Use[] uses)
+ {
+ var loop = builder.AllocateLoopId();
+ var coedges = uses.Select(_ => builder.AllocateCoedgeId()).ToArray();
+ for (var i = 0; i < uses.Length; i++)
+ builder.AddCoedge(new Coedge(coedges[i], uses[i].Edge, loop,
+ coedges[(i + 1) % uses.Length], coedges[(i + uses.Length - 1) % uses.Length], uses[i].Reverse));
+ builder.AddLoop(new Loop(loop, coedges));
+ var face = builder.AddFace([loop]);
+ bindings.AddFaceBinding(new(face, surfaceId));
+ bindings.AddFaceBoundaryRoleBinding(new(face, loop, FaceBoundaryRole.Outer));
+ for (var i = 0; i < uses.Length; i++)
+ if (uses[i].Pcurve is { } uv)
+ bindings.AddPcurveBinding(new(coedges[i], face, surfaceId, uv));
+ faces.Add(face);
+ faceRoles.Add(face, role);
+ return face;
+ }
+
+ static Use[] Reversed(params Use[] uses) => uses.Reverse()
+ .Select(use => use with { Reverse = !use.Reverse }).ToArray();
+
+ PcurveGeometry CylinderVertical(EdgeId edge, double u)
+ {
+ var e = builder.Model.GetEdge(edge);
+ var start = (points[e.StartVertexId] - p.AxisOrigin).Dot(p.Axis.ToVector());
+ var end = (points[e.EndVertexId] - p.AxisOrigin).Dot(p.Axis.ToVector());
+ var trim = bindings.EdgeBindings.Single(binding => binding.EdgeId == edge).TrimInterval!.Value;
+ return PcurveGeometry.Line(trim, new(u, start), new(u, end));
+ }
+
+ PcurveGeometry CylinderHelix(EdgeId edge, int turn, bool trailing)
+ {
+ var trim = bindings.EdgeBindings.Single(binding => binding.EdgeId == edge).TrimInterval!.Value;
+ var offset = trailing ? p.RootWidthMm / 2d : -p.RootWidthMm / 2d;
+ var z0 = p.AxialStartMm + turn * p.PitchMm + offset;
+ return PcurveGeometry.Line(trim, new(0d, z0), new(2d * double.Pi, z0 + p.PitchMm));
+ }
+
+ var section = new VertexId[turns + 1, 4];
+ for (var k = 0; k <= turns; k++)
+ {
+ var angle = p.StartAngleRadians + 2d * double.Pi * k;
+ for (var role = 0; role < 4; role++)
+ section[k, role] = Vertex(rib.Boundary((HelicalRibBoundaryRole)role).Evaluate(angle));
+ }
+ var bottom = Vertex(cylinder.Evaluate(0d, p.SupportAxialMinMm));
+ var top = Vertex(cylinder.Evaluate(0d, p.SupportAxialMaxMm));
+
+ var sideSurfaces = new SurfaceGeometryId[turns, 3];
+ var sideRealizations = new QualifiedHelicalRibSurface[turns, 3];
+ var helical = new EdgeId[turns, 4];
+ for (var k = 0; k < turns; k++)
+ {
+ var sub = HelicalRibGeometry.Create(p with
+ {
+ AxialStartMm = p.AxialStartMm + k * p.PitchMm,
+ AxialEndMm = p.AxialStartMm + (k + 1) * p.PitchMm,
+ StartAngleRadians = p.StartAngleRadians + 2d * double.Pi * k
+ });
+ if (!sub.IsSuccess) return KernelResult<BrepHelicalRibResult>.Failure(sub.Diagnostics);
+ var realized = new QualifiedHelicalRibSurface[3];
+ for (var role = 0; role < 3; role++)
+ {
+ var result = HelicalRibSurfaceRealizer.Realize(sub.Value, (HelicalRibSideRole)role);
+ if (!result.IsSuccess) return KernelResult<BrepHelicalRibResult>.Failure(result.Diagnostics);
+ realized[role] = result.Value;
+ sideRealizations[k, role] = result.Value;
+ var surfaceId = new SurfaceGeometryId(nextSurface++);
+ geometry.AddSurface(surfaceId, SurfaceGeometry.FromBSplineSurfaceWithKnots(result.Value.Surface));
+ sideSurfaces[k, role] = surfaceId;
+ }
+ for (var role = 0; role < 4; role++)
+ {
+ var source = role switch { 0 => realized[0].Surface, 1 => realized[0].Surface,
+ 2 => realized[1].Surface, _ => realized[2].Surface };
+ var column = role is 0 ? 0 : 1;
+ var curve = new BSpline3Curve(source.DegreeU,
+ source.ControlPoints.Select(row => row[column]).ToArray(),
+ source.KnotMultiplicitiesU, source.KnotValuesU, "UNSPECIFIED", false, false, "UNSPECIFIED");
+ helical[k, role] = Edge(section[k, role], section[k + 1, role],
+ CurveGeometry.FromBSpline(curve), new(curve.DomainStart, curve.DomainEnd),
+ $"{(HelicalRibBoundaryRole)role}.Segment[{k}]");
+ }
+ }
+
+ var cross = new EdgeId[turns + 1, 3];
+ for (var k = 0; k <= turns; k++)
+ for (var role = 0; role < 3; role++)
+ cross[k, role] = Straight(section[k, role], section[k, role + 1], $"Section[{k}].{(HelicalRibSideRole)role}");
+
+ var startRoot = Straight(section[0, 0], section[0, 3], "Start.Root");
+ var endRoot = Straight(section[turns, 0], section[turns, 3], "End.Root");
+ var gaps = new EdgeId[turns + 1];
+ for (var k = 1; k <= turns; k++)
+ gaps[k] = Straight(section[k - 1, 3], section[k, 0], $"RootGap.Seam[{k}]");
+ var lowerSeam = Straight(bottom, section[0, 0], "RootLower.Seam");
+ var upperSeam = Straight(section[turns, 3], top, "RootUpper.Seam");
+ var bottomCircle = Edge(bottom, bottom,
+ CurveGeometry.FromCircle(new Circle3Curve(p.AxisOrigin + p.Axis.ToVector() * p.SupportAxialMinMm,
+ p.Axis, p.RootRadiusMm, seamRadial)), new(0d, 2d * double.Pi), "Support.BottomRim");
+ var topCircle = Edge(top, top,
+ CurveGeometry.FromCircle(new Circle3Curve(p.AxisOrigin + p.Axis.ToVector() * p.SupportAxialMaxMm,
+ p.Axis, p.RootRadiusMm, seamRadial)), new(0d, 2d * double.Pi), "Support.TopRim");
+ var bottomUv = PcurveGeometry.Line(new(0d, 2d * double.Pi),
+ new(0d, p.SupportAxialMinMm), new(2d * double.Pi, p.SupportAxialMinMm));
+ var topUv = PcurveGeometry.Line(new(0d, 2d * double.Pi),
+ new(0d, p.SupportAxialMaxMm), new(2d * double.Pi, p.SupportAxialMaxMm));
+
+ Face("RootCylinderSkin.Lower", cylinderId, Reversed(
+ new Use(lowerSeam, false, CylinderVertical(lowerSeam, 0d)),
+ new Use(helical[0, 0], false, CylinderHelix(helical[0, 0], 0, false)),
+ new Use(gaps[1], true, CylinderVertical(gaps[1], 2d * double.Pi)),
+ new Use(startRoot, true, CylinderVertical(startRoot, 2d * double.Pi)),
+ new Use(lowerSeam, true, CylinderVertical(lowerSeam, 2d * double.Pi)),
+ new Use(bottomCircle, true, bottomUv)));
+
+ for (var k = 1; k < turns; k++)
+ Face($"RootCylinderSkin.Gap[{k}]", cylinderId, Reversed(
+ new Use(gaps[k], false, CylinderVertical(gaps[k], 0d)),
+ new Use(helical[k, 0], false, CylinderHelix(helical[k, 0], k, false)),
+ new Use(gaps[k + 1], true, CylinderVertical(gaps[k + 1], 2d * double.Pi)),
+ new Use(helical[k - 1, 3], true, CylinderHelix(helical[k - 1, 3], k - 1, true))));
+
+ Face("RootCylinderSkin.Upper", cylinderId, Reversed(
+ new Use(gaps[turns], false, CylinderVertical(gaps[turns], 0d)),
+ new Use(endRoot, false, CylinderVertical(endRoot, 0d)),
+ new Use(upperSeam, false, CylinderVertical(upperSeam, 0d)),
+ new Use(topCircle, false, topUv),
+ new Use(upperSeam, true, CylinderVertical(upperSeam, 2d * double.Pi)),
+ new Use(helical[turns - 1, 3], true, CylinderHelix(helical[turns - 1, 3], turns - 1, true))));
+
+ for (var k = 0; k < turns; k++)
+ {
+ for (var role = 0; role < 3; role++)
+ {
+ var u0 = p.StartAngleRadians + 2d * double.Pi * k;
+ var u1 = u0 + 2d * double.Pi;
+ var boundary0 = helical[k, role];
+ var boundary1 = helical[k, role + 1];
+ var interval = bindings.EdgeBindings.Single(item => item.EdgeId == boundary0).TrimInterval!.Value;
+ var startInterval = bindings.EdgeBindings.Single(item => item.EdgeId == cross[k, role]).TrimInterval!.Value;
+ var endInterval = bindings.EdgeBindings.Single(item => item.EdgeId == cross[k + 1, role]).TrimInterval!.Value;
+ var sideFace = Face($"{(HelicalRibSideRole)role}.Segment[{k}]", sideSurfaces[k, role],
+ new Use(boundary0, false, PcurveGeometry.Line(interval, new(u0, 0d), new(u1, 0d))),
+ new Use(cross[k + 1, role], false, PcurveGeometry.Line(endInterval, new(u1, 0d), new(u1, 1d))),
+ new Use(boundary1, true, PcurveGeometry.Line(interval, new(u0, 1d), new(u1, 1d))),
+ new Use(cross[k, role], true, PcurveGeometry.Line(startInterval, new(u0, 0d), new(u0, 1d))));
+ qualifiedSideFaces.Add(sideFace, sideRealizations[k, role]);
+ }
+ }
+
+ var radialNormal = Direction3D.Create(p.Axis.ToVector().Cross(seamRadial.ToVector()));
+ var startPlaneId = new SurfaceGeometryId(nextSurface++);
+ geometry.AddSurface(startPlaneId, SurfaceGeometry.FromPlane(new PlaneSurface(points[section[0, 0]],
+ Direction3D.Create(-radialNormal.ToVector()), seamRadial)));
+ Face("StartCap", startPlaneId,
+ new Use(cross[0, 0], false), new Use(cross[0, 1], false),
+ new Use(cross[0, 2], false), new Use(startRoot, true));
+ var endPlaneId = new SurfaceGeometryId(nextSurface++);
+ geometry.AddSurface(endPlaneId, SurfaceGeometry.FromPlane(new PlaneSurface(points[section[turns, 0]],
+ radialNormal, seamRadial)));
+ Face("EndCap", endPlaneId,
+ new Use(endRoot, false), new Use(cross[turns, 2], true),
+ new Use(cross[turns, 1], true), new Use(cross[turns, 0], true));
+ var bottomPlaneId = new SurfaceGeometryId(nextSurface++);
+ geometry.AddSurface(bottomPlaneId, SurfaceGeometry.FromPlane(new PlaneSurface(
+ p.AxisOrigin + p.Axis.ToVector() * p.SupportAxialMinMm,
+ Direction3D.Create(-p.Axis.ToVector()), seamRadial)));
+ Face("Support.BottomCap", bottomPlaneId, new Use(bottomCircle, true));
+ var topPlaneId = new SurfaceGeometryId(nextSurface++);
+ geometry.AddSurface(topPlaneId, SurfaceGeometry.FromPlane(new PlaneSurface(
+ p.AxisOrigin + p.Axis.ToVector() * p.SupportAxialMaxMm, p.Axis, seamRadial)));
+ Face("Support.TopCap", topPlaneId, new Use(topCircle, false));
+
+ var shell = builder.AddShell(faces);
+ builder.AddBody([shell]);
+ var body = new BrepBody(builder.Model, geometry, bindings, points);
+ var validation = BrepBindingValidator.Validate(body, true);
+ if (!validation.IsSuccess) return KernelResult<BrepHelicalRibResult>.Failure(validation.Diagnostics);
+ var preflight = BrepExportPreflight.Validate(body);
+ if (!preflight.IsValid)
+ return Failure("preflight", string.Join("; ", preflight.Diagnostics
+ .Where(d => d.Severity == BrepExportPreflightSeverity.Error)
+ .Take(8).Select(d => d.Code + ": " + d.Message)));
+ return KernelResult<BrepHelicalRibResult>.Success(new(rib, body, faceRoles, edgeRoles, qualifiedSideFaces, turns - 1));
+ }
+
+ private static KernelResult<BrepHelicalRibResult> Failure(string code, string message) =>
+ KernelResult<BrepHelicalRibResult>.Failure([
+ new KernelDiagnostic(KernelDiagnosticCode.ValidationFailed, KernelDiagnosticSeverity.Error,
+ $"brep-helical-rib-{code}: {message}", "Brep.HelicalRib")]);
+}
diff --git a/Aetheris.Kernel.Core/Brep/Tessellation/BrepDisplayTessellator.cs b/Aetheris.Kernel.Core/Brep/Tessellation/BrepDisplayTessellator.cs
index 71389f9e..b77255fd 100644
--- a/Aetheris.Kernel.Core/Brep/Tessellation/BrepDisplayTessellator.cs
+++ b/Aetheris.Kernel.Core/Brep/Tessellation/BrepDisplayTessellator.cs
@@ -684,6 +684,31 @@ public static class BrepDisplayTessellator
var loopIds = body.GetLoopIds(faceId)
.Where(loopId => body.Topology.GetLoop(loopId).Kind == LoopKind.Edge)
.ToArray();
+ // A one-loop helical gap is a narrow diagonal strip in cylinder UV.
+ // Its bounding rectangle covers the rib footprint and is not a valid
+ // display patch. Use the authored pcurves for this bounded trim family.
+ if (loopIds.Length == 1 && body.GetCoedgeIds(loopIds[0]).Any(id =>
+ {
+ if (!body.Bindings.TryGetPcurveBinding(id, out var binding) || binding.FaceId != faceId)
+ return false;
+ var domain = binding.Pcurve.Domain;
+ var start = binding.Pcurve.Evaluate(domain.Start);
+ var end = binding.Pcurve.Evaluate(domain.End);
+ return double.Abs(end.U - start.U) > 1e-8d && double.Abs(end.V - start.V) > 1e-8d;
+ }))
+ {
+ var uvLoops = TryBuildTrimmedSurfaceUvLoops(body, faceId, loopIds,
+ point => TryProjectPointToCylinderUv(cylinder, point), options, executionBudget,
+ SurfaceGeometryKind.Cylinder);
+ if (!uvLoops.IsSuccess)
+ return KernelResult<DisplayFaceMeshPatch>.Failure(uvLoops.Diagnostics);
+ return TrimmedSurfaceTessellator.Tessellate(faceId, uvLoops.Value,
+ (u, v) => cylinder.Evaluate(u, v),
+ (u, _) => cylinder.Normal(u).ToVector(), options,
+ double.NegativeInfinity, double.PositiveInfinity,
+ double.NegativeInfinity, double.PositiveInfinity,
+ CreateValidationWarning, executionBudget, SurfaceGeometryKind.Cylinder);
+ }
if (loopIds.Length == 2
&& TryResolveDualSingleCoedgeClosedCircleCylinderTrimPatch(body, faceId, cylinder, loopIds, cylinder.Axis.ToVector(), 1e-8d).IsSuccess)
{
diff --git a/Aetheris.Kernel.Core/Geometry/Curves/CylindricalHelix3.cs b/Aetheris.Kernel.Core/Geometry/Curves/CylindricalHelix3.cs
new file mode 100644
index 00000000..44cb57e8
--- /dev/null
+++ b/Aetheris.Kernel.Core/Geometry/Curves/CylindricalHelix3.cs
@@ -0,0 +1,83 @@
+using Aetheris.Kernel.Core.Math;
+
+namespace Aetheris.Kernel.Core.Geometry.Curves;
+
+/// <summary>
+/// Exact, constant-pitch cylindrical helix. The angle is the parameter; a positive
+/// angle advances along the axis for a right-hand helix. Finite splines may realize
+/// this curve, but never replace its geometric authority.
+/// </summary>
+public readonly record struct CylindricalHelix3
+{
+ public CylindricalHelix3(Point3D axisOrigin, Direction3D axis, Direction3D startRadial,
+ double radiusMm, double pitchMm, double axialStartMm, double startAngleRadians,
+ double endAngleRadians, bool rightHanded = true)
+ {
+ if (!double.IsFinite(radiusMm) || radiusMm <= 0d) throw new ArgumentOutOfRangeException(nameof(radiusMm));
+ if (!double.IsFinite(pitchMm) || pitchMm <= 0d) throw new ArgumentOutOfRangeException(nameof(pitchMm));
+ if (!double.IsFinite(axialStartMm)) throw new ArgumentOutOfRangeException(nameof(axialStartMm));
+ if (!double.IsFinite(startAngleRadians) || !double.IsFinite(endAngleRadians)
+ || endAngleRadians <= startAngleRadians) throw new ArgumentOutOfRangeException(nameof(endAngleRadians));
+ if (!double.IsFinite(axisOrigin.X) || !double.IsFinite(axisOrigin.Y) || !double.IsFinite(axisOrigin.Z))
+ throw new ArgumentOutOfRangeException(nameof(axisOrigin));
+ if (double.Abs(axis.ToVector().LengthSquared - 1d) > 1e-9d
+ || double.Abs(startRadial.ToVector().LengthSquared - 1d) > 1e-9d)
+ throw new ArgumentException("Axis and start radial must be unit directions.");
+ if (double.Abs(axis.ToVector().Dot(startRadial.ToVector())) > 1e-9d)
+ throw new ArgumentException("Start radial must be perpendicular to the helix axis.", nameof(startRadial));
+
+ AxisOrigin = axisOrigin;
+ Axis = axis;
+ StartRadial = startRadial;
+ RadiusMm = radiusMm;
+ PitchMm = pitchMm;
+ AxialStartMm = axialStartMm;
+ StartAngleRadians = startAngleRadians;
+ EndAngleRadians = endAngleRadians;
+ RightHanded = rightHanded;
+ }
+
+ public Point3D AxisOrigin { get; }
+ public Direction3D Axis { get; }
+ public Direction3D StartRadial { get; }
+ public double RadiusMm { get; }
+ public double PitchMm { get; }
+ public double LeadMm => PitchMm;
+ public double AxialStartMm { get; }
+ public double StartAngleRadians { get; }
+ public double EndAngleRadians { get; }
+ public bool RightHanded { get; }
+ public double Turns => (EndAngleRadians - StartAngleRadians) / (2d * double.Pi);
+
+ public Vector3D Radial(double angle)
+ {
+ var radial = StartRadial.ToVector();
+ var circumferential = Axis.ToVector().Cross(radial);
+ var signedAngle = RightHanded ? angle : -angle;
+ return radial * double.Cos(signedAngle) + circumferential * double.Sin(signedAngle);
+ }
+
+ public Point3D Evaluate(double angle)
+ {
+ CheckDomain(angle);
+ return AxisOrigin + Axis.ToVector() * (AxialStartMm + PitchMm * (angle - StartAngleRadians) / (2d * double.Pi))
+ + Radial(angle) * RadiusMm;
+ }
+
+ public Vector3D Derivative(double angle)
+ {
+ CheckDomain(angle);
+ var radial = StartRadial.ToVector();
+ var circumferential = Axis.ToVector().Cross(radial);
+ var sign = RightHanded ? 1d : -1d;
+ var signedAngle = sign * angle;
+ return Axis.ToVector() * (PitchMm / (2d * double.Pi))
+ + (circumferential * double.Cos(signedAngle) - radial * double.Sin(signedAngle)) * (RadiusMm * sign);
+ }
+
+ private void CheckDomain(double angle)
+ {
+ if (!double.IsFinite(angle) || angle < StartAngleRadians - 1e-12d || angle > EndAngleRadians + 1e-12d)
+ throw new ArgumentOutOfRangeException(nameof(angle));
+ }
+}
diff --git a/Aetheris.Kernel.Core/Geometry/Curves/HelicalRibBoundaryRealizer.cs b/Aetheris.Kernel.Core/Geometry/Curves/HelicalRibBoundaryRealizer.cs
new file mode 100644
index 00000000..74b4eead
--- /dev/null
+++ b/Aetheris.Kernel.Core/Geometry/Curves/HelicalRibBoundaryRealizer.cs
@@ -0,0 +1,79 @@
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+using Aetheris.Kernel.Core.Results;
+
+namespace Aetheris.Kernel.Core.Geometry.Curves;
+
+/// <summary>A finite polynomial curve subordinate to one exact helical rib boundary.</summary>
+public sealed record QualifiedHelicalRibBoundary(
+ CylindricalHelix3 Authority,
+ BSpline3Curve Curve,
+ double RequestedToleranceMm,
+ double AnalyticErrorBoundMm,
+ double NumericalAllowanceMm,
+ int SegmentCount)
+{
+ public double CertifiedDeviationBoundMm => AnalyticErrorBoundMm + NumericalAllowanceMm;
+}
+
+public static class HelicalRibBoundaryRealizer
+{
+ private const int MaxSegments = 16_384;
+ private const double MachineEpsilon = 2.2204460492503131e-16d;
+
+ public static KernelResult<QualifiedHelicalRibBoundary> Realize(
+ CylindricalHelix3 authority, ToleranceContext? tolerance = null)
+ {
+ var requested = (tolerance ?? ToleranceContext.Default).Linear;
+ var axialEnd = authority.AxialStartMm + authority.PitchMm * authority.Turns;
+ var scale = double.Max(1d, double.Max(authority.RadiusMm,
+ double.Max(double.Max(double.Abs(authority.AxialStartMm), double.Abs(axialEnd)),
+ double.Max(double.Abs(authority.AxisOrigin.X),
+ double.Max(double.Abs(authority.AxisOrigin.Y), double.Abs(authority.AxisOrigin.Z))))));
+ var allowance = 256d * MachineEpsilon * scale;
+ var budget = requested - allowance;
+ if (budget <= 0d)
+ return Failure("numeric-tolerance", "Coordinate scale consumes the requested tolerance.");
+
+ // Cubic Hermite remainder: |f''''| h^4 / 384. The axial coordinate is
+ // linear in angle; the fourth derivative is purely radial with norm r.
+ var maximumSpan = double.Pow(384d * budget / authority.RadiusMm, 0.25d);
+ var angleRange = authority.EndAngleRadians - authority.StartAngleRadians;
+ var segmentCountReal = double.Ceiling(angleRange / maximumSpan);
+ if (!double.IsFinite(segmentCountReal) || segmentCountReal < 1d || segmentCountReal > MaxSegments)
+ return Failure("segment-budget", "Certified helix realization exceeds the bounded segment budget.");
+ var segmentCount = (int)segmentCountReal;
+ var h = angleRange / segmentCount;
+ var error = authority.RadiusMm * double.Pow(h, 4d) / 384d;
+ var controls = new List<Point3D>(4 * segmentCount);
+ var knots = new List<double>(segmentCount + 1);
+ var multiplicities = new List<int>(segmentCount + 1);
+ knots.Add(authority.StartAngleRadians);
+ multiplicities.Add(4);
+ for (var i = 0; i < segmentCount; i++)
+ {
+ var a = authority.StartAngleRadians + angleRange * i / segmentCount;
+ var b = i == segmentCount - 1 ? authority.EndAngleRadians
+ : authority.StartAngleRadians + angleRange * (i + 1) / segmentCount;
+ var width = b - a;
+ var p0 = authority.Evaluate(a);
+ var p3 = authority.Evaluate(b);
+ controls.Add(p0);
+ controls.Add(p0 + authority.Derivative(a) * (width / 3d));
+ controls.Add(p3 - authority.Derivative(b) * (width / 3d));
+ controls.Add(p3);
+ knots.Add(b);
+ multiplicities.Add(4);
+ }
+ var curve = new BSpline3Curve(3, controls, multiplicities, knots,
+ "UNSPECIFIED", false, false, "UNSPECIFIED");
+ return KernelResult<QualifiedHelicalRibBoundary>.Success(new(
+ authority, curve, requested, error, allowance, segmentCount));
+ }
+
+ private static KernelResult<QualifiedHelicalRibBoundary> Failure(string code, string message) =>
+ KernelResult<QualifiedHelicalRibBoundary>.Failure([
+ new KernelDiagnostic(KernelDiagnosticCode.ValidationFailed, KernelDiagnosticSeverity.Error,
+ $"helical-rib-realization-{code}: {message}", "Geometry.HelicalRib.Boundary")]);
+}
diff --git a/Aetheris.Kernel.Core/Geometry/HelicalRibGeometry.cs b/Aetheris.Kernel.Core/Geometry/HelicalRibGeometry.cs
new file mode 100644
index 00000000..b6a9979e
--- /dev/null
+++ b/Aetheris.Kernel.Core/Geometry/HelicalRibGeometry.cs
@@ -0,0 +1,127 @@
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Geometry.Curves;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+using Aetheris.Kernel.Core.Results;
+
+namespace Aetheris.Kernel.Core.Geometry;
+
+/// <summary>Exact intent for one additive, right-hand, single-start rib on finite cylindrical stock.</summary>
+public sealed record HelicalRibParameters(
+ Point3D AxisOrigin,
+ Direction3D Axis,
+ Direction3D StartRadial,
+ double SupportAxialMinMm,
+ double SupportAxialMaxMm,
+ double RootRadiusMm,
+ double CrestRadiusMm,
+ double PitchMm,
+ double AxialStartMm,
+ double AxialEndMm,
+ double RootWidthMm,
+ double CrestWidthMm,
+ double StartAngleRadians = 0d);
+
+public enum HelicalRibBoundaryRole { LeadingRoot, LeadingCrest, TrailingCrest, TrailingRoot }
+public enum HelicalRibSideRole { LeadingFlank, Crest, TrailingFlank }
+
+/// <summary>
+/// Exact cylindrical frame and trapezoidal profile geometry. This is the
+/// authoritative law for future BRep faces; it is not a BRep materializer.
+/// </summary>
+public sealed class HelicalRibGeometry
+{
+ private HelicalRibGeometry(HelicalRibParameters parameters)
+ {
+ Parameters = parameters;
+ EndAngleRadians = parameters.StartAngleRadians
+ + 2d * double.Pi * (parameters.AxialEndMm - parameters.AxialStartMm) / parameters.PitchMm;
+ }
+
+ public HelicalRibParameters Parameters { get; }
+ public double EndAngleRadians { get; }
+ public double Turns => (Parameters.AxialEndMm - Parameters.AxialStartMm) / Parameters.PitchMm;
+ public double LeadMm => Parameters.PitchMm;
+ public double MinimumAdjacentTurnClearanceMm => Parameters.PitchMm - Parameters.RootWidthMm;
+
+ public static KernelResult<HelicalRibGeometry> Create(HelicalRibParameters p, ToleranceContext? tolerance = null)
+ {
+ ArgumentNullException.ThrowIfNull(p);
+ var linear = (tolerance ?? ToleranceContext.Default).Linear;
+ if (!Finite(p.SupportAxialMinMm, p.SupportAxialMaxMm, p.RootRadiusMm,
+ p.CrestRadiusMm, p.PitchMm, p.AxialStartMm, p.AxialEndMm,
+ p.RootWidthMm, p.CrestWidthMm, p.StartAngleRadians,
+ p.AxisOrigin.X, p.AxisOrigin.Y, p.AxisOrigin.Z))
+ return Failure("nonfinite", "All rib dimensions and placement coordinates must be finite.");
+ if (p.SupportAxialMaxMm <= p.SupportAxialMinMm)
+ return Failure("support-bounds", "Support axial maximum must exceed minimum.");
+ if (p.RootRadiusMm <= 0d || p.CrestRadiusMm <= p.RootRadiusMm)
+ return Failure("radii", "Crest radius must exceed a positive root/support radius.");
+ if (p.PitchMm <= 0d) return Failure("pitch", "Pitch must be positive.");
+ if (p.AxialEndMm <= p.AxialStartMm)
+ return Failure("span", "Rib axial end must exceed start.");
+ if (p.CrestWidthMm <= 0d || p.RootWidthMm <= p.CrestWidthMm)
+ return Failure("profile-width", "Root width must exceed a positive crest width.");
+ if (p.RootWidthMm >= p.PitchMm - linear)
+ return Failure("adjacent-turn-overlap", "Root profile width must be smaller than pitch with positive clearance.");
+ if (p.AxialStartMm - p.RootWidthMm / 2d < p.SupportAxialMinMm - linear
+ || p.AxialEndMm + p.RootWidthMm / 2d > p.SupportAxialMaxMm + linear)
+ return Failure("support-extent", "The entire rib profile must lie within the support axial bounds.");
+ if (double.Abs(p.Axis.ToVector().LengthSquared - 1d) > 1e-9d
+ || double.Abs(p.StartRadial.ToVector().LengthSquared - 1d) > 1e-9d
+ || double.Abs(p.Axis.ToVector().Dot(p.StartRadial.ToVector())) > 1e-9d)
+ return Failure("frame", "Axis and start radial must be unit and perpendicular.");
+ var endAngle = p.StartAngleRadians + 2d * double.Pi * (p.AxialEndMm - p.AxialStartMm) / p.PitchMm;
+ if (!double.IsFinite(endAngle) || endAngle <= p.StartAngleRadians)
+ return Failure("turn-count", "Derived angular span is nonfinite or degenerate.");
+ return KernelResult<HelicalRibGeometry>.Success(new HelicalRibGeometry(p));
+ }
+
+ public CylindricalHelix3 Boundary(HelicalRibBoundaryRole role)
+ {
+ var (radius, axialOffset) = Corner(role);
+ return new CylindricalHelix3(Parameters.AxisOrigin, Parameters.Axis, Parameters.StartRadial,
+ radius, Parameters.PitchMm, Parameters.AxialStartMm + axialOffset,
+ Parameters.StartAngleRadians, EndAngleRadians);
+ }
+
+ /// <summary>Exact point on a ruled helical flank or crest; u is angular position, v crosses the profile.</summary>
+ public Point3D Evaluate(HelicalRibSideRole role, double angle, double v)
+ {
+ if (!double.IsFinite(v) || v < 0d || v > 1d) throw new ArgumentOutOfRangeException(nameof(v));
+ var (a, b) = role switch
+ {
+ HelicalRibSideRole.LeadingFlank => (HelicalRibBoundaryRole.LeadingRoot, HelicalRibBoundaryRole.LeadingCrest),
+ HelicalRibSideRole.Crest => (HelicalRibBoundaryRole.LeadingCrest, HelicalRibBoundaryRole.TrailingCrest),
+ HelicalRibSideRole.TrailingFlank => (HelicalRibBoundaryRole.TrailingCrest, HelicalRibBoundaryRole.TrailingRoot),
+ _ => throw new ArgumentOutOfRangeException(nameof(role))
+ };
+ var (r0, z0) = Corner(a);
+ var (r1, z1) = Corner(b);
+ var radius = r0 + (r1 - r0) * v;
+ var offset = z0 + (z1 - z0) * v;
+ var helix = new CylindricalHelix3(Parameters.AxisOrigin, Parameters.Axis, Parameters.StartRadial,
+ radius, Parameters.PitchMm, Parameters.AxialStartMm + offset,
+ Parameters.StartAngleRadians, EndAngleRadians);
+ return helix.Evaluate(angle);
+ }
+
+ public IReadOnlyList<Point3D> CapCorners(bool end) => Enum.GetValues<HelicalRibBoundaryRole>()
+ .Select(role => Boundary(role).Evaluate(end ? EndAngleRadians : Parameters.StartAngleRadians)).ToArray();
+
+ private (double Radius, double AxialOffset) Corner(HelicalRibBoundaryRole role) => role switch
+ {
+ HelicalRibBoundaryRole.LeadingRoot => (Parameters.RootRadiusMm, -Parameters.RootWidthMm / 2d),
+ HelicalRibBoundaryRole.LeadingCrest => (Parameters.CrestRadiusMm, -Parameters.CrestWidthMm / 2d),
+ HelicalRibBoundaryRole.TrailingCrest => (Parameters.CrestRadiusMm, Parameters.CrestWidthMm / 2d),
+ HelicalRibBoundaryRole.TrailingRoot => (Parameters.RootRadiusMm, Parameters.RootWidthMm / 2d),
+ _ => throw new ArgumentOutOfRangeException(nameof(role))
+ };
+
+ private static bool Finite(params double[] values) => values.All(double.IsFinite);
+
+ private static KernelResult<HelicalRibGeometry> Failure(string code, string message) =>
+ KernelResult<HelicalRibGeometry>.Failure([
+ new KernelDiagnostic(KernelDiagnosticCode.ValidationFailed, KernelDiagnosticSeverity.Error,
+ $"helical-rib-{code}: {message}", "Geometry.HelicalRib")]);
+}
diff --git a/Aetheris.Kernel.Core/Geometry/Surfaces/HelicalRibSurfaceRealizer.cs b/Aetheris.Kernel.Core/Geometry/Surfaces/HelicalRibSurfaceRealizer.cs
new file mode 100644
index 00000000..d68e52ed
--- /dev/null
+++ b/Aetheris.Kernel.Core/Geometry/Surfaces/HelicalRibSurfaceRealizer.cs
@@ -0,0 +1,94 @@
+using Aetheris.Kernel.Core.Diagnostics;
+using Aetheris.Kernel.Core.Geometry.Curves;
+using Aetheris.Kernel.Core.Math;
+using Aetheris.Kernel.Core.Numerics;
+using Aetheris.Kernel.Core.Results;
+
+namespace Aetheris.Kernel.Core.Geometry.Surfaces;
+
+/// <summary>Finite flank/crest surface subordinate to an exact constant-profile helical rib.</summary>
+public sealed record QualifiedHelicalRibSurface(
+ HelicalRibGeometry Authority,
+ HelicalRibSideRole Role,
+ BSplineSurfaceWithKnots Surface,
+ double RequestedToleranceMm,
+ double AnalyticErrorBoundMm,
+ double NumericalAllowanceMm,
+ int SegmentCount)
+{
+ public double CertifiedDeviationBoundMm => AnalyticErrorBoundMm + NumericalAllowanceMm;
+}
+
+public static class HelicalRibSurfaceRealizer
+{
+ private const int MaxSegments = 16_384;
+ private const double MachineEpsilon = 2.2204460492503131e-16d;
+
+ public static KernelResult<QualifiedHelicalRibSurface> Realize(
+ HelicalRibGeometry rib, HelicalRibSideRole role, ToleranceContext? tolerance = null)
+ {
+ ArgumentNullException.ThrowIfNull(rib);
+ var (firstRole, secondRole) = role switch
+ {
+ HelicalRibSideRole.LeadingFlank => (HelicalRibBoundaryRole.LeadingRoot, HelicalRibBoundaryRole.LeadingCrest),
+ HelicalRibSideRole.Crest => (HelicalRibBoundaryRole.LeadingCrest, HelicalRibBoundaryRole.TrailingCrest),
+ HelicalRibSideRole.TrailingFlank => (HelicalRibBoundaryRole.TrailingCrest, HelicalRibBoundaryRole.TrailingRoot),
+ _ => throw new ArgumentOutOfRangeException(nameof(role))
+ };
+ var first = rib.Boundary(firstRole);
+ var second = rib.Boundary(secondRole);
+ var requested = (tolerance ?? ToleranceContext.Default).Linear;
+ var p = rib.Parameters;
+ var scale = double.Max(1d, double.Max(p.CrestRadiusMm,
+ double.Max(double.Abs(p.SupportAxialMinMm),
+ double.Max(double.Abs(p.SupportAxialMaxMm),
+ double.Max(double.Abs(p.AxisOrigin.X),
+ double.Max(double.Abs(p.AxisOrigin.Y), double.Abs(p.AxisOrigin.Z)))))));
+ var allowance = 256d * MachineEpsilon * scale;
+ var budget = requested - allowance;
+ if (budget <= 0d)
+ return Failure("numeric-tolerance", "Coordinate scale consumes the requested tolerance.");
+ var maximumRadius = double.Max(first.RadiusMm, second.RadiusMm);
+ // The surface is linear in profile coordinate v. Hermite interpolation
+ // in angle has fourth derivative norm <= max endpoint radius.
+ var maximumSpan = double.Pow(384d * budget / maximumRadius, 0.25d);
+ var angleRange = rib.EndAngleRadians - p.StartAngleRadians;
+ var countReal = double.Ceiling(angleRange / maximumSpan);
+ if (!double.IsFinite(countReal) || countReal < 1d || countReal > MaxSegments)
+ return Failure("segment-budget", "Certified helical surface exceeds the bounded segment budget.");
+ var count = (int)countReal;
+ var h = angleRange / count;
+ var analyticError = maximumRadius * double.Pow(h, 4d) / 384d;
+ var rows = new List<IReadOnlyList<Point3D>>(count * 4);
+ var knots = new List<double>(count + 1) { p.StartAngleRadians };
+ var multiplicities = new List<int>(count + 1) { 4 };
+ for (var i = 0; i < count; i++)
+ {
+ var a = p.StartAngleRadians + angleRange * i / count;
+ var b = i == count - 1 ? rib.EndAngleRadians : p.StartAngleRadians + angleRange * (i + 1) / count;
+ var width = b - a;
+ var a0 = first.Evaluate(a);
+ var b0 = first.Evaluate(b);
+ var a1 = second.Evaluate(a);
+ var b1 = second.Evaluate(b);
+ rows.Add([a0, a1]);
+ rows.Add([a0 + first.Derivative(a) * (width / 3d),
+ a1 + second.Derivative(a) * (width / 3d)]);
+ rows.Add([b0 - first.Derivative(b) * (width / 3d),
+ b1 - second.Derivative(b) * (width / 3d)]);
+ rows.Add([b0, b1]);
+ knots.Add(b);
+ multiplicities.Add(4);
+ }
+ var surface = new BSplineSurfaceWithKnots(3, 1, rows,
+ "UNSPECIFIED", false, false, false,
+ multiplicities, [2, 2], knots, [0d, 1d], "UNSPECIFIED");
+ return KernelResult<QualifiedHelicalRibSurface>.Success(new(
+ rib, role, surface, requested, analyticError, allowance, count));
+ }
+
+ private static KernelResult<QualifiedHelicalRibSurface> Failure(string code, string message) =>
+ KernelResult<QualifiedHelicalRibSurface>.Failure([
+ new KernelDiagnostic(KernelDiagnosticCode.ValidationFailed, KernelDiagnosticSeverity.Error,
+ $"helical-rib-surface-{code}: {message}", "Geometry.HelicalRib.Surface")]);
+}
diff --git a/Aetheris.Kernel.Core/Step242/Step242Importer.cs b/Aetheris.Kernel.Core/Step242/Step242Importer.cs
index 250668af..5ce9c8d3 100644
--- a/Aetheris.Kernel.Core/Step242/Step242Importer.cs
+++ b/Aetheris.Kernel.Core/Step242/Step242Importer.cs
@@ -1097,7 +1097,7 @@ public static class Step242Importer
}
return FailureCurveBinding(
- $"RATIONAL_B_SPLINE_CURVE is unsupported unless it recovers as an analytic circle. {recoveryDecision.Reason}",
+ $"RATIONAL_B_SPLINE_CURVE #{curveEntity.Id} cannot be imported exactly: the curve is not a qualified analytic circle, and CurveGeometry has no weighted B-spline curve representation. Do not discard its weights or substitute the polynomial control polygon. {recoveryDecision.Reason}",
SourceFor(curveEntity.Id, "Importer.Geometry.RationalBSplineCurve"));
}
diff --git a/Aetheris.Kernel.Firmament/Materializer/WireCoils.cs b/Aetheris.Kernel.Firmament/Materializer/WireCoils.cs
index cf5afb64..4de51a62 100644
--- a/Aetheris.Kernel.Firmament/Materializer/WireCoils.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/WireCoils.cs
@@ -156,14 +156,17 @@ public static class WireCoilGeometry
{
public static Point3D EvaluateAxis(WireAxisCoilAir coil, double t)
{
- var theta = (coil.Handedness == WireCoilHandedness.RightHanded ? 1d : -1d) * 2d * Math.PI * coil.Turns * Math.Clamp(t, 0d, 1d);
- return coil.AxisOrigin + Rotate(coil.StartRadial.ToVector(), coil.Axis.ToVector(), theta) * coil.RadiusMm + coil.Axis.ToVector() * (coil.HeightMm * t);
+ var helix = AxisHelix(coil);
+ return helix.Evaluate(helix.EndAngleRadians * Math.Clamp(t, 0d, 1d));
}
public static Direction3D TangentAxis(WireAxisCoilAir coil, double t)
{
- var sign = coil.Handedness == WireCoilHandedness.RightHanded ? 1d : -1d; var radial = Rotate(coil.StartRadial.ToVector(), coil.Axis.ToVector(), sign * 2d * Math.PI * coil.Turns * t);
- return Direction3D.Create(WireFormAuthoring.Cross(coil.Axis.ToVector(), radial) * (sign * 2d * Math.PI * coil.Turns * coil.RadiusMm) + coil.Axis.ToVector() * coil.HeightMm);
+ var helix = AxisHelix(coil);
+ return Direction3D.Create(helix.Derivative(helix.EndAngleRadians * Math.Clamp(t, 0d, 1d)));
}
+ private static CylindricalHelix3 AxisHelix(WireAxisCoilAir coil) => new(
+ coil.AxisOrigin, coil.Axis, coil.StartRadial, coil.RadiusMm, coil.HeightMm / coil.Turns,
+ 0d, 0d, 2d * Math.PI * coil.Turns, coil.Handedness == WireCoilHandedness.RightHanded);
public static Point3D EvaluateSurface(WireSurfaceCoilAir coil, double t)
{
t = Math.Clamp(t, 0d, 1d); var sign = coil.Handedness == WireCoilHandedness.RightHanded ? 1d : -1d; var theta = sign * 2d * Math.PI * coil.Turns * t;
diff --git a/docs/release/BREP-HELICAL-RIB-X0.md b/docs/release/BREP-HELICAL-RIB-X0.md
new file mode 100644
index 00000000..e18fc47f
--- /dev/null
+++ b/docs/release/BREP-HELICAL-RIB-X0.md
@@ -0,0 +1,31 @@
+# BREP-HELICAL-RIB-X0 — qualified geometry, topology stop
+
+> Downstream status (X1): the bounded complete-turn manifold topology, AP242 export/reimport, and display witness are now implemented and qualified in `BREP-HELICAL-RIB-X1.md`. The X0 verdict below records the state at the end of the X0 geometry milestone.
+
+**Verdict: Meaningful progression; the requested manifold BRep is not accepted.** The exact cylindrical helix and bounded trapezoidal rib authority now exist in Core, with certified non-rational polynomial realizations for all four boundary helices and three side surfaces. The missing layer is the direct BRep construction that replaces the rib footprint on the support cylinder, stitches shared helical edges, closes the two end caps, and resolves the periodic seam. No mesh, generic sweep, or generic Boolean substitute is used. No `Thread` syntax was added.
+
+## Geometry authority
+
+`CylindricalHelix3` is shared by the existing WireForm axis-coil evaluator and `HelicalRibGeometry`. It retains axis, reference radial, radius, pitch, handedness, axial origin, and angular domain. The rib admits right-hand, single-start, constant pitch/profile geometry and derives lead = pitch and turns = axial span / pitch. Its natural frame is the support axis and rotating radial vector; no Frenet transport is involved. The exact side law is linear across each root/flank/crest profile segment and helical in angle. Four stable boundary roles are `LeadingRoot`, `LeadingCrest`, `TrailingCrest`, and `TrailingRoot`; the side roles are `LeadingFlank`, `Crest`, and `TrailingFlank`. Start/end cap corners are exact evaluations at domain limits.
+
+The canonical geometry test uses a 3.2 mm root radius, 4 mm crest radius, 1.25 mm pitch, 1.1 mm root width, 0.1 mm crest width, and 30 mm centerline axial span: **24 turns**, 0.15 mm minimum adjacent-turn axial clearance, root/crest diameters 6.4/8 mm. This is a metric-like envelope, not a standard thread claim. The footprint fits support bounds from 0 to 31.1 mm. Validation rejects nonfinite input, invalid radii, pitch/span, inverted crest/root widths, root width reaching pitch, nonorthogonal frame, and profile extending beyond support bounds.
+
+## Qualified finite geometry
+
+The boundary realizer emits cubic non-rational B-spline spans. The side realizer emits degree-(3,1) non-rational B-spline surfaces, cubic along the helix and linear across the profile. Both retain the exact authority in their result. On an angular span of width `h`, the axial component is represented exactly and the fourth derivative of the radial component has norm `r`; the cubic Hermite deviation is bounded by `r h^4 / 384`. A separate floating-point allowance is subtracted from the requested tolerance before choosing a bounded segment count. The returned certificate is the analytic bound plus that allowance. The default requested kernel tolerance is 1e-6 mm. Tests sample the canonical 24-turn witness against exact points on all three realized side surfaces and one boundary, and check every sampled error against its certificate. This is a real-arithmetic interpolation bound with a conservative scale-based numerical allowance; it is not yet a pcurve/3D edge consistency certificate for a BRep.
+
+For later topology assembly, a shared edge must be derived from the adjacent surface boundary or realized on a common knot partition. Independently realized curves can choose different partitions even when they represent the same exact helix. The current authority preserves enough information to do that deterministically but does not claim the edge bindings yet.
+
+## Exact missing topology layer
+
+The outer support cylinder must exclude the helical attachment footprint. Its remaining skin must be split into deterministic helical gap patches across angular wraps. The leading/trailing flank and crest faces need coedges that share one curve binding at each boundary and at every seam split. The four-corner start/end caps must meet the support skin without T junctions, and the two stock end disks must close the shell. The current BRep construction utilities do not assemble that specific wound cylinder partition. Producing side surfaces alone, or unioning a floating swept strip, would fail the support-attachment and manifold requirements. This is the isolated next blocker.
+
+There is therefore no canonical BRep body, topology count, STEP export/reimport, display tessellation, shaded render, or construction/topology/STEP timing to report. The finite side representations are geometry candidates, not evidence that exporter and importer accept the eventual trimmed helical faces. No pcurve error bound or orientation qualification is claimed.
+
+## Reference scope
+
+The supplied McMaster pair remains dimensional evidence only. Direct STEP records show 8 mm cylindrical major surfaces and a repeating 0.625 mm axial vertex interval in the threaded file, consistent with a 1.25 mm full pitch. The current Aetheris importer stops at non-circular weighted B-spline curve `#2175`; its weights cannot be dropped. Exact minor diameter, runout, and source topology correspondence remain unverified. Reports of misrendering in OCCT-based readers have not been independently verified here and are not used as acceptance evidence. See `THREAD-EXTERNAL-X0.md` for the measured inventory.
+
+## Verification
+
+The focused Core geometry tests cover one and 24 turns, derived lead/turns, pitch/length/depth changes, transformed axis frame, angular periodicity, support extent and adjacent-turn rejection, deterministic boundary realization, and sampled certified surface deviations. The shared helix evaluation path passed all 30 `WireFormTests`. Release solution build passed. The fast Core lane passed 987/987; the corpus-inclusive Core lane passed 1120/1120; Firmament passed 1649/1649. The full solution gate still exits nonzero on the same baseline failures observed before this milestone: two CLI tests (hex-bolt OBJ polygon count and SheetMetal routing) and five SheetMetal tests. They are outside this geometry work.
diff --git a/docs/release/BREP-HELICAL-RIB-X1.md b/docs/release/BREP-HELICAL-RIB-X1.md
new file mode 100644
index 00000000..81fa8540
--- /dev/null
+++ b/docs/release/BREP-HELICAL-RIB-X1.md
@@ -0,0 +1,53 @@
+# BREP-HELICAL-RIB-X1 — manifold topology for bounded helical ribs
+
+**Verdict: Accepted for the bounded complete-turn kernel feature.** `BrepHelicalRib.Create` converts the X0 exact rib authority into one closed, oriented, seam-aware BRep body. The canonical 24-turn body exports to AP242, reimports as one enclosed manifold shell, and tessellates with every face present. This is a kernel feature; public `Thread` syntax remains a later milestone.
+
+## Admitted construction
+
+The input is one right-hand, single-start, constant-pitch `HelicalRibGeometry` on cylindrical root stock. X1 admits 1–40 **complete turns** and requires exposed cylindrical stock before and after the rib footprint. Noninteger turn counts and rib contact with either stock end receive explicit diagnostics. The X0 authority still rejects overlapping adjacent turns (`root width >= pitch`) and invalid radii, pitch, profile widths, or support extent before topology construction.
+
+The rib retains its exact axis, radial frame, pitch, profile, start phase, and angular domain in `BrepHelicalRibResult.Authority`. `QualifiedSideFaces` maps every side face back to its exact one-turn authority and finite-realization certificate. The BRep side faces are qualified non-rational degree-(3,1) surfaces. Their four boundary curve roles are realized directly from the corresponding surface control nets, so adjacent faces bind the same edge rather than independently fitting it. The X0 realization certificate bounds each side surface to the configured 1e-6 mm kernel tolerance, including its numerical allowance. The BRep pcurve validator checks 3D/pcurve agreement to 1e-6 mm.
+
+## Direct topology
+
+For `N` turns, the support cylinder is partitioned into `N+1` exposed skin faces: lower margin, `N-1` interturn gaps, and upper margin. No untrimmed support face remains beneath the rib. Each turn has a leading flank, finite-width crest, and trailing flank. Planar start/end rib caps close the feature; planar stock end disks close the cylinder. This is direct known topology: no generic sweep, Boolean union, or mesh-derived BRep.
+
+The support seam is placed at the authored start phase, even when the entire axis/frame is transformed. Each wrap is one deterministic topological segment. Neighboring side surfaces and root gaps share the same edge IDs, and `EdgeRoles` retain the logical boundary name plus segment index. The result reports `N-1` internal seam splits. Each edge has exactly two coedges of opposite sense; loop and binding validation, export preflight, and pcurve checks pass. The 24-turn tessellation has positive signed volume of approximately 1,312.0 mm³, within 0.5% of the analytic stock-plus-trapezoid volume (1,317.4 mm³). This display-derived volume is an orientation/trim check, not a certified mass property.
+
+| Turns | Faces | Edges | Vertices | Internal seam splits | Warm build |
+| ---: | ---: | ---: | ---: | ---: | ---: |
+| 1 | 9 | 17 | 10 | 0 | 0.7 ms |
+| 4 | 21 | 41 | 22 | 3 | 2.4 ms |
+| 24 | 101 | 201 | 102 | 23 | 14.1 ms |
+
+The general counts are `4N+5` faces, `8N+9` edges, and `4N+6` vertices. The 24-turn STEP contains 25 cylinder faces, 72 B-spline side faces, and four planes. Its importer reports 392 pcurves and two seam pcurve pairs.
+
+## Canonical witness and interchange
+
+The kernel witness has a 6.4 mm root diameter, 8.0 mm crest diameter, 1.25 mm pitch, 1.1 mm root width, 0.1 mm crest width, and 30 mm centerline span: exactly 24 turns. The support extends from `z=-1` to `z=32.1` mm, leaving 1 mm exposed margin outside each full rib footprint. These are metric-like envelope dimensions, not a qualified thread standard.
+
+The production AP242 file is generated at `artifacts/local/helical-rib-x1/helical-rib-24.step`. `aetheris analyze` reimported it and reported one body, one shell, 101 faces, 201 edges, 102 vertices, bounding box `[-4,-4,-1]` to `[4,4,32.1]` mm, and `enclosed-manifold` structural assessment. Its orientation report found 101 source agreements and no mismatches or ambiguous components. Roundtrip tests also check imported root/crest radius samples and the 1.25 mm axial displacement between consecutive leading-root seam vertices. The supplied McMaster STEP pair is dimensional and visual context only; this witness is authored from X0 geometry rather than reconstructed from imported topology.
+
+The supported BRep display tessellator produced nonempty patches for all 101 faces and 375,078 triangles. The shaded [24-turn render](artifacts/helical-rib-x1.png) shows the continuous rib, support margins, and planar terminations without a visible missing wedge or exploding seam. The image is a derived display artifact; the STEP and exact rib parameters are the engineering authorities. One-loop cylinder faces with inclined pcurves now use trim-aware tessellation: the legacy bounding-rectangle display path had visibly overfilled the narrow interturn gaps and inflated display volume to 1,947 mm³. The volume regression assertion prevents that fallback from silently returning.
+
+To regenerate the STEP, display OBJ, metrics, and render in PowerShell from the repository root (the Python renderer uses NumPy and Pillow):
+
+```powershell
+$env:AETHERIS_HELICAL_RIB_ARTIFACT_DIR = (Join-Path (Get-Location) 'artifacts/local/helical-rib-x1')
+dotnet test Aetheris.Kernel.Core.Tests -c Release --filter FullyQualifiedName~WriteCanonicalWitnessWhenRequested
+python scripts/render-helical-rib-x1.py artifacts/local/helical-rib-x1
+```
+
+The promoted PNG is the compact release visual; the STEP/OBJ and run metrics remain ignored local artifacts under the repository generated-artifact policy.
+
+## Representative performance
+
+One local Release run of the 24-turn witness measured 75 ms for initial BRep construction and validation, 4.51 s for supported display tessellation, 116 ms for AP242 export, and 4.52 s for Aetheris STEP reimport. The STEP file is 5,460,677 bytes. Warm in-process build times appear in the topology table. These are single-run measurements on the development machine, not a benchmark distribution. Face/edge counts scale linearly with turn count; display tessellation and reimport are the largest measured costs.
+
+## Verification and limits
+
+Focused tests cover 1, 4, and 24 turns; face/edge/vertex counts; every edge's two opposite coedges; pcurve consistency; display volume within 1% of the analytic envelope; STEP export/reimport; nonempty tessellation patches; pitch, crest-depth, start-phase, and transformed-axis changes; and explicit stock-end-contact rejection. X0 tests provide adjacent-turn self-intersection rejection and finite-realization bounds. The canonical artifact test is opt-in through `AETHERIS_HELICAL_RIB_ARTIFACT_DIR`, so normal test runs do not write output.
+
+The phase-alignment test found and fixed an initial mismatch between the rib phase and support cylinder/cap reference frames. Start/end contact with stock end faces, partial turns, runout, arbitrary profile shapes, generic sweeps/booleans, and public Thread semantics remain outside X1. The imported STEP length unit is currently reported as assumed millimetres by the general importer; the exported witness coordinates and bbox were checked directly.
+
+The Release solution build passed. The fast Core lane passed 1000/1000; the corpus-inclusive Core lane passed 1133/1133; Firmament passed 1649/1649. The conclusive full solution command exits nonzero only on the established baseline of two CLI tests and five SheetMetal tests. One intervening full run hit two existing Core tests' 10-second tessellation budgets; both passed immediately in isolation, and the subsequent corpus-inclusive Core and full solution runs passed 1133/1133. No X1 assertion failed.
diff --git a/docs/release/THREAD-EXTERNAL-X0.md b/docs/release/THREAD-EXTERNAL-X0.md
new file mode 100644
index 00000000..f19ad073
--- /dev/null
+++ b/docs/release/THREAD-EXTERNAL-X0.md
@@ -0,0 +1,35 @@
+# THREAD-EXTERNAL-X0 — qualification stop
+
+**Verdict: Honest stop.** Aetheris cannot currently construct and export a closed, exact external helical thread through one Firmament feature. The existing `Helix` construct materializes a WireForm centerline, while `SurfaceFeatureValidator` explicitly routes thread/helical surface features to a non-emitting Forge plan. Core has bounded extrusion, revolution, and some analytic Boolean families, but no qualified profile-along-helix BRep emitter with start/end closure. Adding a syntax-only `Thread` would misrepresent material geometry, so X0 does not admit one.
+
+## Supplied reference evidence
+
+Local inputs (not copied into the repository): `91280A546_NO THREADS_Medium-Strength Class 8.8 Steel Hex Head Screw.STEP` and `91280A546_Medium-Strength Class 8.8 Steel Hex Head Screw.STEP`. Reproduce the smooth-body inspection with `dotnet run --project Aetheris.CLI -- analyze <smooth.step> --json` and the threaded import failure with the same command on `<threaded.step>`. Both files declare millimetres through `SI_UNIT(.MILLI.,.METRE.)`. The table separates import-verified values from direct STEP-entity inventory and inferences.
+
+| Feature | Smooth McMaster | Threaded McMaster | Evidence / qualification |
+| --- | ---: | ---: | --- |
+| Topology | 62 faces, 148 edges, 96 vertices | 147 faces, 405 edges, 268 vertices | Smooth: CLI import; threaded: direct `ADVANCED_FACE`, `EDGE_CURVE`, `VERTEX_POINT` record counts, not imported topology validation. |
+| Closed shell | 1 | 1 | Direct `CLOSED_SHELL` records; CLI also assesses smooth body as enclosed manifold. Threaded manifold status is unverified. |
+| Overall vertex bounds | X ±6.5, Y ±7.50555, Z ±27.65 mm | Same | Direct `VERTEX_POINT` coordinate references. The head is at positive Z, tip at negative Z. |
+| Major diameter | 8 mm | 8 mm | Smooth has two, threaded has 79 `CYLINDRICAL_SURFACE` records of radius 4 mm. These records support nominal major size but do not alone certify every crest. |
+| Smooth shank extent | Z −26.7125 to +22.35 mm at radius 4; tip ends at −27.65 mm, radius 3.0625 | — | Smooth STEP vertex and analytic-cylinder inspection. Shank length under head to tip is 50 mm, with a 0.9375 mm tip chamfer. |
+| Minor/root diameter | — | At least one end-region vertex radius 3.18810 mm (diameter 6.37620 mm) | This is a vertex sample, **not** a certified minimum over the thread surface. Exact root diameter remains unmeasured. |
+| Pitch | — | 0.625 mm repeated axial vertex interval; 1.25 mm full pitch is consistent with two phase intervals | Inferred from repeated thread vertex levels. Helix curve/surface parameterization has not been imported and qualified. |
+| Thread length/start/end | Smooth stock provides 50 mm shank | Thread records span much of Z −27.65 to +22.35 mm; exact root and runout bounds unverified | Reference thread start, termination, and runout require successful weighted-curve and swept-surface interpretation. |
+| Aetheris modeled witness | Not built for part 91280A546 | Not built | No X0 `Thread` materializer or STEP result exists. Deviations cannot honestly be reported. |
+
+The smooth body imports with 32 B-spline surfaces and 76 polynomial B-spline curves. The threaded file contains 160 `RATIONAL_B_SPLINE_CURVE` records. `aetheris analyze` fails on the first non-circular weighted curve: `Importer.Geometry.RationalBSplineCurve`, with `step242-rational-bspline-circle-fit-residual-exceeded`. Core's `CurveGeometry` has a polynomial `BSpline3` but no weighted-curve variant. Dropping rational weights would change the reference geometry and is not a qualified import route. The importer now names this exact dependency in its diagnostic.
+
+## Intended semantic and geometry boundary
+
+The admitted future intent is an external, cylindrical, constant-pitch, single-start, right-hand, 60-degree metric-style thread. It must own axis, major diameter, pitch, lead (= pitch), axial range, handedness, and profile family. A thread-specific 60-degree profile needs bounded crest, flank, root, and truncation; turn count derives from length/pitch. A major-diameter stock cylinder with a cut helical groove is the most direct candidate for this supplied smooth 8 mm blank, but the choice cannot be qualified until the helical wall, intersections with the stock cylinder, and planar start/end closures form one manifold BRep. No Boolean or mesh fallback is accepted here.
+
+The existing HexBolt template at `fixtures/Compatibility/LegacyV1/Examples/hexbolt_template_m2.firmament` is a different McMaster part (91180A151, 35 mm shank), so it cannot silently serve as the 91280A546 witness. Its `SemanticAxialRegion ThreadRegion` is metadata with `MaterialGeometry: Cylinder`; it is not modeled thread geometry. A future 91280A546 witness should reuse its typed template architecture with a measured 50 mm specification and add exactly one Thread construct targeting the shank face. Head text marking is excluded.
+
+## Missing qualification primitive
+
+The next materializer needs a bounded helical profile sweep or equivalent direct screw-surface construction whose side faces, crest/root surfaces, seam edges, and clipped start/end caps are all exact or carry an explicit bounded realization error. It must emit a closed, consistently oriented BRep accepted by `BrepExportPreflight`, the display tessellator, STEP exporter, and STEP reimporter. The reference-analysis side separately needs weighted B-spline curve support (or a certified exact recovery for the particular curves) to measure profile and overlay accurately. These are substantive geometry representations, not a small parser addition.
+
+## Acceptance status
+
+No authored Thread source, source map, schema/LX exposure, modeled bolt, render, topology, STEP round trip, or construction/tessellation/export timings are claimed. The smooth reference inspection succeeds; the threaded reference import has the specific weighted-curve blocker above. Until the helical BRep primitive exists, a proposed `Thread` syntax or semantic-only feature would fail the mission's real modeled-geometry criterion.
diff --git a/docs/release/artifacts/helical-rib-x1.png b/docs/release/artifacts/helical-rib-x1.png
new file mode 100644
index 00000000..7faf09f1
Binary files /dev/null and b/docs/release/artifacts/helical-rib-x1.png differ
diff --git a/scripts/render-helical-rib-x1.py b/scripts/render-helical-rib-x1.py
new file mode 100644
index 00000000..d00abeb6
--- /dev/null
+++ b/scripts/render-helical-rib-x1.py
@@ -0,0 +1,46 @@
+from pathlib import Path
+import sys
+import numpy as np
+from PIL import Image, ImageDraw
+
+root = Path(sys.argv[1]) if len(sys.argv) > 1 else Path("artifacts/local/helical-rib-x1")
+root.mkdir(parents=True, exist_ok=True)
+vertices = []
+faces = []
+with (root / "helical-rib-24.obj").open() as stream:
+ for line in stream:
+ if line.startswith("v "):
+ vertices.append([float(x) for x in line.split()[1:]])
+ elif line.startswith("f "):
+ faces.append([int(x) - 1 for x in line.split()[1:]])
+points = np.asarray(vertices)
+triangles = np.asarray(faces)
+center = np.array([0.0, 0.0, 15.55])
+view = np.array([1.0, -1.5, 0.65])
+view /= np.linalg.norm(view)
+right = np.cross([0.0, 0.0, 1.0], view)
+right /= np.linalg.norm(right)
+up = np.cross(view, right)
+projected = np.column_stack(((points-center) @ right, (points-center) @ up, (points-center) @ view))
+width, height = 1400, 1600
+scale = min((width-180)/(np.ptp(projected[:,0])), (height-180)/(np.ptp(projected[:,1])))
+xy = np.column_stack((width/2 + projected[:,0]*scale, height/2-projected[:,1]*scale))
+verts = points[triangles]
+normals = np.cross(verts[:,1]-verts[:,0], verts[:,2]-verts[:,0])
+normlen = np.linalg.norm(normals, axis=1)
+valid = normlen > 1e-13
+normals[valid] /= normlen[valid,None]
+light = np.array([0.5,-0.7,0.6])
+light /= np.linalg.norm(light)
+brightness = np.clip(0.4 + 0.6*(normals @ light), 0.18, 1.0)
+depth = projected[triangles,2].mean(axis=1)
+visible = np.where(valid & ((normals @ view) > 0))[0]
+order = visible[np.argsort(depth[visible])]
+image = Image.new("RGB", (width,height), (245,247,251))
+draw = ImageDraw.Draw(image)
+for index in order:
+ shade = float(brightness[index])
+ color = (int(58+118*shade), int(83+130*shade), int(121+124*shade))
+ draw.polygon([tuple(xy[v]) for v in triangles[index]], fill=color)
+image.save(root / "helical-rib-24.png")
+print(len(order), "visible triangles")