Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel
Bound Bezier boundary lift checks with control hulls
Yuechen Licbc4d11d6e05
diff --git a/Aetheris.Kernel.Core.Tests/Step242/PcurveBoundaryLiftBoundTests.cs b/Aetheris.Kernel.Core.Tests/Step242/PcurveBoundaryLiftBoundTests.csnew file mode 100644index 00000000..f93a33ec--- /dev/null+++ b/Aetheris.Kernel.Core.Tests/Step242/PcurveBoundaryLiftBoundTests.cs@@ -0,0 +1,163 @@+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.Topology;++namespace Aetheris.Kernel.Core.Tests.Step242;++public sealed class PcurveBoundaryLiftBoundTests+{+ private static BSplineSurfaceWithKnots Patch(bool flat = false, bool shifted = false) => new(3, 2,+ Enumerable.Range(0, 4).Select(i => (IReadOnlyList<Point3D>)Enumerable.Range(0, 3)+ .Select(j => flat ? new Point3D(i / 3d, j / 2d, 0)+ : new Point3D(10 + 15 * i + .2 * j * j, -7 + 9 * j + .3 * i * i, 4 + .7 * i * j)).ToArray()).ToArray(),+ "UNSPECIFIED", false, false, false, [4, 4], [3, 3], shifted ? [-4d, 3d] : [0d, 1d], shifted ? [2d, 7d] : [0d, 1d], "UNSPECIFIED");++ private static BSpline3Curve Curve(int degree, IReadOnlyList<Point3D> controls, double a = 0, double b = 1) =>+ new(degree, controls, [degree + 1, degree + 1], [a, b], "UNSPECIFIED", false, false, "UNSPECIFIED");++ [Theory]+ [InlineData(1)] [InlineData(2)] [InlineData(3)] [InlineData(5)] [InlineData(8)]+ public void BoundCoversSupportedDegreesAtLargeWorldAndParameterOffsets(int degree)+ {+ var random = new Random(147 + degree);+ var net = Enumerable.Range(0, degree + 1).Select(_ => (IReadOnlyList<Point3D>)Enumerable.Range(0, degree + 1)+ .Select(_ => new Point3D(1e6 + random.NextDouble() * 20, -2e6 + random.NextDouble() * 20, 3e6 + random.NextDouble() * 20)).ToArray()).ToArray();+ var patch = new BSplineSurfaceWithKnots(degree, degree, net, "UNSPECIFIED", false, false, false,+ [degree + 1, degree + 1], [degree + 1, degree + 1], [1000d, 1001d], [-7d, -3d], "UNSPECIFIED");+ var curve = Curve(degree, net[0], -7, -3);+ var interval = new ParameterInterval(-7, -3);+ var pcurve = PcurveGeometry.Line(interval, new(1000, -7), new(1000, -3));+ Assert.True(BrepPcurveLiftBounds.TryBoundaryBound(SurfaceGeometry.FromBSplineSurfaceWithKnots(patch),+ CurveGeometry.FromBSpline(curve), pcurve, interval, out var bound));+ for (var i = 0; i <= 1000; i++)+ {+ var t = interval.Start + (interval.End - interval.Start) * i / 1000d;+ var uv = pcurve.Evaluate(t);+ Assert.True((patch.Evaluate(uv.U, uv.V) - curve.Evaluate(t)).Length <= bound);+ }+ }++ [Theory]+ [InlineData(0, false)] [InlineData(0, true)]+ [InlineData(1, false)] [InlineData(1, true)]+ [InlineData(2, false)] [InlineData(2, true)]+ [InlineData(3, false)] [InlineData(3, true)]+ public void BoundCoversTheWholeTrimIncludingReversalAndRecoveredUvError(int side, bool reverse)+ {+ var patch = Patch(shifted: true); var fixedU = side < 2;+ var degree = fixedU ? patch.DegreeV : patch.DegreeU;+ var controls = Enumerable.Range(0, degree + 1).Select(i => fixedU+ ? patch.ControlPoints[side == 0 ? 0 : patch.DegreeU][i]+ : patch.ControlPoints[i][side == 2 ? 0 : patch.DegreeV]).ToArray();+ if (reverse) Array.Reverse(controls);+ controls[1] += new Vector3D(1e-7, -2e-8, 3e-8);+ var start = fixedU ? patch.DomainStartV : patch.DomainStartU;+ var end = fixedU ? patch.DomainEndV : patch.DomainEndU;+ var curve = Curve(degree, controls, start, end);+ var low = start + .17 * (end - start); var high = start + .89 * (end - start);+ var interval = new ParameterInterval(low, high);+ SurfaceParameterPoint Ideal(double t) => fixedU+ ? new(side == 0 ? patch.DomainStartU : patch.DomainEndU, reverse ? end - (t - start) : t)+ : new(reverse ? end - (t - start) : t, side == 2 ? patch.DomainStartV : patch.DomainEndV);+ var a = Ideal(interval.Start); var b = Ideal(interval.End);+ var pcurve = PcurveGeometry.Line(interval, new(a.U + 2e-10, a.V - 3e-10), new(b.U - 2e-10, b.V + 3e-10));+ Assert.True(BrepPcurveLiftBounds.TryBoundaryBound(SurfaceGeometry.FromBSplineSurfaceWithKnots(patch),+ CurveGeometry.FromBSpline(curve), pcurve, interval, out var bound));+ Assert.InRange(bound, 1e-7, 1e-5);+ for (var i = 0; i <= 4096; i++)+ {+ var t = interval.Start + (interval.End - interval.Start) * i / 4096d;+ var uv = pcurve.Evaluate(t);+ Assert.True((patch.Evaluate(uv.U, uv.V) - curve.Evaluate(t)).Length <= bound);+ }+ }++ [Fact]+ public void MatchingEndpointsAndMidpointDoNotCertifyAnOffSurfaceCurve()+ {+ var patch = Patch(flat: true);+ var curve = Curve(3, [new(0, 0, 0), new(1d / 3, 0, .01), new(2d / 3, 0, -.01), new(1, 0, 0)]);+ var interval = new ParameterInterval(0, 1);+ var pcurve = PcurveGeometry.Line(interval, new(0, 0), new(1, 0));+ foreach (var t in new[] { 0d, .5, 1d }) Assert.InRange(double.Abs(curve.Evaluate(t).Z), 0d, 1e-17);+ Assert.True(double.Abs(curve.Evaluate(.25).Z) > 1e-3);+ Assert.True(BrepPcurveLiftBounds.TryBoundaryBound(SurfaceGeometry.FromBSplineSurfaceWithKnots(patch),+ CurveGeometry.FromBSpline(curve), pcurve, interval, out var bound));+ Assert.True(bound > .01);+ var body = TrimmedPatch(patch, corrupt: true);+ var recovery = BrepPcurveRecovery.Populate(body.Topology, body.Geometry, body.Bindings);+ Assert.False(recovery.IsSuccess);+ Assert.Contains(recovery.Diagnostics, d => d.Code == "surf-pcurve-invalid");+ }++ [Fact]+ public void InteriorTrimKeepsDenseQualificationAndOffDomainOrRationalInputsCannotUseTheBound()+ {+ var patch = Patch(flat: true);+ var body = TrimmedPatch(patch, interior: true);+ var recovery = BrepPcurveRecovery.Populate(body.Topology, body.Geometry, body.Bindings);+ Assert.True(recovery.IsSuccess, string.Join("; ", recovery.Diagnostics));+ Assert.Equal(4, recovery.Count);+ Assert.All(body.Bindings.PcurveBindings, p => Assert.Equal(8193, p.Qualification!.LiftSamples));+ var interval = new ParameterInterval(0, 1);+ var edge = CurveGeometry.FromBSpline(Curve(3, patch.ControlPoints.Select(row => row[0]).ToArray()));+ var line = PcurveGeometry.Line(interval, new(0, 0), new(1, 0));+ var weights = patch.ControlPoints.Select(row => row.Select(_ => 1d).ToArray()).ToArray();+ weights[0][0] = 1.1;+ var rational = patch.WithWeights(weights);+ Assert.False(BrepPcurveLiftBounds.TryBoundaryBound(SurfaceGeometry.FromBSplineSurfaceWithKnots(rational), edge, line, interval, out _));+ Assert.False(BrepPcurveLiftBounds.TryBoundaryBound(SurfaceGeometry.FromBSplineSurfaceWithKnots(patch), edge, line, new(-1, 1), out _));+ var segmented = new BSpline3Curve(3, [new(0, 0, 0), new(.25, 0, 0), new(.5, 0, 0), new(.75, 0, 0), new(1, 0, 0)],+ [4, 1, 4], [0d, .5, 1d], "UNSPECIFIED", false, false, "UNSPECIFIED");+ Assert.False(BrepPcurveLiftBounds.TryBoundaryBound(SurfaceGeometry.FromBSplineSurfaceWithKnots(patch),+ CurveGeometry.FromBSpline(segmented), line, interval, out _));+ }++ [Fact]+ public void BoundaryRecoveryReportsABoundWithoutChangingTheRecoveredUvOrGeometry()+ {+ var body = TrimmedPatch(Patch(flat: true));+ var vertices = body.Topology.Vertices.Select(v => { Assert.True(body.TryGetVertexPoint(v.Id, out var point)); return (v.Id, point); }).ToArray(); var curves = body.Geometry.Curves.ToArray();+ var recovery = BrepPcurveRecovery.Populate(body.Topology, body.Geometry, body.Bindings);+ Assert.True(recovery.IsSuccess, string.Join("; ", recovery.Diagnostics));+ Assert.Equal(4, recovery.Count);+ Assert.All(body.Bindings.PcurveBindings, binding => {+ Assert.Equal(0, binding.Qualification!.LiftSamples);+ Assert.Equal("BezierBoundaryControlHull", binding.Qualification.RecoveryMethod);+ Assert.Equal(PcurveBindingOrigin.RecoveredSpline, binding.Qualification.Origin);+ Assert.InRange(binding.Qualification.MaximumLiftDeviationMillimetres, 0d, 1e-5);+ Assert.Equal(PcurveGeometryKind.Line, binding.Pcurve.Kind);+ });+ foreach (var (id, expected) in vertices) { Assert.True(body.TryGetVertexPoint(id, out var actual)); Assert.Equal(expected, actual); }+ Assert.Equal(curves, body.Geometry.Curves.ToArray());+ Assert.True(BrepPcurveValidator.Validate(body, 1e-5, requireEveryCoedge: true).IsValid);+ }++ private static BrepBody TrimmedPatch(BSplineSurfaceWithKnots patch, bool interior = false, bool corrupt = false)+ {+ var builder = new TopologyBuilder(); var geometry = new BrepGeometryStore(); var bindings = new BrepBindingModel();+ var low = interior ? .2 : 0d; var high = interior ? .8 : 1d;+ var uv = new[] { (low, low), (high, low), (high, high), (low, high) };+ var points = new Dictionary<VertexId, Point3D>();+ var vertices = uv.Select(p => { var id = builder.AddVertex(); points[id] = patch.Evaluate(p.Item1, p.Item2); return id; }).ToArray();+ var loop = builder.AllocateLoopId(); var uses = uv.Select(_ => builder.AllocateCoedgeId()).ToArray();+ for (var i = 0; i < 4; i++)+ {+ var j = (i + 1) % 4; var edge = builder.AddEdge(vertices[i], vertices[j]); var curveId = new CurveGeometryId(i + 1);+ var a = points[vertices[i]]; var b = points[vertices[j]];+ var degree = i % 2 == 0 ? patch.DegreeU : patch.DegreeV;+ var controls = Enumerable.Range(0, degree + 1).Select(k => a + (b - a) * (k / (double)degree)).ToArray();+ if (corrupt && i == 0) { controls[1] += new Vector3D(0, 0, .01); controls[2] += new Vector3D(0, 0, -.01); }+ geometry.AddCurve(curveId, CurveGeometry.FromBSpline(Curve(degree, controls)));+ bindings.AddEdgeBinding(new(edge, curveId, new ParameterInterval(0, 1)));+ builder.AddCoedge(new(uses[i], edge, loop, uses[j], uses[(i + 3) % 4], false));+ }+ builder.AddLoop(new Loop(loop, uses)); var face = builder.AddFace([loop]); builder.AddBody([builder.AddShell([face])]);+ var surface = new SurfaceGeometryId(1); geometry.AddSurface(surface, SurfaceGeometry.FromBSplineSurfaceWithKnots(patch));+ bindings.AddFaceBinding(new(face, surface));+ return new(builder.Model, geometry, bindings, points);+ }+}diff --git a/Aetheris.Kernel.Core/Brep/BrepBindings.cs b/Aetheris.Kernel.Core/Brep/BrepBindings.csindex 2d0ccffa..129c85de 100644--- a/Aetheris.Kernel.Core/Brep/BrepBindings.cs+++ b/Aetheris.Kernel.Core/Brep/BrepBindings.cs@@ -195,7 +195,8 @@ public readonly record struct CoedgePcurveBinding(/// straight line of its parameter rectangle (BUILD-PERF-M4: no inverse projection or dense lift).</summary>public enum PcurveBindingOrigin { SourceValidated, RecoveredAnalytic, RecoveredSpline, DerivedAnalytic, ConstructedBoundary }-/// <summary>Measured edge-to-surface-lift evidence for one face-local trim.</summary>+/// <summary>Edge-to-surface-lift evidence for one face-local trim. BezierBoundaryControlHull+/// reports a whole-span upper bound with zero samples. RecoveryMethod identifies the evidence.</summary>public sealed record PcurveQualification(PcurveBindingOrigin Origin,double MaximumLiftDeviationMillimetres,diff --git a/Aetheris.Kernel.Core/Brep/BrepPcurveLiftBounds.cs b/Aetheris.Kernel.Core/Brep/BrepPcurveLiftBounds.csnew file mode 100644index 00000000..9567413c--- /dev/null+++ b/Aetheris.Kernel.Core/Brep/BrepPcurveLiftBounds.cs@@ -0,0 +1,110 @@+using Aetheris.Kernel.Core.Geometry;+using Aetheris.Kernel.Core.Math;++namespace Aetheris.Kernel.Core.Brep;++/// <summary>Whole-span lift bounds for polynomial Bezier patch boundaries.+/// Unsupported representations retain the ordinary sampled qualification.</summary>+internal static class BrepPcurveLiftBounds+{+ private const double MachinePrecision = 2.2204460492503131e-16;++ internal static bool TryBoundaryBound(SurfaceGeometry surface, CurveGeometry curve,+ PcurveGeometry pcurve, ParameterInterval interval, out double bound)+ {+ bound = double.PositiveInfinity;+ if (surface.BSplineSurfaceWithKnots is not { IsRational: false } patch+ || curve.BSpline3 is not { } edge || pcurve.Kind != PcurveGeometryKind.Line+ || pcurve.Points.Count != 2 || pcurve.Domain != interval+ || !IsBezier(patch.DegreeU, patch.ControlPoints.Count, patch.FullKnotsU)+ || !IsBezier(patch.DegreeV, patch.ControlPoints[0].Count, patch.FullKnotsV)+ || !IsBezier(edge.Degree, edge.ControlPoints.Count, edge.FullKnots)+ || !double.IsFinite(interval.Start) || !double.IsFinite(interval.End)+ || !double.IsFinite(interval.End - interval.Start)+ || double.Abs(interval.End - interval.Start) <= 1e-15+ || double.Min(interval.Start, interval.End) < edge.DomainStart+ || double.Max(interval.Start, interval.End) > edge.DomainEnd)+ return false;++ // Derivative control hulls bound the support's sensitivity to UV error.+ // This also covers a recovered line slightly displaced from the ideal+ // boundary: its endpoints bound its entire affine displacement.+ var lu = 0d; var lv = 0d; var scale = 1d;+ for (var i = 0; i <= patch.DegreeU; i++)+ for (var j = 0; j <= patch.DegreeV; j++)+ {+ var point = patch.ControlPoints[i][j];+ scale = double.Max(scale, Magnitude(point));+ if (i < patch.DegreeU)+ lu = double.Max(lu, (patch.ControlPoints[i + 1][j] - point).Length);+ if (j < patch.DegreeV)+ lv = double.Max(lv, (patch.ControlPoints[i][j + 1] - point).Length);+ }+ foreach (var point in edge.ControlPoints) scale = double.Max(scale, Magnitude(point));+ lu *= patch.DegreeU / (patch.DomainEndU - patch.DomainStartU);+ lv *= patch.DegreeV / (patch.DomainEndV - patch.DomainStartV);++ var order = (patch.DegreeU + 1d) * (patch.DegreeV + 1d);+ var roundoff = 128d * MachinePrecision * scale * order * order;+ // Both evaluators snap parameters within 1e-12 of the domain end.+ // Include that displacement and arithmetic allowance instead of calling+ // the observed endpoint fit an exact mathematical identity.+ var uAllowance = ParameterAllowance(patch.DomainStartU, patch.DomainEndU,+ pcurve.Points[0].U, pcurve.Points[1].U, order);+ var vAllowance = ParameterAllowance(patch.DomainStartV, patch.DomainEndV,+ pcurve.Points[0].V, pcurve.Points[1].V, order);+ for (var side = 0; side < 4; side++)+ {+ var fixedU = side < 2;+ var degree = fixedU ? patch.DegreeV : patch.DegreeU;+ var start = fixedU ? patch.DomainStartV : patch.DomainStartU;+ var end = fixedU ? patch.DomainEndV : patch.DomainEndU;+ if (edge.Degree != degree || edge.DomainStart != start || edge.DomainEnd != end) continue;+ for (var reverse = 0; reverse < 2; reverse++)+ {+ var hull = 0d;+ for (var k = 0; k <= degree; k++)+ {+ var index = reverse == 0 ? k : degree - k;+ var point = fixedU+ ? patch.ControlPoints[side == 0 ? 0 : patch.DegreeU][index]+ : patch.ControlPoints[index][side == 2 ? 0 : patch.DegreeV];+ hull = double.Max(hull, (edge.ControlPoints[k] - point).Length);+ }+ SurfaceParameterPoint Ideal(double t)+ {+ var varying = reverse == 0 ? t : end - (t - start);+ return fixedU+ ? new(side == 0 ? patch.DomainStartU : patch.DomainEndU, varying)+ : new(varying, side == 2 ? patch.DomainStartV : patch.DomainEndV);+ }+ var a = Ideal(interval.Start); var b = Ideal(interval.End);+ var du = double.Max(double.Abs(pcurve.Points[0].U - a.U), double.Abs(pcurve.Points[1].U - b.U));+ var dv = double.Max(double.Abs(pcurve.Points[0].V - a.V), double.Abs(pcurve.Points[1].V - b.V));+ // Equal Bernstein bases make the difference a convex combination+ // of paired control differences. Add the UV Lipschitz bound.+ var candidate = double.BitIncrement(hull + lu * (du + uAllowance) + lv * (dv + vAllowance) + roundoff);+ if (double.IsFinite(candidate)) bound = double.Min(bound, candidate);+ }+ }+ return double.IsFinite(bound);+ }++ private static bool IsBezier(int degree, int controls, IReadOnlyList<double> knots)+ {+ // Keep the certificate away from near-degenerate parameter ranges and+ // the evaluator's absolute 1e-12 end-snap scale. These cases still sample.+ if (degree is < 1 or > 8 || controls != degree + 1 || knots.Count != 2 * controls+ || !double.IsFinite(knots[0]) || !double.IsFinite(knots[^1])+ || !double.IsFinite(knots[^1] - knots[0]) || knots[^1] - knots[0] <= 1e-9) return false;+ for (var i = 0; i < controls; i++)+ if (knots[i] != knots[0] || knots[i + controls] != knots[^1]) return false;+ return true;+ }++ private static double Magnitude(Point3D point) => double.Max(double.Abs(point.X), double.Max(double.Abs(point.Y), double.Abs(point.Z)));++ private static double ParameterAllowance(double start, double end, double a, double b, double order) =>+ 2e-12 + 128d * MachinePrecision * order * double.Max(1d,+ double.Max(double.Max(double.Abs(start), double.Abs(end)), double.Max(double.Abs(a), double.Abs(b))));+}diff --git a/Aetheris.Kernel.Core/Brep/BrepPcurveRecovery.cs b/Aetheris.Kernel.Core/Brep/BrepPcurveRecovery.csindex 2134d997..b9132850 100644--- a/Aetheris.Kernel.Core/Brep/BrepPcurveRecovery.cs+++ b/Aetheris.Kernel.Core/Brep/BrepPcurveRecovery.cs@@ -52,8 +52,10 @@ public static class BrepPcurveRecoverydiagnostics.Add(new("surf-pcurve-invalid", built.Diagnostic ?? "Pcurve construction failed.", coedge.Id.Value.ToString()));continue;}- var liftSamples = surface.BSplineSurfaceWithKnots is null ? 1025 : 8193;- var liftResidual = MaximumResidual(surface, curve, built.Pcurve, interval, liftSamples);+ var boundaryBounded = BrepPcurveLiftBounds.TryBoundaryBound(surface, curve, built.Pcurve, interval, out var bound)+ && bound <= qualificationTolerance;+ var liftSamples = boundaryBounded ? 0 : surface.BSplineSurfaceWithKnots is null ? 1025 : 8193;+ var liftResidual = boundaryBounded ? bound : MaximumResidual(surface, curve, built.Pcurve, interval, liftSamples);if (!double.IsFinite(liftResidual) || liftResidual > qualificationTolerance){diagnostics.Add(new("surf-pcurve-invalid",@@ -67,7 +69,7 @@ public static class BrepPcurveRecovery: surface.BSplineSurfaceWithKnots is null ? PcurveBindingOrigin.RecoveredAnalytic : PcurveBindingOrigin.RecoveredSpline;bindings.AddPcurveBinding(new(coedge.Id, face.Id, faceBinding.SurfaceGeometryId, built.Pcurve,Qualification: new(origin, liftResidual, qualificationTolerance, liftSamples,- built.Pcurve.Kind.ToString(), surface.Kind.ToString())));+ boundaryBounded ? "BezierBoundaryControlHull" : built.Pcurve.Kind.ToString(), surface.Kind.ToString())));maximum = double.Max(maximum, liftResidual);count++;}diff --git a/Aetheris.Kernel.Firmament.Tests/PcurveBoundaryQualificationTests.cs b/Aetheris.Kernel.Firmament.Tests/PcurveBoundaryQualificationTests.csnew file mode 100644index 00000000..9c7472d3--- /dev/null+++ b/Aetheris.Kernel.Firmament.Tests/PcurveBoundaryQualificationTests.cs@@ -0,0 +1,32 @@+using Aetheris.Kernel.Core.Brep;+using Aetheris.Kernel.Core.Step242;++namespace Aetheris.Kernel.Firmament.Tests;++public sealed class PcurveBoundaryQualificationTests+{+ [Theory]+ [InlineData("axis-coil.firmament")]+ [InlineData("helix.firmament")]+ public void GeneratedCoilBoundaryBoundsAlsoPassIndependentDenseLiftChecks(string name)+ {+ var path = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, "../../../../fixtures/Canonical/WireForm", name));+ var built = FirmamentBuildAndExport.CompileSource(File.ReadAllText(path), Path.GetDirectoryName(path));+ Assert.True(built.IsSuccess, string.Join("; ", built.Diagnostics));+ // This must import this execution's generated bytes, rather than a cached+ // external corpus body: it qualifies the real compiler roundtrip.+ var imported = Step242Importer.ImportBody(built.Value.StepText);+ Assert.True(imported.IsSuccess, string.Join("; ", imported.Diagnostics));+ var body = imported.Value;+ var certified = body.Bindings.PcurveBindings.Where(p => p.Qualification?.RecoveryMethod == "BezierBoundaryControlHull").ToArray();+ Assert.True(certified.Length > 100);+ Assert.All(certified, p => {+ Assert.Equal(0, p.Qualification!.LiftSamples);+ Assert.InRange(p.Qualification.MaximumLiftDeviationMillimetres, 0d, p.Qualification.QualificationToleranceMillimetres);+ });+ // An independent grid, unrelated to the old 8193-point guard, verifies+ // the actual recovered trims and complete UV-loop closure.+ var evidence = BrepPcurveValidator.Validate(body, 1e-5, requireEveryCoedge: true, samples: 4099);+ Assert.True(evidence.IsValid, string.Join("; ", evidence.Diagnostics));+ }+}diff --git a/docs/development/reports/2026-10/pcurve-boundary-qualification.md b/docs/development/reports/2026-10/pcurve-boundary-qualification.mdnew file mode 100644index 00000000..24270435--- /dev/null+++ b/docs/development/reports/2026-10/pcurve-boundary-qualification.md@@ -0,0 +1,121 @@+# Pcurve boundary qualification performance — 2026-10-26++Baseline: Aetheris `aaaa2cce`. Scope: pcurve recovery/qualification in the existing+kernel owner. No inverse fitting, recovered coordinates, engineering tolerances,+STEP emission, parser routes or display authority were changed.++## Finding and repair++A fresh import of the axis coil contained 4,096 spline-boundary coedges. Each+received an 8,193-point lift check. A per-coedge probe measured about 89 ms in+recovery and 4,336 ms in those checks. Most recovered pcurves were already simple+lines on polynomial Bezier patch boundaries. More aggressive fitting would not+address that measured cost.++`BrepPcurveLiftBounds` now bounds the actual recovered line against the actual 3D+edge over its full trim. For a clamped polynomial tensor-product Bezier patch,+paired boundary/edge control differences share the same Bernstein basis, so+their maximum norm bounds the entire curve difference. Derivative control hulls+bound the additional error from the recovered line's displacement in U and V.+Endpoint errors bound that whole affine displacement. The allowance also covers+the existing evaluators' end snapping and floating-point arithmetic; calculations+that cannot produce a finite bound fall back.++The fast family is deliberately bounded: degrees 1–8, polynomial supports and+edges, single clamped spans, matched varying parameter domains, finite+parameter spans above 1e-9, and a line pcurve with the actual edge trim domain. Both+boundary directions, reversal and partial trims are handled. No source filename,+trusted-import flag or kernel-origin claim is accepted as evidence.++Qualification uses this bound only when it fits the existing resolved tolerance.+Otherwise the previous 1,025/8,193-point checks remain. General rational and+multi-span recovery is unchanged. Retained source pcurves keep their existing+checks and provenance. The implementation has no global mutable cache/state.++BRep evidence reports `BezierBoundaryControlHull`, zero lift samples and the+conservative upper bound. Origin remains RecoveredSpline. Zero samples is honest+proof metadata rather than a fictitious claim that the dense grid ran. The+surface inspection guide and API XML explain the distinction. A NURBS surface+can itself be exact; approximation introduced by exchange/conversion remains+subject to the existing recovery budget.++## Timing protocol and results++Windows, .NET 10.0.401, same host, frozen baseline/candidate CLI directories.+Each invocation starts a new process; this is process-cold with a warm OS file+cache, not a reboot/storage-cold test. Three paired trials per source alternate+baseline/candidate order. No other agent-owned qualification workload ran during+these trials. Baseline and candidate emit the same engineering artifacts.++| Command/input | Baseline median s | Candidate median s | Speedup |+|---|---:|---:|---:|+| validate axis-coil | 7.522 | 3.370 | 2.23× |+| validate helix | 7.428 | 3.309 | 2.25× |+| validate coil-on-stem | 5.983 | 3.041 | 1.97× |+| build guitar | 9.257 | 9.354 | 0.99× |++The guitar control has no demonstrated improvement; its roughly 1% difference+lies within the overlapping sample ranges. This is not a claim that every+source exceeds the earlier strict 2× target: coil-on-stem measures 1.97×.++An initial standalone importer profile fell from 6.619 s to 2.448 s total.+Pcurve recovery/qualification fell to 0.311 s; orientation still took 1.679 s.+This isolates the next dominant import cost without changing it in this pass.+Those profiles and the paired timings are distinct experiments, not combined+into an invented composite timing.++## Qualification++- Sixteen focused Core tests cover all four boundaries and reversed curve+ direction, partial/nondefault domains, UV fitting error, degrees 1–8, large+ coordinates, off-domain/rational/multi-span exclusions, interior-trim fallback,+ geometry preservation and an off-surface curve whose endpoints/midpoint agree.+- Two real compiler tests build axis-coil and helix, import their generated STEP,+ require bounded qualification, then independently check every recovered trim+ and UV-loop closure with a separate 4,099-point grid. These generated imports+ are the test subject; external corpus tests retain Step242Corpus ownership.+- Full regression, canonical STEP parity and dense-bound comparison completion+ are recorded below. No generated logs/STEP/JSON outputs are tracked.++Ignored evidence: `artifacts/local/pcurve-perf/`. `baseline-profile.json` separates+recovery from dense checks per coedge; `paired-timings.json` retains every sample;+`baseline-cli` and `candidate-cli` freeze the compared executables. Reproduce with+normal CLI validate/build on `fixtures/Canonical/WireForm/{axis-coil,helix}.firmament`,+`Assembly/coil-on-stem.firmament`, and `AssemblyInterfaces/GuitarX0/guitar-x0.firmament`.++This replaces redundant brute-force qualification for a provable family. It does+not reduce a physical tolerance to chase a timing number, and it does not claim+that sampled fallback is a universal continuous-error certificate.++## Completion and verdict++**Success for the bounded optimization.** The motivating builds are materially+faster, the tolerance contract is preserved, and the actual engineering outputs+remain unchanged. The earlier strict 2× target is still narrowly missed by the+coil-on-stem median (1.97×); no universal 2× promise is made.++- Release solution build: zero errors (`build.log`).+- Core fast lane: 1,127 passed (`fast.log`).+- Full solution: **6,117 passed, zero failed, two existing Drawing skips** across+ 20 nonempty test projects (`full.log`); empty FrictionLab remains empty.+- Real compiler corpus: **380 sources**, 322 validate, 297 STEP builds succeed,+ **zero exit-status or SHA-256 differences**, no timeouts (`corpus/`). This is+ compared with the prior fully qualified corpus, not a newly recorded baseline.+- The unchanged full NIST/OCCT interchange lane passed without golden updates.+- `dense-bound-comparison.json` reapplies the old 8,193-point check independently+ to all **4,096** bounded coil coedges. **Zero bound underestimates**. Worst+ observed dense deviation is below 9.1e-9 mm; the largest reported bound is below+ 9.5e-9 mm. These are internal numerical errors, not manufacturing callouts.+- The browser development SDK was rebuilt (`../pcurve-sdk-build.log`), so the+ shared kernel change is available to linked Helios checkouts. No browser+ timing or new live UI qualification is claimed in this kernel pass.+- `benchmark-info.json` records the host/runtime and frozen CLI/Core assembly+ hashes. Source changes are confined to this repository; output stays ignored.+- Code-quality review: no input trust bypass, tolerance inflation, altered UVs,+ source rewriting, global mutable state or additional native dependency.+ `git diff --check` passes. Temporary test/profiler/build processes have exited.++General rational/multi-span trim recovery retains dense fallback. Its fitting+and periodic refinement checks were inspected, but this pass does not substitute+an unproven low-resolution grid for that family. The next measured importer cost+is orientation/display tessellation, isolated from pcurve qualification.diff --git a/docs/public/firmament/surface-inspection.md b/docs/public/firmament/surface-inspection.mdindex 2233fbec..b16fcca6 100644--- a/docs/public/firmament/surface-inspection.md+++ b/docs/public/firmament/surface-inspection.md@@ -12,6 +12,14 @@ Helios SDK packets currently carry source face ranges and occurrence edges withoWhole-model surface and translucent views retain the actual CIR/SDF field when active. A field shader has no per-face trim mask. Face colours and face isolation explicitly show its retained BRep mesh proxy, with a notice in Helios. Proxy pixels must not be mistaken for proof of the field's silhouette. Compare the whole field with the proxy to investigate a discrepancy.+Recovered trims must reconstruct their shared 3D edge within the qualification+tolerance. Polynomial Bezier patch boundaries can be checked with a conservative+control-net and parameter-error bound over the whole trim. In the BRep API this+reports `BezierBoundaryControlHull`: the maximum lift deviation is an upper+bound, and zero lift samples means the bound replaced sampling. It does not mean+the trim was unchecked. The recovered coordinates and tolerance are unchanged;+rational, multi-span and other unqualified representations retain sampled checks.+The reusable API is exported by `@aetheris/three-telos`:```ts@@ -26,4 +34,4 @@ host.setScene(inspectSurfaces(sourceScene, "normal"));Projection keeps engineering authority in the source scene. Packed faces share the complete immutable geometry and GPU buffers; triangle draw ranges preserve original triangle indices for source selection. It never reconstructs BRep edges from tessellation or changes export geometry. Products own controls, source metadata and screenshots; Three Telos owns drawing, camera and picking.-For reproducible corpus review, `scripts/inspect-step-legacy-cadmata.mts` captures five matched-camera views, face inventories and optional orbit/zoom/source-face click witnesses through real STEP upload. Outputs belong under ignored `artifacts/local/`. The canvas `data-surface-inspection` and `data-surface-inspection-pick` attributes expose the active projection and actual hit for automation. Contact sheets are review evidence, not engineering qualification or human signoff. See [X4 qualification](../../development/reports/2026-10/STEP-TRIM-TRIANGULATION-X4.md).+For reproducible corpus review, `scripts/inspect-step-legacy-cadmata.mts` captures five matched-camera views, face inventories and optional orbit/zoom/source-face click witnesses through real STEP upload. Outputs belong under ignored `artifacts/local/`. The canvas `data-surface-inspection` and `data-surface-inspection-pick` attributes expose the active projection and actual hit for automation. Contact sheets are review evidence, not engineering qualification or human signoff.