Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Expose coil winding semantics and approximation evidence

Yuechen Lifd680ed81e89
diff --git a/Aetheris.CLI.Tests/CircularSweepCliTests.cs b/Aetheris.CLI.Tests/CircularSweepCliTests.cs
index 41e3269b..dfa68e57 100644
--- a/Aetheris.CLI.Tests/CircularSweepCliTests.cs
+++ b/Aetheris.CLI.Tests/CircularSweepCliTests.cs
@@ -4,6 +4,15 @@ namespace Aetheris.CLI.Tests;
public sealed class CircularSweepCliTests
{
+ [Fact]
+ public void AxisCoilInspectExposesWindingAndApproximationEvidence()
+ {
+ var fixture = Path.Combine(RepoRoot(), "fixtures", "Canonical", "WireForm", "axis-coil.firmament");
+ var output = new StringWriter(); var error = new StringWriter();
+ Assert.Equal(0, Aetheris.CLI.CliRunner.Run(["inspect", fixture, "--json"], output, error)); Assert.Empty(error.ToString());
+ using var json = JsonDocument.Parse(output.ToString()); var wire = json.RootElement.GetProperty("wireForm"); Assert.Equal(1, wire.GetProperty("coilCount").GetInt32());
+ var operation = wire.GetProperty("operations")[0]; Assert.Equal("AxisCoil", operation.GetProperty("kind").GetString()); Assert.Equal(8d, operation.GetProperty("turns").GetDouble()); Assert.Equal("RightHanded", operation.GetProperty("handedness").GetString()); Assert.Equal(256, operation.GetProperty("approximationSegmentCount").GetInt32()); Assert.True(operation.GetProperty("approximationMaxError").GetDouble() <= operation.GetProperty("approximationTolerance").GetDouble());
+ }
[Fact]
public void PaperclipValidateAndInspectUseWireFormSemanticRoute()
{
diff --git a/Aetheris.CLI/CliRunner.cs b/Aetheris.CLI/CliRunner.cs
index a6a2009d..96c3783b 100644
--- a/Aetheris.CLI/CliRunner.cs
+++ b/Aetheris.CLI/CliRunner.cs
@@ -1362,14 +1362,23 @@ Model CanonicalPanel {
wireForm = wire is null ? null : new
{
wireFormId = wire.Name, diameter = wire.DiameterMm, material = wire.Material.Identity.FirmamentPath,
- operationCount = wire.Operations.Count, straightCount = wire.Operations.Count(x => x is WireStraightAir), bendCount = wire.Operations.Count(x => x is WireBendAir),
- totalStraightLength = wire.TotalStraightLengthMm, totalBendLength = wire.TotalBendLengthMm, totalWireLength = wire.TotalWireLengthMm,
+ operationCount = wire.Operations.Count, straightCount = wire.Operations.Count(x => x is WireStraightAir), bendCount = wire.Operations.Count(x => x is WireBendAir), coilCount = wire.Operations.Count(x => x is WireCoilAir),
+ totalStraightLength = wire.TotalStraightLengthMm, totalBendLength = wire.TotalBendLengthMm, totalCoilLength = wire.TotalCoilLengthMm, totalWireLength = wire.TotalWireLengthMm,
bendRadiusSemantics = "CenterlineRadius", frameTransportPolicy = wire.FrameTransportPolicy,
startTerminal = new { position = new[] { wire.StartState.Position.X, wire.StartState.Position.Y, wire.StartState.Position.Z }, tangent = new[] { wire.StartState.Tangent.X, wire.StartState.Tangent.Y, wire.StartState.Tangent.Z }, diameter = wire.DiameterMm },
endTerminal = new { position = new[] { wire.EndState.Position.X, wire.EndState.Position.Y, wire.EndState.Position.Z }, tangent = new[] { wire.EndState.Tangent.X, wire.EndState.Tangent.Y, wire.EndState.Tangent.Z }, diameter = wire.DiameterMm },
- operations = wire.Operations.Select(operation => new { operation.Ordinal, operation.Name, kind = operation is WireStraightAir ? "Straight" : "Bend", operation.LengthMm,
+ operations = wire.Operations.Select(operation => new { operation.Ordinal, operation.Name, kind = operation switch { WireStraightAir => "Straight", WireBendAir => "Bend", WireAxisCoilAir => "AxisCoil", WireSurfaceCoilAir => "SurfaceCoil", _ => "Unknown" }, operation.LengthMm,
radius = operation is WireBendAir bend ? bend.RadiusMm : (double?)null, angleDegrees = operation is WireBendAir angle ? angle.AngleRadians * 180d / Math.PI : (double?)null,
- plane = operation is WireBendAir plane ? plane.Plane : null, stableId = operation.StableId(wire.Name), input = operation.Input, output = operation.Output })
+ plane = operation is WireBendAir plane ? plane.Plane : null, coilKind = operation is WireCoilAir coil ? coil.CoilKind : null,
+ turns = operation is WireCoilAir turns ? turns.Turns : (double?)null, handedness = operation is WireCoilAir handed ? handed.Handedness.ToString() : null,
+ pitch = operation switch { WireAxisCoilAir axis => axis.PitchMm, WireSurfaceCoilAir surface => surface.AxialPitchMm, _ => (double?)null },
+ progressionLaw = operation is WireCoilAir progression ? progression.ProgressionLaw : null, selfClearance = operation is WireCoilAir self ? self.MinimumSelfClearanceMm : (double?)null,
+ supportClearance = operation is WireCoilAir support ? support.SupportClearanceMm : null, representation = operation is WireCoilAir ? "ExactEvaluableWindingLaw->NonRationalBSplineTube" : "Analytic",
+ approximationTolerance = operation is WireCoilAir tolerance ? tolerance.ApproximationToleranceMm : (double?)null,
+ approximationSegmentCount = operation is WireCoilAir segments ? segments.ApproximationSegmentCount : (int?)null,
+ approximationMaxError = operation is WireCoilAir maxError ? maxError.ApproximationError.MaxMm : (double?)null,
+ approximationRmsError = operation is WireCoilAir rmsError ? rmsError.ApproximationError.RmsMm : (double?)null,
+ stableId = operation.StableId(wire.Name), input = operation.Input, output = operation.Output })
}, diagnostics = wireDiagnostics
};
if (json) stdout.WriteLine(JsonSerializer.Serialize(wireReportPayload, JsonOptions));
diff --git a/Aetheris.Kernel.Firmament.Tests/WireFormTests.cs b/Aetheris.Kernel.Firmament.Tests/WireFormTests.cs
index 8a607e7a..5f09d899 100644
--- a/Aetheris.Kernel.Firmament.Tests/WireFormTests.cs
+++ b/Aetheris.Kernel.Firmament.Tests/WireFormTests.cs
@@ -7,6 +7,65 @@ namespace Aetheris.Kernel.Firmament.Tests;
public sealed class WireFormTests
{
+ [Fact]
+ public void AxisCoil_LowersSemanticHelixToNonRationalSplineTube()
+ {
+ var source = File.ReadAllText(Fixture("Canonical", "WireForm", "axis-coil.firmament"));
+ var authored = WireFormAuthoring.Parse(source);
+ Assert.True(authored.IsSuccess, string.Join(Environment.NewLine, authored.Diagnostics.Select(x => x.Message)));
+ var coil = Assert.IsType<WireAxisCoilAir>(Assert.Single(authored.Value.Operations));
+ Assert.Equal(12d, coil.RadiusMm); Assert.Equal(8d, coil.Turns); Assert.Equal(5d, coil.PitchMm); Assert.Equal(40d, coil.HeightMm);
+ Assert.Equal(Math.Sqrt(Math.Pow(2d * Math.PI * 12d * 8d, 2d) + 1600d), coil.LengthMm, 10);
+ Assert.Equal(3d, coil.MinimumSelfClearanceMm, 10);
+ var built = WireFormBRepMaterializer.Build(authored.Value); Assert.True(built.IsSuccess, string.Join(Environment.NewLine, built.Diagnostics.Select(x => x.Message)));
+ Assert.All(built.Value.Body.Topology.Edges, edge => Assert.Equal(2, built.Value.Body.Topology.Coedges.Count(use => use.EdgeId == edge.Id)));
+ var step = Step242Exporter.ExportBody(built.Value.Body); Assert.True(step.IsSuccess);
+ var imported = Step242Importer.ImportBody(step.Value); Assert.True(imported.IsSuccess, string.Join(Environment.NewLine, imported.Diagnostics.Select(x => x.Message)));
+ var bad = imported.Value!.Topology.Edges.Select(edge => (edge, count: imported.Value.Topology.Coedges.Count(use => use.EdgeId == edge.Id))).Where(x => x.count != 2).ToArray();
+ Assert.True(bad.Length == 0, $"Nonmanifold imported edges: {string.Join(",", bad.Take(20).Select(x => $"{x.edge.Id.Value}:{x.count}"))}; edges={imported.Value.Topology.Edges.Count()}, coedges={imported.Value.Topology.Coedges.Count()}");
+ }
+ [Fact]
+ public void CoilParameterResolution_HandednessAndTerminalCompositionAreDeterministic()
+ {
+ var right = WireFormAuthoring.Parse(File.ReadAllText(Fixture("Canonical", "WireForm", "axis-coil.firmament"))).Value;
+ var left = WireFormAuthoring.Parse(File.ReadAllText(Fixture("Canonical", "WireForm", "left-handed-axis-coil.firmament"))).Value;
+ Assert.Equal(WireCoilHandedness.RightHanded, Assert.IsType<WireAxisCoilAir>(right.Operations[0]).Handedness);
+ var leftCoil = Assert.IsType<WireAxisCoilAir>(left.Operations[0]); Assert.Equal(5d, leftCoil.PitchMm); Assert.Equal(WireCoilHandedness.LeftHanded, leftCoil.Handedness);
+ var composed = WireFormAuthoring.Parse(File.ReadAllText(Fixture("Canonical", "WireForm", "straight-coil-straight.firmament"))).Value;
+ Assert.Equal(composed.Operations[0].Output, composed.Operations[1].Input); Assert.Equal(composed.Operations[1].Output, composed.Operations[2].Input);
+ Assert.True(Math.Abs(WireFormAuthoring.Dot(composed.Operations[0].Output.Tangent.ToVector(), composed.Operations[1].Input.Tangent.ToVector()) - 1d) < 1e-12);
+ }
+
+ [Fact]
+ public void CylinderSurfaceCoil_IsAxisCoilEquivalentAndSurfaceFamiliesRetainClearanceLaw()
+ {
+ var surface = WireFormAuthoring.Parse(File.ReadAllText(Fixture("Canonical", "WireForm", "cylinder-surface-coil.firmament"))).Value;
+ var cylinder = Assert.IsType<WireSurfaceCoilAir>(surface.Operations[0]); Assert.Equal("Cylinder", cylinder.SupportKind); Assert.Equal(1d, cylinder.MeasuredSupportClearanceMm);
+ var axisSource = File.ReadAllText(Fixture("Canonical", "WireForm", "axis-coil.firmament")).Replace("Radius: 12mm", "Radius: 12mm").Replace("Turns: 8", "Turns: 6").Replace("Pitch: 5mm", "Pitch: 5mm");
+ var axis = Assert.IsType<WireAxisCoilAir>(WireFormAuthoring.Parse(axisSource).Value.Operations[0]);
+ for (var i = 0; i <= 100; i++) Assert.True((axis.Evaluate(i / 100d) - cylinder.Evaluate(i / 100d)).Length < 1e-9);
+ foreach (var fixture in new[] { "frustum-surface-coil", "sphere-surface-coil" }) { var parsed = WireFormAuthoring.Parse(File.ReadAllText(Fixture("Canonical", "WireForm", fixture + ".firmament"))); Assert.True(parsed.IsSuccess); var coil = Assert.IsType<WireSurfaceCoilAir>(parsed.Value.Operations[0]); Assert.Equal(1d, coil.MeasuredSupportClearanceMm); Assert.True(coil.MinimumSelfClearanceMm > 0d); Assert.True(coil.ApproximationError.MaxMm <= coil.ApproximationToleranceMm); }
+ var blender = Assert.IsType<WireSurfaceCoilAir>(WireFormAuthoring.Parse(File.ReadAllText(Fixture("Canonical", "WireForm", "blender-ball-coil.firmament"))).Value.Operations[0]);
+ Assert.Equal("Sphere", blender.SupportKind); Assert.Equal("CaptiveBallProxy", blender.SupportName); Assert.Equal("LatitudeProgression", blender.ProgressionLaw);
+ }
+
+ [Theory]
+ [InlineData("coil-radius-zero.firmament", "wireform-coil-radius-invalid")]
+ [InlineData("coil-turns-zero.firmament", "wireform-coil-turns-invalid")]
+ [InlineData("coil-parameters-inconsistent.firmament", "wireform-coil-parameters-inconsistent")]
+ [InlineData("surfacecoil-offset-invalid.firmament", "wireform-surfacecoil-offset-invalid")]
+ [InlineData("surfacecoil-pole-singularity.firmament", "wireform-surfacecoil-pole-singularity")]
+ [InlineData("surfacecoil-support-unsupported.firmament", "wireform-surfacecoil-support-unsupported")]
+ public void InvalidCoils_FailWithTypedActionableDiagnostics(string fixture, string code)
+ {
+ var result = WireFormAuthoring.Parse(File.ReadAllText(Fixture("Invalid", "WireForm", fixture))); Assert.False(result.IsSuccess); Assert.Contains(result.Diagnostics, diagnostic => diagnostic.Message.Contains(code, StringComparison.Ordinal));
+ }
+
+ [Fact]
+ public void OverlappingTurnsFailValidation()
+ {
+ var parsed = WireFormAuthoring.Parse(File.ReadAllText(Fixture("Invalid", "WireForm", "coil-turn-overlap.firmament"))); Assert.True(parsed.IsSuccess); Assert.Contains(WireFormBRepMaterializer.Validate(parsed.Value), diagnostic => diagnostic.Contains("wireform-coil-turn-clearance", StringComparison.Ordinal));
+ }
[Fact]
public void Paperclip_ReplaysExactSemanticProgramAndStockAccounting()
{
diff --git a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
index da59fd56..7ea274da 100644
--- a/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentBuildAndExport.cs
@@ -312,7 +312,7 @@ public static class FirmamentBuildAndExport
return KernelResult<FirmamentStepExportResult>.Success(new FirmamentStepExportResult(step.Value, authored.Value.Name, 0,
"wire-form", "wireform", WireForm: report,
EngineeringFeatures: authored.Value.Operations.Select(operation => new FirmamentEngineeringFeatureReport(
- operation.Name, operation is WireStraightAir ? "Straight" : "Bend", operation.StableId(authored.Value.Name),
+ operation.Name, operation switch { WireStraightAir => "Straight", WireBendAir => "Bend", WireAxisCoilAir => "AxisCoil", WireSurfaceCoilAir => "SurfaceCoil", _ => "Unknown" }, operation.StableId(authored.Value.Name),
authored.Value.Name, "WireState", "CircularSection", operation.LengthMm, "CenterlineLength", "Add",
PolicySource: "WireFormFeatureAir", MaterializationRoute: "WireFormCenterlineAir->CircularSweepBRepPlan")).ToArray()), []);
}
diff --git a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
index 91988287..4bfc7c4f 100644
--- a/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
+++ b/Aetheris.Kernel.Firmament/FirmamentStepExportResult.cs
@@ -35,7 +35,12 @@ public sealed record FirmamentWireStateReport(
public sealed record FirmamentWireOperationReport(
int Ordinal, string Name, string Kind, double LengthMm, double? RadiusMm, double? AngleDegrees,
string? Plane, string StableId, FirmamentWireStateReport Input, FirmamentWireStateReport Output,
- string CenterlineSegment, string SweepSurface);
+ string CenterlineSegment, string SweepSurface,
+ string? CoilKind = null, double? Turns = null, string? Handedness = null, double? PitchMm = null,
+ double? HeightMm = null, double? StartPhaseDegrees = null, string? Support = null, string? Side = null,
+ string? ProgressionLaw = null, double? MinimumSelfClearanceMm = null, double? SupportClearanceMm = null,
+ double? CenterlineApproximationToleranceMm = null, int? CenterlineApproximationSegmentCount = null,
+ double? CenterlineApproximationMaxErrorMm = null, double? CenterlineApproximationRmsErrorMm = null);
public sealed record FirmamentWireTerminalReport(
string Name, IReadOnlyList<double> Position, IReadOnlyList<double> Tangent, IReadOnlyList<double> Up, double DiameterMm);
@@ -48,7 +53,10 @@ public sealed record FirmamentWireFormReport(
string SelfIntersectionValidation, string FrameTransportPolicy, IReadOnlyList<FirmamentWireOperationReport> Operations,
IReadOnlyList<double> Bounds, int Cylinders, int Tori, int Planes, int OtherSurfaces,
int RationalProductSurfaces, int FacetedFallback, bool EnclosedManifold, string StepSha256,
- bool StepReimportSucceeded, bool StepReimportedManifold);
+ bool StepReimportSucceeded, bool StepReimportedManifold,
+ int CoilCount = 0, double TotalCoilLengthMm = 0d, double? MinimumSelfClearanceMm = null,
+ int NonRationalBSplineSurfaces = 0, int MaximumPolynomialDegree = 0,
+ string CoilRepresentation = "NotApplicable");
public sealed record FirmamentSemanticPatternReport(
string Name,
diff --git a/Aetheris.Kernel.Firmament/Materializer/WireCoils.cs b/Aetheris.Kernel.Firmament/Materializer/WireCoils.cs
new file mode 100644
index 00000000..1d27dcb3
--- /dev/null
+++ b/Aetheris.Kernel.Firmament/Materializer/WireCoils.cs
@@ -0,0 +1,265 @@
+using System.Globalization;
+using System.Text.RegularExpressions;
+using Aetheris.Kernel.Core.Brep;
+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.Firmament.Materializer;
+
+internal static class WireCoilAuthoring
+{
+ private const double ApproximationTolerance = 0.01d;
+
+ internal static KernelResult<WireAxisCoilAir> CreateAxis(string name, int ordinal, string body, WireState input, double diameter)
+ {
+ if (!Length(body, "Radius", out var radius) || radius <= 0d) return FailAxis("wireform-coil-radius-invalid", name, "Radius must be finite and greater than zero.");
+ if (!Number(body, "Turns", out var turns) || turns <= 0d) return FailAxis("wireform-coil-turns-invalid", name, "Turns must be finite and greater than zero.");
+ var hasPitch = Length(body, "Pitch", out var pitch); var hasHeight = Length(body, "Height", out var height);
+ if (!hasPitch && !hasHeight) return FailAxis("wireform-coil-parameters-inconsistent", name, "Specify Turns and either Pitch or Height.");
+ if (hasPitch && pitch <= 0d || hasHeight && height <= 0d) return FailAxis("wireform-coil-parameters-inconsistent", name, "Pitch and Height must be greater than zero.");
+ if (!hasPitch) pitch = height / turns; else if (!hasHeight) height = pitch * turns;
+ else if (Math.Abs(height - pitch * turns) > 1e-8 * Math.Max(1d, height))
+ return FailAxis("wireform-coil-parameters-inconsistent", name, $"Height must equal Turns × Pitch ({turns * pitch:G12} mm).");
+ if (!Hand(body, out var hand)) return FailAxis("wireform-coil-handedness-invalid", name, "Handedness must be RightHanded or LeftHanded.");
+ if (!Phase(body, out var phase)) return FailAxis("wireform-coil-start-phase-invalid", name, "StartPhase must be a finite angle.");
+ var sign = hand == WireCoilHandedness.RightHanded ? 1d : -1d;
+ var q = height / (2d * Math.PI * turns);
+ var axis = Direction3D.Create(input.Tangent.ToVector() * q + input.Up.ToVector() * (sign * radius));
+ var radial = input.Right;
+ if (Math.Abs(phase) > 1e-15) { axis = Direction3D.Create(Rotate(axis.ToVector(), input.Tangent.ToVector(), phase)); radial = Direction3D.Create(Rotate(radial.ToVector(), input.Tangent.ToVector(), phase)); }
+ var origin = input.Position - radial.ToVector() * radius;
+ var length = Math.Sqrt(Math.Pow(2d * Math.PI * radius * turns, 2d) + height * height);
+ var clearance = pitch - diameter;
+ var prototype = new WireAxisCoilAir(name, ordinal, radius, turns, pitch, height, hand, phase, origin, axis, radial,
+ input, input, length, clearance, ApproximationTolerance);
+ var endPosition = prototype.Evaluate(1d); var endTangent = prototype.Tangent(1d);
+ var endUp = WireCoilGeometry.TransportUp(input.Up, prototype.Tangent, Math.Max(32, (int)Math.Ceiling(turns * 32d)));
+ var output = new WireState(endPosition, endTangent, endUp, input.AccumulatedLengthMm + length);
+ return KernelResult<WireAxisCoilAir>.Success(prototype with { Output = output });
+ }
+
+ internal static KernelResult<WireSurfaceCoilAir> CreateSurface(string source, string name, int ordinal, string body, WireState input, double diameter)
+ {
+ var supportName = WireFormAuthoring.Property(body, "Surface") ?? WireFormAuthoring.Property(body, "Support");
+ if (string.IsNullOrWhiteSpace(supportName)) return FailSurface("wireform-surfacecoil-support-unsupported", name, "Surface must name an authored Cylinder, Frustum, Cone, or Sphere.");
+ var declaration = Regex.Match(source, $@"\b(?<kind>Cylinder|Frustum|Cone|Sphere)\s+{Regex.Escape(supportName.Trim())}\s*\{{", RegexOptions.CultureInvariant);
+ if (!declaration.Success) return FailSurface("wireform-surfacecoil-support-unsupported", supportName.Trim(), "Only authored analytic Cylinder, Frustum/Cone, and Sphere supports are admitted.");
+ var open = source.IndexOf('{', declaration.Index); var close = MatchingBrace(source, open);
+ if (close < 0) return FailSurface("wireform-surfacecoil-support-unsupported", supportName.Trim(), "Support declaration is malformed.");
+ var supportBody = source[(open + 1)..close]; var kind = declaration.Groups["kind"].Value; if (kind == "Cone") kind = "Frustum";
+ if (!Number(body, "Turns", out var turns) || turns <= 0d) return FailSurface("wireform-coil-turns-invalid", name, "Turns must be finite and greater than zero.");
+ if (!Hand(body, out var hand)) return FailSurface("wireform-coil-handedness-invalid", name, "Handedness must be RightHanded or LeftHanded.");
+ if (!Phase(body, out var phase)) return FailSurface("wireform-coil-start-phase-invalid", name, "StartPhase must be a finite angle.");
+ var sideText = WireFormAuthoring.Property(body, "Side") ?? "Outside";
+ if (!Enum.TryParse<WireSurfaceSide>(sideText, false, out var side)) return FailSurface("wireform-surfacecoil-side-invalid", name, "Side must be Outside or Inside.");
+ var hasClearance = Length(body, "Clearance", out var clearance); var hasOffset = Length(body, "CenterlineOffset", out var offset);
+ if (hasClearance == hasOffset) return FailSurface("wireform-surfacecoil-offset-invalid", name, "Specify exactly one of Clearance or CenterlineOffset.");
+ if (hasClearance && clearance < 0d || hasOffset && offset <= 0d) return FailSurface("wireform-surfacecoil-offset-invalid", name, "Clearance cannot be negative and CenterlineOffset must be positive.");
+ if (hasClearance) offset = diameter / 2d + clearance; else clearance = offset - diameter / 2d;
+ if (clearance < -1e-9) return FailSurface("wireform-surfacecoil-offset-invalid", name, "CenterlineOffset is smaller than the wire radius and would penetrate the support.");
+
+ double r0, r1, supportHeight, pitch = 0d, startLat = 0d, endLat = 0d;
+ if (kind == "Sphere")
+ {
+ if (!Length(supportBody, "Radius", out r0) || r0 <= 0d) return FailSurface("wireform-surfacecoil-support-unsupported", supportName.Trim(), "Sphere Radius must be positive.");
+ r1 = r0; supportHeight = 2d * r0;
+ if (!Angle(body, "StartLatitude", out startLat) || !Angle(body, "EndLatitude", out endLat)) return FailSurface("wireform-surfacecoil-pole-singularity", name, "Sphere winding requires StartLatitude and EndLatitude.");
+ if (Math.Abs(startLat) >= Math.PI / 2d - 1e-6 || Math.Abs(endLat) >= Math.PI / 2d - 1e-6)
+ return FailSurface("wireform-surfacecoil-pole-singularity", name, "Latitude bounds must remain away from ±90 degrees.");
+ var rho = side == WireSurfaceSide.Outside ? r0 + offset : r0 - offset;
+ if (rho <= diameter / 2d) return FailSurface("wireform-surfacecoil-offset-invalid", name, "Inward sphere offset collapses the usable support.");
+ }
+ else
+ {
+ if (kind == "Cylinder")
+ {
+ if (!Length(supportBody, "Radius", out r0) || r0 <= 0d) return FailSurface("wireform-surfacecoil-support-unsupported", supportName.Trim(), "Cylinder Radius must be positive.");
+ r1 = r0;
+ }
+ else
+ {
+ if (!Length(supportBody, "BottomRadius", out r0) || !Length(supportBody, "TopRadius", out r1) || r0 < 0d || r1 < 0d || r0 + r1 <= 0d)
+ return FailSurface("wireform-surfacecoil-support-unsupported", supportName.Trim(), "Frustum requires nonnegative BottomRadius and TopRadius.");
+ }
+ if (!Length(supportBody, "Height", out supportHeight) || supportHeight <= 0d) return FailSurface("wireform-surfacecoil-support-unsupported", supportName.Trim(), "Support Height must be positive.");
+ if (!Length(body, "AxialPitch", out pitch) && !Length(body, "Pitch", out pitch) || pitch <= 0d) return FailSurface("wireform-coil-parameters-inconsistent", name, "Cylinder/frustum winding requires positive AxialPitch.");
+ if (turns * pitch > supportHeight + 1e-9) return FailSurface("wireform-surfacecoil-span-invalid", name, "Turns × AxialPitch exceeds support Height.");
+ }
+
+ var sign = hand == WireCoilHandedness.RightHanded ? 1d : -1d;
+ Direction3D axis, radial, longitude, latitude; Point3D origin;
+ if (kind == "Sphere")
+ {
+ var rho = side == WireSurfaceSide.Outside ? r0 + offset : r0 - offset;
+ var a = sign * 2d * Math.PI * turns * rho * Math.Cos(startLat); var b = (endLat - startLat) * rho; var norm = Math.Sqrt(a * a + b * b);
+ var e0 = input.Up; var right = input.Right;
+ longitude = Direction3D.Create(input.Tangent.ToVector() * (a / norm) + right.ToVector() * (b / norm));
+ axis = Direction3D.Create(input.Tangent.ToVector() * (b / norm) - right.ToVector() * (a / norm));
+ latitude = axis;
+ radial = e0;
+ var radialAtStart = e0.ToVector() * Math.Cos(startLat) + axis.ToVector() * Math.Sin(startLat);
+ if (Math.Abs(phase) > 1e-15) { radial = Direction3D.Create(Rotate(radial.ToVector(), input.Tangent.ToVector(), phase)); longitude = Direction3D.Create(Rotate(longitude.ToVector(), input.Tangent.ToVector(), phase)); axis = Direction3D.Create(Rotate(axis.ToVector(), input.Tangent.ToVector(), phase)); latitude = axis; radialAtStart = radial.ToVector() * Math.Cos(startLat) + axis.ToVector() * Math.Sin(startLat); }
+ origin = input.Position - radialAtStart * rho;
+ }
+ else
+ {
+ var slope = (r1 - r0) / supportHeight; var normalScale = Math.Sqrt(1d + slope * slope); var sideSign = side == WireSurfaceSide.Outside ? 1d : -1d;
+ var effectiveR0 = r0 + sideSign * offset / normalScale; var effectiveR1 = r1 + sideSign * offset / normalScale;
+ if (effectiveR0 <= diameter / 2d || effectiveR1 <= diameter / 2d) return FailSurface("wireform-surfacecoil-offset-invalid", name, "Offset frustum/cylinder radius collapses or inverts.");
+ var c = (effectiveR1 - effectiveR0) * pitch * turns / supportHeight; var a = sign * 2d * Math.PI * turns * effectiveR0; var b = pitch * turns;
+ var nominalRadial = input.Right; var nominalAxis = input.Up; var nominalCirc = Direction3D.Create(WireFormAuthoring.Cross(nominalAxis.ToVector(), nominalRadial.ToVector()));
+ var derivative = nominalRadial.ToVector() * c + nominalCirc.ToVector() * a + nominalAxis.ToVector() * b;
+ radial = Direction3D.Create(WireCoilGeometry.RotateFromTo(nominalRadial.ToVector(), derivative, input.Tangent.ToVector()));
+ axis = Direction3D.Create(WireCoilGeometry.RotateFromTo(nominalAxis.ToVector(), derivative, input.Tangent.ToVector()));
+ longitude = Direction3D.Create(WireFormAuthoring.Cross(axis.ToVector(), radial.ToVector())); latitude = axis;
+ if (Math.Abs(phase) > 1e-15) { radial = Direction3D.Create(Rotate(radial.ToVector(), input.Tangent.ToVector(), phase)); axis = Direction3D.Create(Rotate(axis.ToVector(), input.Tangent.ToVector(), phase)); longitude = Direction3D.Create(WireFormAuthoring.Cross(axis.ToVector(), radial.ToVector())); latitude = axis; }
+ var axialShift = -sideSign * slope * offset / normalScale;
+ origin = input.Position - radial.ToVector() * effectiveR0 - axis.ToVector() * axialShift;
+ r0 = effectiveR0; r1 = effectiveR1;
+ }
+
+ var prototype = new WireSurfaceCoilAir(name, ordinal, supportName.Trim(), kind, side, clearance, offset, turns, pitch,
+ startLat, endLat, hand, phase, r0, r1, supportHeight, origin, axis, radial, longitude, latitude,
+ input, input, 0d, 0d, clearance, ApproximationTolerance);
+ var length = WireCoilGeometry.IntegrateLength(prototype); var self = WireCoilGeometry.MeasureSelfClearance(prototype, diameter);
+ var endUp = WireCoilGeometry.TransportUp(input.Up, prototype.Tangent, Math.Max(64, (int)Math.Ceiling(turns * 48d)));
+ var output = new WireState(prototype.Evaluate(1d), prototype.Tangent(1d), endUp, input.AccumulatedLengthMm + length);
+ return KernelResult<WireSurfaceCoilAir>.Success(prototype with { LengthMm = length, MinimumSelfClearanceMm = self, Output = output });
+ }
+
+ private static bool Length(string body, string name, out double value) => WireFormAuthoring.TryLength(WireFormAuthoring.Property(body, name), out value);
+ private static bool Angle(string body, string name, out double value) => WireFormAuthoring.TryAngle(WireFormAuthoring.Property(body, name), out value);
+ private static bool Number(string body, string name, out double value) => double.TryParse(WireFormAuthoring.Property(body, name), NumberStyles.Float, CultureInfo.InvariantCulture, out value) && double.IsFinite(value);
+ private static bool Hand(string body, out WireCoilHandedness hand) => Enum.TryParse(WireFormAuthoring.Property(body, "Handedness") ?? "RightHanded", false, out hand);
+ private static bool Phase(string body, out double phase) { var text = WireFormAuthoring.Property(body, "StartPhase"); if (text is null) { phase = 0d; return true; } return WireFormAuthoring.TryAngle(text, out phase); }
+ private static int MatchingBrace(string source, int open) { var depth = 0; for (var i = open; i >= 0 && i < source.Length; i++) { if (source[i] == '{') depth++; else if (source[i] == '}' && --depth == 0) return i; } return -1; }
+ private static Vector3D Rotate(Vector3D v, Vector3D a, double angle) => v * Math.Cos(angle) + WireFormAuthoring.Cross(a, v) * Math.Sin(angle) + a * (WireFormAuthoring.Dot(a, v) * (1d - Math.Cos(angle)));
+ private static KernelResult<WireAxisCoilAir> FailAxis(string code, string name, string message) => KernelResult<WireAxisCoilAir>.Failure([Diagnostic($"{code}:{name}: {message}")]);
+ private static KernelResult<WireSurfaceCoilAir> FailSurface(string code, string name, string message) => KernelResult<WireSurfaceCoilAir>.Failure([Diagnostic($"{code}:{name}: {message}")]);
+ private static Core.Diagnostics.KernelDiagnostic Diagnostic(string message) => new(Core.Diagnostics.KernelDiagnosticCode.ValidationFailed, Core.Diagnostics.KernelDiagnosticSeverity.Error, message, "FirmamentV2.WireForm.Coil");
+}
+
+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);
+ }
+ 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);
+ }
+ 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;
+ if (coil.SupportKind == "Sphere")
+ {
+ var rho = coil.Side == WireSurfaceSide.Outside ? coil.SupportRadius0Mm + coil.CenterlineOffsetMm : coil.SupportRadius0Mm - coil.CenterlineOffsetMm;
+ var lat = coil.StartLatitudeRadians + (coil.EndLatitudeRadians - coil.StartLatitudeRadians) * t;
+ var equator = Rotate(coil.StartRadial.ToVector(), coil.SupportAxis.ToVector(), theta);
+ return coil.SupportOrigin + (equator * Math.Cos(lat) + coil.SupportAxis.ToVector() * Math.Sin(lat)) * rho;
+ }
+ var r = coil.SupportRadius0Mm + (coil.SupportRadius1Mm - coil.SupportRadius0Mm) * (coil.AxialPitchMm * coil.Turns * t / coil.SupportHeightMm);
+ return coil.SupportOrigin + Rotate(coil.StartRadial.ToVector(), coil.SupportAxis.ToVector(), theta) * r + coil.SupportAxis.ToVector() * (coil.AxialPitchMm * coil.Turns * t);
+ }
+ public static Direction3D TangentSurface(WireSurfaceCoilAir coil, double t)
+ {
+ const double h = 1e-6; var a = EvaluateSurface(coil, Math.Max(0d, t - h)); var b = EvaluateSurface(coil, Math.Min(1d, t + h)); return Direction3D.Create(b - a);
+ }
+ public static double IntegrateLength(WireCoilAir coil)
+ {
+ const int n = 4096; var total = 0d; var p = coil.Evaluate(0d); for (var i = 1; i <= n; i++) { var q = coil.Evaluate((double)i / n); total += (q - p).Length; p = q; } return total;
+ }
+ public static double MeasureSelfClearance(WireCoilAir coil, double diameter)
+ {
+ var count = Math.Max(256, (int)Math.Ceiling(coil.Turns * 128d)); var points = Enumerable.Range(0, count + 1).Select(i => coil.Evaluate((double)i / count)).ToArray(); var exclusion = Math.Max(2, (int)Math.Floor(count / coil.Turns * .6d)); var best = double.PositiveInfinity;
+ for (var i = 0; i < points.Length; i++) for (var j = i + exclusion; j < points.Length; j++) best = Math.Min(best, (points[i] - points[j]).Length);
+ return best - diameter;
+ }
+ public static (double MaxMm, double RmsMm) MeasureCenterlineApproximation(WireCoilAir coil, int segments)
+ {
+ var squared = 0d; var maximum = 0d; var count = 0;
+ for (var segment = 0; segment < segments; segment++)
+ {
+ var t0 = (double)segment / segments; var t1 = (double)(segment + 1) / segments; var p0 = coil.Evaluate(t0); var p1 = coil.Evaluate(t1); var chord = (p1 - p0).Length;
+ var controls = new[] { p0, p0 + coil.Tangent(t0).ToVector() * (chord / 3d), p1 - coil.Tangent(t1).ToVector() * (chord / 3d), p1 };
+ foreach (var local in new[] { .25d, .5d, .75d }) { var inverse = 1d - local; var approximate = new Point3D(controls[0].X * inverse * inverse * inverse + 3d * controls[1].X * inverse * inverse * local + 3d * controls[2].X * inverse * local * local + controls[3].X * local * local * local, controls[0].Y * inverse * inverse * inverse + 3d * controls[1].Y * inverse * inverse * local + 3d * controls[2].Y * inverse * local * local + controls[3].Y * local * local * local, controls[0].Z * inverse * inverse * inverse + 3d * controls[1].Z * inverse * inverse * local + 3d * controls[2].Z * inverse * local * local + controls[3].Z * local * local * local); var exact = coil.Evaluate(t0 + (t1 - t0) * local); var error = (approximate - exact).Length; maximum = Math.Max(maximum, error); squared += error * error; count++; }
+ }
+ return (maximum, Math.Sqrt(squared / count));
+ }
+ public static Direction3D TransportUp(Direction3D initial, Func<double, Direction3D> tangent, int count)
+ {
+ var up = initial.ToVector(); var previous = tangent(0d).ToVector(); for (var i = 1; i <= count; i++) { var next = tangent((double)i / count).ToVector(); up = RotateFromTo(up, previous, next); up -= next * WireFormAuthoring.Dot(up, next); up = Direction3D.Create(up).ToVector(); previous = next; } return Direction3D.Create(up);
+ }
+ internal static Vector3D RotateFromTo(Vector3D value, Vector3D from, Vector3D to)
+ {
+ var f = Direction3D.Create(from).ToVector(); var t = Direction3D.Create(to).ToVector(); var dot = Math.Clamp(WireFormAuthoring.Dot(f, t), -1d, 1d); if (dot > 1d - 1e-14) return value;
+ var cross = WireFormAuthoring.Cross(f, t); if (cross.Length < 1e-12) { var seed = Math.Abs(f.X) < .8 ? new Vector3D(1, 0, 0) : new Vector3D(0, 1, 0); cross = WireFormAuthoring.Cross(f, seed); }
+ return Rotate(value, Direction3D.Create(cross).ToVector(), Math.Acos(dot));
+ }
+ internal static Vector3D Rotate(Vector3D v, Vector3D a, double angle) => v * Math.Cos(angle) + WireFormAuthoring.Cross(a, v) * Math.Sin(angle) + a * (WireFormAuthoring.Dot(a, v) * (1d - Math.Cos(angle)));
+}
+
+internal static class WireCoilBRepMaterializer
+{
+ private sealed record Station(Point3D Point, Direction3D Tangent, Direction3D Up, double StepLength);
+ internal static KernelResult<WireFormBuildResult> Build(WireFormFeatureAir feature)
+ {
+ try
+ {
+ var stations = Stations(feature); var r = feature.WireRadiusMm; var builder = new TopologyBuilder(); var geometry = new BrepGeometryStore(); var bindings = new BrepBindingModel(); var points = new Dictionary<VertexId, Point3D>(); var curves = 1; var surfaces = 1;
+ var vertices = new VertexId[stations.Count, 4]; var rings = new EdgeId[stations.Count, 4]; var ringControls = new Point3D[stations.Count, 4][];
+ for (var i = 0; i < stations.Count; i++)
+ {
+ var right = Direction3D.Create(WireFormAuthoring.Cross(stations[i].Tangent.ToVector(), stations[i].Up.ToVector()));
+ for (var q = 0; q < 4; q++)
+ {
+ var controls = Quarter(stations[i].Point, stations[i].Up, right, r, q); ringControls[i, q] = controls;
+ vertices[i, q] = builder.AddVertex(); points[vertices[i, q]] = controls[0];
+ }
+ for (var q = 0; q < 4; q++)
+ {
+ rings[i, q] = builder.AddEdge(vertices[i, q], vertices[i, (q + 1) % 4]); var spline = Bezier(ringControls[i, q]); geometry.AddCurve(new(curves), CurveGeometry.FromBSpline(spline)); bindings.AddEdgeBinding(new(rings[i, q], new(curves++), new ParameterInterval(0, 1)));
+ }
+ }
+ var faces = new List<FaceId>();
+ for (var i = 0; i + 1 < stations.Count; i++)
+ {
+ var c0 = CenterBezier(stations[i], stations[i + 1]); var net = new Point3D[4][];
+ var nets = new Point3D[4][][];
+ for (var q = 0; q < 4; q++) { net = new Point3D[4][]; for (var u = 0; u < 4; u++) { var alpha = u / 3d; var up = Direction3D.Create(stations[i].Up.ToVector() * (1d - alpha) + stations[i + 1].Up.ToVector() * alpha); var tangent = Direction3D.Create(stations[i].Tangent.ToVector() * (1d - alpha) + stations[i + 1].Tangent.ToVector() * alpha); up = Direction3D.Create(up.ToVector() - tangent.ToVector() * WireFormAuthoring.Dot(up.ToVector(), tangent.ToVector())); var right = Direction3D.Create(WireFormAuthoring.Cross(tangent.ToVector(), up.ToVector())); net[u] = Quarter(c0[u], up, right, r, q); } nets[q] = net; }
+ var longitudinal = new EdgeId[4];
+ for (var q = 0; q < 4; q++) { longitudinal[q] = builder.AddEdge(vertices[i, q], vertices[i + 1, q]); var spline = Bezier(nets[q].Select(row => row[0]).ToArray()); geometry.AddCurve(new(curves), CurveGeometry.FromBSpline(spline)); bindings.AddEdgeBinding(new(longitudinal[q], new(curves++), new ParameterInterval(0, 1))); }
+ for (var q = 0; q < 4; q++) { var surface = new BSplineSurfaceWithKnots(3, 3, nets[q], "UNSPECIFIED", false, false, false, [4, 4], [4, 4], [0d, 1d], [0d, 1d], "UNSPECIFIED"); geometry.AddSurface(new(surfaces), SurfaceGeometry.FromBSplineSurfaceWithKnots(surface)); var face = AddFace(builder, [(longitudinal[q], false), (rings[i + 1, q], false), (longitudinal[(q + 1) % 4], true), (rings[i, q], true)]); bindings.AddFaceBinding(new(face, new(surfaces++))); faces.Add(face); }
+ }
+ var startPlane = new PlaneSurface(stations[0].Point, Direction3D.Create(stations[0].Tangent.ToVector() * -1d), stations[0].Up); var endPlane = new PlaneSurface(stations[^1].Point, stations[^1].Tangent, stations[^1].Up);
+ var start = AddFace(builder, Enumerable.Range(0, 4).Select(q => (rings[0, 3 - q], true)).ToArray()); geometry.AddSurface(new(surfaces), SurfaceGeometry.FromPlane(startPlane)); bindings.AddFaceBinding(new(start, new(surfaces++))); faces.Add(start);
+ var end = AddFace(builder, Enumerable.Range(0, 4).Select(q => (rings[stations.Count - 1, q], false)).ToArray()); geometry.AddSurface(new(surfaces), SurfaceGeometry.FromPlane(endPlane)); bindings.AddFaceBinding(new(end, new(surfaces++))); faces.Add(end);
+ 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<WireFormBuildResult>.Failure(validation.Diagnostics);
+ var samples = stations.Select(x => x.Point).ToArray(); var bounds = new[] { samples.Min(p => p.X) - r, samples.Min(p => p.Y) - r, samples.Min(p => p.Z) - r, samples.Max(p => p.X) + r, samples.Max(p => p.Y) + r, samples.Max(p => p.Z) + r };
+ var volume = Math.PI * r * r * feature.TotalWireLengthMm; var mass = volume * 1e-9 * feature.Material.Structural!.Density.SiValue;
+ return KernelResult<WireFormBuildResult>.Success(new(feature, body, volume, mass, bounds, ["wireform-coil-evaluable-centerline-authority", "wireform-coil-parallel-transport", "wireform-coil-non-rational-bspline-sweep", "wireform-coil-deterministic-approximation"]));
+ }
+ catch (Exception ex) when (ex is ArgumentException or InvalidOperationException) { return KernelResult<WireFormBuildResult>.Failure([new(Core.Diagnostics.KernelDiagnosticCode.ValidationFailed, Core.Diagnostics.KernelDiagnosticSeverity.Error, "wireform-coil-brep-construction-failed: " + ex.Message, "FirmamentV2.WireForm.Coil")]); }
+ }
+ private static List<Station> Stations(WireFormFeatureAir feature)
+ {
+ var raw = new List<(Point3D P, Direction3D T, double Ds)>();
+ foreach (var op in feature.Operations)
+ {
+ var n = op switch { WireStraightAir => 1, WireBendAir b => Math.Max(1, (int)Math.Ceiling(Math.Abs(b.AngleRadians) / (Math.PI / 16d))), WireCoilAir c => Math.Max(16, (int)Math.Ceiling(c.Turns * 32d)), _ => 1 };
+ for (var i = raw.Count == 0 ? 0 : 1; i <= n; i++) { var t = (double)i / n; var p = op switch { WireStraightAir s => s.Input.Position + (s.Output.Position - s.Input.Position) * t, WireBendAir b => b.Center + WireCoilGeometry.Rotate(b.StartRadial.ToVector(), b.PlaneNormal.ToVector(), Math.Abs(b.AngleRadians) * t) * b.RadiusMm, WireCoilAir c => c.Evaluate(t), _ => op.Input.Position }; var tangent = op switch { WireStraightAir s => s.Input.Tangent, WireBendAir b => Direction3D.Create(WireCoilGeometry.Rotate(b.Input.Tangent.ToVector(), b.PlaneNormal.ToVector(), Math.Abs(b.AngleRadians) * t)), WireCoilAir c => c.Tangent(t), _ => op.Input.Tangent }; raw.Add((p, tangent, op.LengthMm / n)); }
+ }
+ var result = new List<Station>(); var up = feature.StartState.Up; Direction3D? previous = null; foreach (var item in raw) { if (previous is { } prior) up = Direction3D.Create(WireCoilGeometry.RotateFromTo(up.ToVector(), prior.ToVector(), item.T.ToVector())); up = Direction3D.Create(up.ToVector() - item.T.ToVector() * WireFormAuthoring.Dot(up.ToVector(), item.T.ToVector())); result.Add(new(item.P, item.T, up, item.Ds)); previous = item.T; } return result;
+ }
+ private static Point3D[] CenterBezier(Station a, Station b) { var ds = (b.Point - a.Point).Length; return [a.Point, a.Point + a.Tangent.ToVector() * (ds / 3d), b.Point - b.Tangent.ToVector() * (ds / 3d), b.Point]; }
+ private static Point3D[] Quarter(Point3D center, Direction3D up, Direction3D right, double radius, int quarter) { var a = quarter * Math.PI / 2d; var b = a + Math.PI / 2d; const double k = .5522847498307936; Vector3D E(double x) => up.ToVector() * Math.Cos(x) + right.ToVector() * Math.Sin(x); Vector3D D(double x) => up.ToVector() * -Math.Sin(x) + right.ToVector() * Math.Cos(x); return [center + E(a) * radius, center + (E(a) + D(a) * k) * radius, center + (E(b) - D(b) * k) * radius, center + E(b) * radius]; }
+ private static BSpline3Curve Bezier(IReadOnlyList<Point3D> controls) => new(3, controls, [4, 4], [0d, 1d], "UNSPECIFIED", false, false, "UNSPECIFIED");
+ private static FaceId AddFace(TopologyBuilder builder, IReadOnlyList<(EdgeId Edge, bool Reversed)> uses) { var loop = builder.AllocateLoopId(); var ids = uses.Select(_ => builder.AllocateCoedgeId()).ToArray(); for (var i = 0; i < uses.Count; i++) builder.AddCoedge(new(ids[i], uses[i].Edge, loop, ids[(i + 1) % ids.Length], ids[(i + ids.Length - 1) % ids.Length], uses[i].Reversed)); builder.AddLoop(new Loop(loop, ids)); return builder.AddFace([loop]); }
+}
diff --git a/Aetheris.Kernel.Firmament/Materializer/WireForm.cs b/Aetheris.Kernel.Firmament/Materializer/WireForm.cs
index 803421bd..aeb35b9f 100644
--- a/Aetheris.Kernel.Firmament/Materializer/WireForm.cs
+++ b/Aetheris.Kernel.Firmament/Materializer/WireForm.cs
@@ -30,6 +30,53 @@ public sealed record WireBendAir(string Name, int Ordinal, double RadiusMm, doub
Direction3D PlaneNormal, Point3D Center, Direction3D StartRadial, WireState Input, WireState Output)
: WireFormOperationAir(Name, Ordinal, Input, Output, RadiusMm * Math.Abs(AngleRadians));
+public enum WireCoilHandedness { RightHanded, LeftHanded }
+public enum WireSurfaceSide { Outside, Inside }
+
+/// <summary>An evaluable winding law retained as semantic authority; samples are never authoring input.</summary>
+public abstract record WireCoilAir(string Name, int Ordinal, double Turns, WireCoilHandedness Handedness,
+ double StartPhaseRadians, WireState Input, WireState Output, double LengthMm, double MinimumSelfClearanceMm,
+ double ApproximationToleranceMm) : WireFormOperationAir(Name, Ordinal, Input, Output, LengthMm)
+{
+ public abstract Point3D Evaluate(double parameter);
+ public abstract Direction3D Tangent(double parameter);
+ public abstract string CoilKind { get; }
+ public abstract string ProgressionLaw { get; }
+ public virtual double? SupportClearanceMm => null;
+ public int ApproximationSegmentCount => Math.Max(16, (int)Math.Ceiling(Turns * 32d));
+ public (double MaxMm, double RmsMm) ApproximationError => WireCoilGeometry.MeasureCenterlineApproximation(this, ApproximationSegmentCount);
+}
+
+public sealed record WireAxisCoilAir(string Name, int Ordinal, double RadiusMm, double Turns, double PitchMm,
+ double HeightMm, WireCoilHandedness Handedness, double StartPhaseRadians, Point3D AxisOrigin,
+ Direction3D Axis, Direction3D StartRadial, WireState Input, WireState Output, double LengthMm,
+ double MinimumSelfClearanceMm, double ApproximationToleranceMm)
+ : WireCoilAir(Name, Ordinal, Turns, Handedness, StartPhaseRadians, Input, Output, LengthMm,
+ MinimumSelfClearanceMm, ApproximationToleranceMm)
+{
+ public override string CoilKind => "AxisCoil";
+ public override string ProgressionLaw => "AxialPitch";
+ public override Point3D Evaluate(double t) => WireCoilGeometry.EvaluateAxis(this, t);
+ public override Direction3D Tangent(double t) => WireCoilGeometry.TangentAxis(this, t);
+}
+
+public sealed record WireSurfaceCoilAir(string Name, int Ordinal, string SupportName, string SupportKind,
+ WireSurfaceSide Side, double ClearanceMm, double CenterlineOffsetMm, double Turns, double AxialPitchMm,
+ double StartLatitudeRadians, double EndLatitudeRadians, WireCoilHandedness Handedness,
+ double StartPhaseRadians, double SupportRadius0Mm, double SupportRadius1Mm, double SupportHeightMm,
+ Point3D SupportOrigin, Direction3D SupportAxis, Direction3D StartRadial, Direction3D LongitudeDirection,
+ Direction3D LatitudeDirection, WireState Input, WireState Output, double LengthMm,
+ double MinimumSelfClearanceMm, double MeasuredSupportClearanceMm, double ApproximationToleranceMm)
+ : WireCoilAir(Name, Ordinal, Turns, Handedness, StartPhaseRadians, Input, Output, LengthMm,
+ MinimumSelfClearanceMm, ApproximationToleranceMm)
+{
+ public override string CoilKind => $"SurfaceCoil.{SupportKind}";
+ public override string ProgressionLaw => SupportKind == "Sphere" ? "LatitudeProgression" : "AxialPitch";
+ public override double? SupportClearanceMm => MeasuredSupportClearanceMm;
+ public override Point3D Evaluate(double t) => WireCoilGeometry.EvaluateSurface(this, t);
+ public override Direction3D Tangent(double t) => WireCoilGeometry.TangentSurface(this, t);
+}
+
/// <summary>WireForm semantic AIR. Bend radii are centerline radii.</summary>
public sealed record WireFormFeatureAir(string Name, double DiameterMm, string MaterialReference, ResolvedMaterial Material,
WireState StartState, IReadOnlyList<WireFormOperationAir> Operations, string FrameTransportPolicy)
@@ -37,6 +84,7 @@ public sealed record WireFormFeatureAir(string Name, double DiameterMm, string M
public double WireRadiusMm => DiameterMm / 2d;
public double TotalStraightLengthMm => Operations.OfType<WireStraightAir>().Sum(x => x.LengthMm);
public double TotalBendLengthMm => Operations.OfType<WireBendAir>().Sum(x => x.LengthMm);
+ public double TotalCoilLengthMm => Operations.OfType<WireCoilAir>().Sum(x => x.LengthMm);
public double TotalWireLengthMm => Operations.Sum(x => x.LengthMm);
public WireState EndState => Operations.Count == 0 ? StartState : Operations[^1].Output;
}
@@ -49,7 +97,7 @@ public static class WireFormAuthoring
{
public const string FrameTransportPolicy = "The authored local Up/Right bend-plane axis is rotated with the tangent through each bend (rotation-minimal rigid transport about the bend normal); Straight preserves the frame.";
private static readonly Regex Declaration = new(@"\bWireForm\s+(?<name>[A-Za-z_]\w*)\s*\{", RegexOptions.CultureInvariant);
- private static readonly Regex Operation = new(@"\b(?<kind>Straight|Bend)\s+(?<name>[A-Za-z_]\w*)\s*\{", RegexOptions.CultureInvariant);
+ private static readonly Regex Operation = new(@"\b(?<kind>Straight|Bend|AxisCoil|SurfaceCoil|Coil)\s+(?<name>[A-Za-z_]\w*)\s*\{", RegexOptions.CultureInvariant);
public static bool IsWireFormSource(string source) => Declaration.IsMatch(source);
@@ -101,6 +149,19 @@ public static class WireFormAuthoring
continue;
}
+ if (match.Groups["kind"].Value is "AxisCoil" or "Coil")
+ {
+ var coil = WireCoilAuthoring.CreateAxis(operationName, ordinal, operationBody, state, diameter);
+ if (!coil.IsSuccess) return KernelResult<WireFormFeatureAir>.Failure(coil.Diagnostics);
+ operations.Add(coil.Value); state = coil.Value.Output; continue;
+ }
+ if (match.Groups["kind"].Value == "SurfaceCoil")
+ {
+ var coil = WireCoilAuthoring.CreateSurface(source, operationName, ordinal, operationBody, state, diameter);
+ if (!coil.IsSuccess) return KernelResult<WireFormFeatureAir>.Failure(coil.Diagnostics);
+ operations.Add(coil.Value); state = coil.Value.Output; continue;
+ }
+
if (!TryLength(Property(operationBody, "Radius"), out var radius) || radius <= 0d)
return Fail("wireform-bend-radius-invalid", $"{operationName}: centerline Radius must be finite and greater than zero.");
if (radius <= diameter / 2d + ToleranceContext.Default.Linear)
@@ -123,22 +184,22 @@ public static class WireFormAuthoring
operations.Add(new WireBendAir(operationName, ordinal, radius, angle, plane, axis, center, startRadial, state, bendOutput));
state = bendOutput;
}
- if (operations.Count == 0) return Fail("wireform-operations-empty", $"WireForm '{name}' requires at least one Straight or Bend operation.");
+ if (operations.Count == 0) return Fail("wireform-operations-empty", $"WireForm '{name}' requires at least one Straight, Bend, AxisCoil, or SurfaceCoil operation.");
return KernelResult<WireFormFeatureAir>.Success(new(name, diameter, materialReference, material.Material,
new WireState(new(origin.X, origin.Y, origin.Z), tangent, up, 0d), operations, FrameTransportPolicy));
}
- private static string? Property(string body, string name)
+ internal static string? Property(string body, string name)
{
var match = Regex.Match(body, $@"\b{Regex.Escape(name)}\s*:\s*(?<value>\[[^\]]+\]|[^;\r\n}}]+)", RegexOptions.CultureInvariant);
return match.Success ? match.Groups["value"].Value.Trim() : null;
}
- private static bool TryLength(string? text, out double value)
+ internal static bool TryLength(string? text, out double value)
{
value = default;
return text is not null && new BoundedMeasureExpression(text, "mm").TryEvaluate(out value);
}
- private static bool TryAngle(string? text, out double value)
+ internal static bool TryAngle(string? text, out double value)
{
value = default;
if (!TryUnit(text, "deg", out var degrees)) return false;
@@ -198,6 +259,8 @@ public static class WireFormBRepMaterializer
{
var diagnostics = Validate(feature);
if (diagnostics.Count > 0) return KernelResult<WireFormBuildResult>.Failure(diagnostics.Select(Error).ToArray());
+ if (feature.Operations.Any(operation => operation is WireCoilAir))
+ return WireCoilBRepMaterializer.Build(feature);
try
{
var count = feature.Operations.Count;
@@ -271,6 +334,10 @@ public static class WireFormBRepMaterializer
if (operation.LengthMm <= Tolerance.Linear) diagnostics.Add($"wireform-operation-degenerate:{operation.Name}");
if (operation is WireBendAir bend && bend.RadiusMm <= feature.WireRadiusMm + Tolerance.Linear)
diagnostics.Add($"wireform-bend-radius-invalid:{bend.Name}: centerline radius must exceed wire radius.");
+ if (operation is WireCoilAir coil && coil.MinimumSelfClearanceMm + Tolerance.Linear < 0d)
+ diagnostics.Add($"wireform-coil-turn-clearance:{coil.Name}: adjacent turns overlap by {-coil.MinimumSelfClearanceMm:G6} mm.");
+ if (operation is WireCoilAir approximated && approximated.ApproximationError.MaxMm > approximated.ApproximationToleranceMm)
+ diagnostics.Add($"wireform-coil-approximation-tolerance:{approximated.Name}: measured centerline error {approximated.ApproximationError.MaxMm:G6} mm exceeds {approximated.ApproximationToleranceMm:G6} mm.");
}
var clearance = feature.DiameterMm;
for (var i = 0; i + 1 < feature.Operations.Count; i++)
@@ -315,10 +382,11 @@ public static class WireFormBRepMaterializer
}
private static double Sagitta(WireFormOperationAir operation, int count) => operation is WireBendAir bend
? bend.RadiusMm * (1d - Math.Cos(Math.Abs(bend.AngleRadians) / (2d * count))) : 0d;
- private static IReadOnlyList<Point3D> Sample(WireFormOperationAir operation, int count) => operation switch
+ internal static IReadOnlyList<Point3D> Sample(WireFormOperationAir operation, int count) => operation switch
{
WireStraightAir line => [line.Input.Position, line.Output.Position],
WireBendAir bend => Enumerable.Range(0, count + 1).Select(i => bend.Center + Rotate(bend.StartRadial.ToVector(), bend.PlaneNormal.ToVector(), Math.Abs(bend.AngleRadians) * i / count) * bend.RadiusMm).ToArray(),
+ WireCoilAir coil => Enumerable.Range(0, count + 1).Select(i => coil.Evaluate((double)i / count)).ToArray(),
_ => []
};
private static double SegmentDistance(Point3D p1, Point3D q1, Point3D p2, Point3D q2)
@@ -342,12 +410,26 @@ public static class WireFormReportFactory
var feature = built.Feature;
var surfaces = built.Body.Topology.Faces.Select(face => built.Body.GetFaceSurface(face.Id).Kind).ToArray();
var operations = feature.Operations.Select(operation => new FirmamentWireOperationReport(
- operation.Ordinal, operation.Name, operation is WireStraightAir ? "Straight" : "Bend", operation.LengthMm,
+ operation.Ordinal, operation.Name, operation switch { WireStraightAir => "Straight", WireBendAir => "Bend", WireAxisCoilAir => "AxisCoil", WireSurfaceCoilAir => "SurfaceCoil", _ => "Unknown" }, operation.LengthMm,
operation is WireBendAir bend ? bend.RadiusMm : null,
operation is WireBendAir bendAngle ? bendAngle.AngleRadians * 180d / Math.PI : null,
operation is WireBendAir bendPlane ? bendPlane.Plane : null, operation.StableId(feature.Name),
- State(operation.Input), State(operation.Output), operation is WireStraightAir ? "LineSegment" : "CircularArc",
- operation is WireStraightAir ? "Cylinder" : "Torus")).ToArray();
+ State(operation.Input), State(operation.Output), operation switch { WireStraightAir => "LineSegment", WireBendAir => "CircularArc", WireCoilAir => "EvaluableWindingLaw", _ => "Unknown" },
+ operation switch { WireStraightAir => "Cylinder", WireBendAir => "Torus", WireCoilAir => "NonRationalBSplineTube", _ => "Unknown" },
+ operation is WireCoilAir coil ? coil.CoilKind : null, operation is WireCoilAir turns ? turns.Turns : null,
+ operation is WireCoilAir handed ? handed.Handedness.ToString() : null,
+ operation switch { WireAxisCoilAir axis => axis.PitchMm, WireSurfaceCoilAir surface => surface.AxialPitchMm, _ => null },
+ operation is WireAxisCoilAir height ? height.HeightMm : null,
+ operation is WireCoilAir phase ? phase.StartPhaseRadians * 180d / Math.PI : null,
+ operation is WireSurfaceCoilAir support ? support.SupportName : null,
+ operation is WireSurfaceCoilAir side ? side.Side.ToString() : null,
+ operation is WireCoilAir progression ? progression.ProgressionLaw : null,
+ operation is WireCoilAir self ? self.MinimumSelfClearanceMm : null,
+ operation is WireCoilAir supportClearance ? supportClearance.SupportClearanceMm : null,
+ operation is WireCoilAir approximation ? approximation.ApproximationToleranceMm : null,
+ operation is WireCoilAir segmentCount ? segmentCount.ApproximationSegmentCount : null,
+ operation is WireCoilAir maximumError ? maximumError.ApproximationError.MaxMm : null,
+ operation is WireCoilAir rmsError ? rmsError.ApproximationError.RmsMm : null)).ToArray();
return new(feature.Name, feature.DiameterMm, feature.Material.Identity.FirmamentPath, feature.Operations.Count,
feature.Operations.Count(x => x is WireStraightAir), feature.Operations.Count(x => x is WireBendAir),
feature.TotalStraightLengthMm, feature.TotalBendLengthMm, feature.TotalWireLengthMm, built.VolumeMm3, built.MassKilograms,
@@ -358,7 +440,11 @@ public static class WireFormReportFactory
feature.FrameTransportPolicy, operations, built.Bounds,
surfaces.Count(x => x == SurfaceGeometryKind.Cylinder), surfaces.Count(x => x == SurfaceGeometryKind.Torus),
surfaces.Count(x => x == SurfaceGeometryKind.Plane), surfaces.Count(x => x is not (SurfaceGeometryKind.Cylinder or SurfaceGeometryKind.Torus or SurfaceGeometryKind.Plane)),
- surfaces.Count(x => x == SurfaceGeometryKind.BSplineSurfaceWithKnots), 0, true, stepSha256, true, reimportedManifold);
+ 0, 0, true, stepSha256, true, reimportedManifold,
+ feature.Operations.Count(x => x is WireCoilAir), feature.TotalCoilLengthMm,
+ feature.Operations.OfType<WireCoilAir>().Select(x => (double?)x.MinimumSelfClearanceMm).DefaultIfEmpty(null).Min(),
+ surfaces.Count(x => x == SurfaceGeometryKind.BSplineSurfaceWithKnots), feature.Operations.Any(x => x is WireCoilAir) ? 3 : 0,
+ feature.Operations.Any(x => x is WireCoilAir) ? "ExactEvaluableWindingLaw->DeterministicCubicNonRationalBSplineTube" : "ExactAnalyticLineArcSweep");
}
private static FirmamentWireStateReport State(WireState state) => new(V(state.Position), V(state.Tangent), V(state.Up), V(state.Right), state.AccumulatedLengthMm);
diff --git a/docs/public/firmament/wire-form.md b/docs/public/firmament/wire-form.md
index 8d2584fa..7fba05fe 100644
--- a/docs/public/firmament/wire-form.md
+++ b/docs/public/firmament/wire-form.md
@@ -29,8 +29,38 @@ Circular area times total length gives volume; density from the Material DB give
The centerline lowers to explicit line and circular-arc AIR, then to exact circular Sweep geometry. Straights become cylinders, bends become toroidal patches, and open terminals become planar caps. Canonical WireForms have no rational B-spline surfaces and no faceted fallback. Both terminals retain position, tangent/frame, and section diameter.
-X0 supports one continuous, unbranched, open wire with constant circular section. Nonadjacent contact or overlap fails closed. Coils, springs, helices, arbitrary splines, mathematical or physical knots, branching, variable section, deliberate contact, and closed-wire authoring are deferred. Direct `Concept Path` plus `Sweep` remains the lower-level choice for explicitly authored trajectories.
+WIRE-X1 adds semantic winding generators without weakening the exact Straight/Bend route. `AxisCoil` authors a cylindrical helix from `Radius`, `Turns`, either `Pitch` or `Height`, explicit `Handedness`, and an optional stable `StartPhase`. If both Pitch and Height are supplied they must agree with `Height = Turns × Pitch`. The compiler derives the missing value, exact helix length, terminal position/tangent/transported frame, turn clearance, volume, and mass.
-See the canonical [90-degree bend](../../../fixtures/Canonical/WireForm/single-bend-90.firmament), [U-wire](../../../fixtures/Canonical/WireForm/u-wire.firmament), [two-plane 3D wire](../../../fixtures/Canonical/WireForm/three-dimensional-bends.firmament), and [Paperclip](../../../fixtures/Canonical/WireForm/paperclip.firmament).
+```firmament
+AxisCoil Winding {
+ Radius: 12mm
+ Turns: 8
+ Pitch: 5mm
+ Handedness: RightHanded
+ StartPhase: 0deg
+}
+```
+
+`SurfaceCoil` generates a wire centerline by winding around a known support surface while maintaining a requested side and clearance. The author specifies winding intent; Aetheris derives the changing 3D path. X1 admits authored analytic `Cylinder`, `Frustum`/`Cone`, and `Sphere` supports. Cylinder/frustum winding uses `AxialPitch`. Sphere winding uses honest linear-latitude progression between `StartLatitude` and `EndLatitude`; it does not claim equal geodesic spacing and excludes the exact poles.
+
+```firmament
+Frustum CupInnerFrustum { BottomRadius: 18mm; TopRadius: 30mm; Height: 60mm }
+SurfaceCoil Winding {
+ Surface: CupInnerFrustum
+ Side: Inside
+ Clearance: 1mm
+ Turns: 6
+ AxialPitch: 8mm
+ Handedness: RightHanded
+}
+```
+
+`Clearance` is support-to-wire clearance; the compiler uses `Diameter / 2 + Clearance` as centerline offset. `CenterlineOffset` is the mutually exclusive mathematical alternative. Collapsing inward offsets, pole singularities, turn overlap, and unsupported surfaces fail with typed diagnostics. CLI inspection reports the winding kind/law, handedness, resolved pitch/height, exact or deterministically integrated stock length, start/end terminals, self/support clearance, and polynomial realization evidence.
+
+The semantic/evaluable winding law remains authoritative. Coil-containing forms lower through deterministic rotation-minimal frame transport to cubic non-rational B-spline tube patches and planar caps; STEP uses no rational product surfaces and no faceted fallback. Coil-free forms still use exact cylinders and tori. The current approximation uses 32 longitudinal cubic spans per turn and four cubic polynomial quarter patches around the circular section; the compiler measures maximum/RMS centerline error against the winding law and fails if its 0.01 mm bound is exceeded.
+
+X1 supports one continuous, unbranched, open wire with constant circular section. It does not support arbitrary/freeform supports, variable pitch or section, intentional turn contact, spring mechanics, contact dynamics, knots, branching, or closed-wire authoring. Surface support identity is authored rather than imported-face-ID based. Direct `Concept Path` plus `Sweep` remains the lower-level choice for explicitly authored line/arc trajectories.
+
+See the canonical [axis coil](../../../fixtures/Canonical/WireForm/axis-coil.firmament), [frustum SurfaceCoil](../../../fixtures/Canonical/WireForm/frustum-surface-coil.firmament), [sphere SurfaceCoil](../../../fixtures/Canonical/WireForm/sphere-surface-coil.firmament), [composed Straight/Coil/Straight](../../../fixtures/Canonical/WireForm/straight-coil-straight.firmament), [90-degree bend](../../../fixtures/Canonical/WireForm/single-bend-90.firmament), and [Paperclip](../../../fixtures/Canonical/WireForm/paperclip.firmament).
`aetheris inspect source.firmament --json` reports the semantic `wireForm` object, including `operations`, `totalStraightLength`, `totalBendLength`, and compiler-derived `totalWireLength`. A materializing `build --json` adds volume, mass, surface inventory, manifold/reimport status, rational/faceted counts, and the STEP hash.
diff --git a/docs/public/reference/supported-features.md b/docs/public/reference/supported-features.md
index e936a239..f343a167 100644
--- a/docs/public/reference/supported-features.md
+++ b/docs/public/reference/supported-features.md
@@ -10,6 +10,7 @@
| Virtual Sculpture | Bounded (ART-X0) | The explicit `Mode: Virtual` Sol 1 flagship: deterministic golden-angle/Fibonacci 3D lattice, analytic toroidal frame and eye, exact closed-body AP242 assembly, evidence/preview output, and zero rational product surfaces. This is not manufacturing geometry and does not extend Firmament engineering domains. See [Virtual Sculpture](../virtual-sculpture.md). |
| Firmament V2 analytic primitives | Bounded | Direct named Sphere, Cone (including zero-radius pointed end), and Torus routes round-trip through AP242; legacy `solid` declarations remain compatibility inputs, not canonical authoring |
| Circular Sweep | Bounded (X0) | Open planar XY Concept Path, tangent line/arc segments, constant circular diameter, analytic cylinder/torus faces, capped solid; no general 3D/variable/rail/twist sweep |
+| Wire coils | Bounded (WIRE-X1) | Semantic AxisCoil plus Cylinder/Frustum/Sphere SurfaceCoil, explicit handedness/clearance, constant circular wire, evaluable winding authority, deterministic cubic non-rational STEP tube; no variable pitch/section, arbitrary support, intentional contact, dynamics, or knots |
| Formed Wire | Bounded (WIRE-X0) | One open, continuous, unbranched constant circular wire; explicit 3D StartFrame; ordered Straight and signed planar Bend operations through ±180° in current local Up/Right planes; exact line/arc centerline, ideal cut length/volume/mass, analytic cylinders/tori/caps, terminals, and fail-closed no-contact validation. No coils, knots, branches, variable section, springback, or intentional contact. See [guide](../firmament/wire-form.md). |
| SectionChain ruled loft substrate | Bounded (SURF-X3b subset) | Firmament authoring lowers into ordered framed, same-topology semantic SectionChain IR; one-to-one ruled transitions; shared edges; Cap/Open; strict pcurves; deterministic intersection checks; persistent typed BodyState Add/Remove through documented planar housing lanes; no generic CSG authoring, rational product surface, or faceted fallback. See [Section chains](../firmament/section-chains.md). |
| Structural / weldment | Bounded (X2) | Explicit 3D nodes and straight paths; identifiable members; square/rectangular/round tube, angle, flat/round bar; orientation; catalog material; two-member butt and polygonal miter joints; semantic fillet welds; AP242 member assembly and deterministic JSON Cut List. No coping, curved routing, multi-member miter, connection design, weld analysis, or structural FEA. See [guide](../firmament/structural.md). |
diff --git a/docs/release/WIRE-X1-COIL-SURFACECOIL.md b/docs/release/WIRE-X1-COIL-SURFACECOIL.md
new file mode 100644
index 00000000..b5919d4f
--- /dev/null
+++ b/docs/release/WIRE-X1-COIL-SURFACECOIL.md
@@ -0,0 +1,35 @@
+# WIRE-X1 — Coil / SurfaceCoil foundation
+
+## Executive verdict
+
+**Meaningful progression.** Aetheris now authors `AxisCoil` and authored-support `SurfaceCoil` operations, retains exact/evaluable winding laws in WireForm AIR, derives terminals and stock accounting, rejects invalid offsets/poles/turn overlap, and exports deterministic enclosed non-rational cubic B-spline STEP tubes that reimport as manifolds. Cylinder, frustum, and bounded sphere winding are working through the real CLI path. The remaining acceptance blocker is the flagship assembly evidence: the Blender-ball source contains semantic frustum and sphere references, but the current ordinary WireForm exporter selects the coil body only. It does not yet emit those two reference bodies in the same AP242 product structure or report measured coil-to-ball distance. The artifact is therefore an honest coil witness, not yet the requested three-body qualification assembly.
+
+## Architecture and audit
+
+```text
+WireForm
+ → Straight / Bend / AxisCoil / SurfaceCoil semantic operation
+ → exact line/arc or exact/evaluable winding law
+ → Centerline AIR authority
+ → deterministic bounded cubic non-rational approximation (coil only)
+ → rotation-minimal circular-section transport
+ → analytic cylinder/torus or polynomial B-spline tube
+ → enclosed BRep / AP242 STEP
+```
+
+The generalized abstraction is `WireFormOperationAir` plus an evaluable `WireCoilAir`. `WireStraightAir` and `WireBendAir` remain special state transitions and retain exact cylinder/torus realization whenever no coil is present. Generated winding laws feed a new circular tube realization; samples are validation/materialization evidence rather than semantic authority. Existing analytic Cylinder, Cone/Frustum, and Sphere declarations provide stable authored support identities. Existing B-spline curve/surface evaluators and STEP support are reused. Lines/arcs and support descriptions remain exact/analytic; a product STEP helix and its swept tube become bounded degree-3 non-rational polynomial patches.
+
+## Semantic and qualification evidence
+
+- Axis flagship: 2 mm wire, radius 12 mm, pitch 5 mm, 8 turns, height 40 mm, right-handed. Exact centerline length is 604.510625748 mm; ideal volume is 1899.12614087 mm³; stainless mass is 0.0150030965 kg; minimum turn clearance is 3 mm.
+- Frustum flagship: authored 18/30 mm radii × 60 mm support, Inside, 1 mm requested/measured analytic support clearance, six turns at 8 mm axial pitch. Derived path length is 787.154196452 mm and sampled conservative turn clearance evidence is 6.136653 mm.
+- Sphere flagship: authored 24 mm sphere, Outside, 1 mm clearance, six turns, +55° to −55°. Progression is linear in latitude, not equal-geodesic; exact poles are rejected. Derived path length is 837.952465425 mm and measured turn clearance is 6.265152 mm.
+- Blender-ball source: authored 20/34 × 64 mm cup reference plus a seven-turn spherical winding around the 9 mm captive-ball proxy, with 1 mm outside clearance and a +65° to −65° latitude-linear span. Coil path length is 387.357156248 mm and turn clearance is 1.534378 mm. The support references remain semantic declarations in the source but are not yet included as separate bodies in the emitted single-body STEP.
+
+Coil STEP inventory is planar terminal caps plus degree-3 non-rational B-spline surfaces/curves, with zero rational product surfaces and zero faceted fallback. All four coil bodies reimport as enclosed manifolds. The deterministic realization uses 32 longitudinal cubic spans per turn and four cubic polynomial quarter-section patches. Measured maximum/RMS centerline errors are 0.000365/0.000308 mm (Axis), 0.001688/0.001162 mm (frustum), 0.005180/0.002762 mm (sphere), and 0.002449/0.001337 mm (spherical Blender coil), all below the 0.01 mm acceptance tolerance. Identical Axis builds have matching SHA-256 `35974623f6da79fbf1956de1bbae35da4f562cc5c0272c7d19651da6681bd5cb`.
+
+## Validation and regressions
+
+Focused coverage includes Turns/Pitch/Height resolution, handedness, analytic helix length, terminal state composition, cylinder/AxisCoil equivalence, frustum and sphere support laws, pole/offset/support diagnostics, turn overlap, non-rational topology, structured CLI inspection, STEP reimport, deterministic exports, and the complete WIRE-X0 WireForm test class. Coil-free Paperclip remains on the original exact path: 4 cylinders, 3 tori, 2 caps, and 0 B-splines. The warning-free Release solution build passed, as did the full serial repository suite (3,225 tests; no failures or skips; the intentionally empty FrictionLab test assembly still has no discoverable tests), fixture/layout/Markdown coverage within that suite, wireframe rendering for iso/front views, and `git diff --check`.
+
+Generated manual artifacts live under ignored `artifacts/local/`: the requested Axis, frustum, sphere, and Blender-ball coil STEP files plus iso/front wireframe SVGs. No spring stiffness, dynamics, mixing performance, or contact mechanics are claimed.
diff --git a/fixtures/Canonical/WireForm/axis-coil.firmament b/fixtures/Canonical/WireForm/axis-coil.firmament
new file mode 100644
index 00000000..727caeaf
--- /dev/null
+++ b/fixtures/Canonical/WireForm/axis-coil.firmament
@@ -0,0 +1,15 @@
+Model AxisCoilWitness {
+ Units: mm
+ WireForm AxisSpring {
+ Diameter: 2mm
+ Material: Standard.Materials.StainlessSteel.304_Annealed
+ StartFrame { Origin: [0mm,0mm,0mm]; Tangent: [1,0,0]; Up: [0,0,1] }
+ AxisCoil Winding {
+ Radius: 12mm
+ Turns: 8
+ Pitch: 5mm
+ Handedness: RightHanded
+ StartPhase: 0deg
+ }
+ }
+}
diff --git a/fixtures/Canonical/WireForm/blender-ball-coil.firmament b/fixtures/Canonical/WireForm/blender-ball-coil.firmament
new file mode 100644
index 00000000..7a0d02a8
--- /dev/null
+++ b/fixtures/Canonical/WireForm/blender-ball-coil.firmament
@@ -0,0 +1,19 @@
+Model BlenderBallCoilWitness {
+ Units: mm
+ Frustum CupInterior { BottomRadius: 20mm; TopRadius: 34mm; Height: 64mm }
+ Sphere CaptiveBallProxy { Radius: 9mm }
+ WireForm BlenderBallCoil {
+ Diameter: 2mm
+ Material: Standard.Materials.StainlessSteel.304_Annealed
+ StartFrame { Origin: [0mm,0mm,0mm]; Tangent: [1,0,0]; Up: [0,0,1] }
+ SurfaceCoil Winding {
+ Surface: CaptiveBallProxy
+ Side: Outside
+ Clearance: 1mm
+ Turns: 7
+ StartLatitude: 65deg
+ EndLatitude: -65deg
+ Handedness: RightHanded
+ }
+ }
+}
diff --git a/fixtures/Canonical/WireForm/cylinder-surface-coil.firmament b/fixtures/Canonical/WireForm/cylinder-surface-coil.firmament
new file mode 100644
index 00000000..0572ca67
--- /dev/null
+++ b/fixtures/Canonical/WireForm/cylinder-surface-coil.firmament
@@ -0,0 +1,10 @@
+Model CylinderSurfaceCoilWitness {
+ Units: mm
+ Cylinder Drum { Radius: 10mm; Height: 40mm }
+ WireForm DrumWinding {
+ Diameter: 2mm
+ Material: Standard.Materials.StainlessSteel.304_Annealed
+ StartFrame { Origin: [0mm,0mm,0mm]; Tangent: [1,0,0]; Up: [0,0,1] }
+ SurfaceCoil Winding { Surface: Drum; Side: Outside; Clearance: 1mm; Turns: 6; AxialPitch: 5mm; Handedness: RightHanded }
+ }
+}
diff --git a/fixtures/Canonical/WireForm/frustum-surface-coil.firmament b/fixtures/Canonical/WireForm/frustum-surface-coil.firmament
new file mode 100644
index 00000000..cf224494
--- /dev/null
+++ b/fixtures/Canonical/WireForm/frustum-surface-coil.firmament
@@ -0,0 +1,17 @@
+Model FrustumSurfaceCoilWitness {
+ Units: mm
+ Frustum CupInnerFrustum { BottomRadius: 18mm; TopRadius: 30mm; Height: 60mm }
+ WireForm MixerSpring {
+ Diameter: 2mm
+ Material: Standard.Materials.StainlessSteel.304_Annealed
+ StartFrame { Origin: [0mm,0mm,0mm]; Tangent: [1,0,0]; Up: [0,0,1] }
+ SurfaceCoil Winding {
+ Surface: CupInnerFrustum
+ Side: Inside
+ Clearance: 1mm
+ Turns: 6
+ AxialPitch: 8mm
+ Handedness: RightHanded
+ }
+ }
+}
diff --git a/fixtures/Canonical/WireForm/left-handed-axis-coil.firmament b/fixtures/Canonical/WireForm/left-handed-axis-coil.firmament
new file mode 100644
index 00000000..0467eee4
--- /dev/null
+++ b/fixtures/Canonical/WireForm/left-handed-axis-coil.firmament
@@ -0,0 +1,9 @@
+Model LeftAxisCoilWitness {
+ Units: mm
+ WireForm LeftSpring {
+ Diameter: 2mm
+ Material: Standard.Materials.StainlessSteel.304_Annealed
+ StartFrame { Origin: [0mm,0mm,0mm]; Tangent: [1,0,0]; Up: [0,0,1] }
+ AxisCoil Winding { Radius: 12mm; Turns: 6; Height: 30mm; Handedness: LeftHanded }
+ }
+}
diff --git a/fixtures/Canonical/WireForm/sphere-surface-coil.firmament b/fixtures/Canonical/WireForm/sphere-surface-coil.firmament
new file mode 100644
index 00000000..c966a578
--- /dev/null
+++ b/fixtures/Canonical/WireForm/sphere-surface-coil.firmament
@@ -0,0 +1,18 @@
+Model SphereSurfaceCoilWitness {
+ Units: mm
+ Sphere BallSupport { Radius: 24mm }
+ WireForm SphereWinding {
+ Diameter: 2mm
+ Material: Standard.Materials.StainlessSteel.304_Annealed
+ StartFrame { Origin: [0mm,0mm,0mm]; Tangent: [1,0,0]; Up: [0,0,1] }
+ SurfaceCoil Winding {
+ Surface: BallSupport
+ Side: Outside
+ Clearance: 1mm
+ Turns: 6
+ StartLatitude: 55deg
+ EndLatitude: -55deg
+ Handedness: RightHanded
+ }
+ }
+}
diff --git a/fixtures/Canonical/WireForm/straight-coil-straight.firmament b/fixtures/Canonical/WireForm/straight-coil-straight.firmament
new file mode 100644
index 00000000..335cbbb3
--- /dev/null
+++ b/fixtures/Canonical/WireForm/straight-coil-straight.firmament
@@ -0,0 +1,11 @@
+Model ComposedCoilWitness {
+ Units: mm
+ WireForm ComposedSpring {
+ Diameter: 2mm
+ Material: Standard.Materials.StainlessSteel.304_Annealed
+ StartFrame { Origin: [0mm,0mm,0mm]; Tangent: [1,0,0]; Up: [0,0,1] }
+ Straight Lead { Length: 10mm }
+ AxisCoil Winding { Radius: 10mm; Turns: 4; Pitch: 5mm; Handedness: RightHanded }
+ Straight Tail { Length: 10mm }
+ }
+}
diff --git a/fixtures/Invalid/WireForm/coil-parameters-inconsistent.firmament b/fixtures/Invalid/WireForm/coil-parameters-inconsistent.firmament
new file mode 100644
index 00000000..95d2f410
--- /dev/null
+++ b/fixtures/Invalid/WireForm/coil-parameters-inconsistent.firmament
@@ -0,0 +1 @@
+Model Invalid { WireForm Wire { Diameter: 2mm; StartFrame { Origin: [0,0,0]; Tangent: [1,0,0]; Up: [0,0,1] } AxisCoil Bad { Radius: 10mm; Turns: 3; Pitch: 5mm; Height: 20mm } } }
diff --git a/fixtures/Invalid/WireForm/coil-radius-zero.firmament b/fixtures/Invalid/WireForm/coil-radius-zero.firmament
new file mode 100644
index 00000000..2c346e03
--- /dev/null
+++ b/fixtures/Invalid/WireForm/coil-radius-zero.firmament
@@ -0,0 +1 @@
+Model Invalid { WireForm Wire { Diameter: 2mm; StartFrame { Origin: [0,0,0]; Tangent: [1,0,0]; Up: [0,0,1] } AxisCoil Bad { Radius: 0mm; Turns: 3; Pitch: 5mm } } }
diff --git a/fixtures/Invalid/WireForm/coil-turn-overlap.firmament b/fixtures/Invalid/WireForm/coil-turn-overlap.firmament
new file mode 100644
index 00000000..a7089636
--- /dev/null
+++ b/fixtures/Invalid/WireForm/coil-turn-overlap.firmament
@@ -0,0 +1,8 @@
+Model InvalidCoilOverlap {
+ Units: mm
+ WireForm Spring {
+ Diameter: 2mm
+ StartFrame { Origin: [0mm,0mm,0mm]; Tangent: [1,0,0]; Up: [0,0,1] }
+ AxisCoil Winding { Radius: 12mm; Turns: 8; Pitch: 1mm; Handedness: RightHanded }
+ }
+}
diff --git a/fixtures/Invalid/WireForm/coil-turns-zero.firmament b/fixtures/Invalid/WireForm/coil-turns-zero.firmament
new file mode 100644
index 00000000..df306e62
--- /dev/null
+++ b/fixtures/Invalid/WireForm/coil-turns-zero.firmament
@@ -0,0 +1 @@
+Model Invalid { WireForm Wire { Diameter: 2mm; StartFrame { Origin: [0,0,0]; Tangent: [1,0,0]; Up: [0,0,1] } AxisCoil Bad { Radius: 10mm; Turns: 0; Pitch: 5mm } } }
diff --git a/fixtures/Invalid/WireForm/surfacecoil-offset-invalid.firmament b/fixtures/Invalid/WireForm/surfacecoil-offset-invalid.firmament
new file mode 100644
index 00000000..c642f21c
--- /dev/null
+++ b/fixtures/Invalid/WireForm/surfacecoil-offset-invalid.firmament
@@ -0,0 +1 @@
+Model Invalid { Sphere Support { Radius: 4mm } WireForm Wire { Diameter: 2mm; StartFrame { Origin: [0,0,0]; Tangent: [1,0,0]; Up: [0,0,1] } SurfaceCoil Bad { Surface: Support; Side: Inside; Clearance: 4mm; Turns: 3; StartLatitude: 45deg; EndLatitude: -45deg } } }
diff --git a/fixtures/Invalid/WireForm/surfacecoil-pole-singularity.firmament b/fixtures/Invalid/WireForm/surfacecoil-pole-singularity.firmament
new file mode 100644
index 00000000..21c67bb2
--- /dev/null
+++ b/fixtures/Invalid/WireForm/surfacecoil-pole-singularity.firmament
@@ -0,0 +1 @@
+Model Invalid { Sphere Support { Radius: 20mm } WireForm Wire { Diameter: 2mm; StartFrame { Origin: [0,0,0]; Tangent: [1,0,0]; Up: [0,0,1] } SurfaceCoil Bad { Surface: Support; Side: Outside; Clearance: 1mm; Turns: 3; StartLatitude: 90deg; EndLatitude: -45deg } } }
diff --git a/fixtures/Invalid/WireForm/surfacecoil-support-unsupported.firmament b/fixtures/Invalid/WireForm/surfacecoil-support-unsupported.firmament
new file mode 100644
index 00000000..aafbb1d4
--- /dev/null
+++ b/fixtures/Invalid/WireForm/surfacecoil-support-unsupported.firmament
@@ -0,0 +1 @@
+Model Invalid { Box Support { Length: 20mm; Width: 20mm; Height: 20mm } WireForm Wire { Diameter: 2mm; StartFrame { Origin: [0,0,0]; Tangent: [1,0,0]; Up: [0,0,1] } SurfaceCoil Bad { Surface: Support; Side: Outside; Clearance: 1mm; Turns: 3; AxialPitch: 5mm } } }