Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

34.2 KB
Raw Blame
using Aetheris.Kernel.Core.Geometry.Curves;
using Aetheris.Kernel.Core.Geometry;
using Aetheris.Kernel.Core.Geometry.Surfaces;
using Aetheris.Kernel.Core.Math;
using Aetheris.Kernel.Core.Topology;

namespace Aetheris.Kernel.Core.Brep;

public sealed record BrepPcurveRecoveryResult(bool IsSuccess, int Count, double MaximumResidual, IReadOnlyList<BrepPcurveRecoveryDiagnostic> Diagnostics);
public sealed record BrepPcurveRecoveryDiagnostic(string Code, string Message, string? Entity = null);

/// <summary>Builds deterministic face-local pcurves from edge and support geometry.</summary>
public static class BrepPcurveRecovery
{
    /// <summary>Tag on qualifications accepted at the source's measured gap rather than the policy tolerance.</summary>
    public const string SourceTolerantMethod = "SourceTolerant";

    /// <param name="sourceTolerance">When set, an imported edge whose 3D curve lies off its surface by more than
    /// <paramref name="tolerance"/> but no more than this is accepted as a tolerant edge: its pcurve is kept, its
    /// measured gap becomes its qualification tolerance, and nothing is repaired.</param>
    public static BrepPcurveRecoveryResult Populate(TopologyModel topology, BrepGeometryStore geometry, BrepBindingModel bindings,
        double tolerance = 1e-5, int sampleCount = 129, double? sourceTolerance = null)
    {
        var diagnostics = new List<BrepPcurveRecoveryDiagnostic>();
        var count = 0;
        var maximum = 0d;
        foreach (var face in topology.Faces.OrderBy(item => item.Id.Value))
        {
            if (!bindings.TryGetFaceBinding(face.Id, out var faceBinding) || !geometry.TryGetSurface(faceBinding.SurfaceGeometryId, out var surface) || surface is null)
                continue;
            foreach (var coedge in face.LoopIds.Select(topology.GetLoop).SelectMany(loop => loop.CoedgeIds.Select(topology.GetCoedge)))
            {
                if (!bindings.TryGetEdgeBinding(coedge.EdgeId, out var edgeBinding) || !geometry.TryGetCurve(edgeBinding.CurveGeometryId, out var curve) || curve is null
                    || edgeBinding.TrimInterval is not { } interval)
                {
                    diagnostics.Add(new("surf-pcurve-invalid", $"Coedge {coedge.Id.Value} has no bounded 3D edge curve.", coedge.Id.Value.ToString()));
                    continue;
                }
                var qualificationTolerance = ResolveQualificationTolerance(surface, curve, tolerance);
                if (bindings.TryGetPcurveBinding(coedge.Id, out var retained))
                {
                    var residual = MaximumResidual(surface, curve, retained.Pcurve, interval, sampleCount);
                    if (retained.FaceId != face.Id || retained.SurfaceGeometryId != faceBinding.SurfaceGeometryId || residual > qualificationTolerance)
                        diagnostics.Add(new("surf-pcurve-invalid", "Retained pcurve has inconsistent ownership or geometry.", coedge.Id.Value.ToString()));
                    maximum = double.Max(maximum, residual); count++; continue;
                }
                (PcurveGeometry? Pcurve, double MaximumResidual, string? Diagnostic) built;
                var tolerant = false;
                try
                {
                    built = Build(surface, curve, interval, qualificationTolerance, sampleCount);
                    // Measure, record, don't repair: the gap is the source's, within what it declared.
                    if (built.Pcurve is null && sourceTolerance is { } cap && cap > qualificationTolerance
                        && double.IsFinite(built.MaximumResidual) && built.MaximumResidual <= cap)
                    {
                        var retry = Build(surface, curve, interval, cap, sampleCount);
                        // A looser fit must still be a trace on the surface: on a B-spline support it may not
                        // wander outside the parameter domain.
                        if (retry.Pcurve is not null && WithinDomain(surface, retry.Pcurve)) { built = retry; tolerant = true; qualificationTolerance = cap; }
                    }
                }
                catch (Exception exception) when (exception is ArgumentException or InvalidOperationException or NotSupportedException)
                {
                    diagnostics.Add(new("surf-pcurve-invalid",
                        $"Face {face.Id.Value}, edge {coedge.EdgeId.Value}, {surface.Kind}: {exception.Message}",
                        coedge.Id.Value.ToString()));
                    continue;
                }
                if (built.Pcurve is null)
                {
                    diagnostics.Add(new("surf-pcurve-invalid", built.Diagnostic ?? "Pcurve construction failed.", coedge.Id.Value.ToString()));
                    continue;
                }
                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",
                        $"Face {face.Id.Value}, edge {coedge.EdgeId.Value}, {surface.Kind}: lifted pcurve residual {liftResidual:R} mm exceeds {qualificationTolerance:R} mm over {liftSamples} samples.",
                        coedge.Id.Value.ToString()));
                    continue;
                }
                var exactPlanarProjection = surface.Plane is not null
                    && (curve.Kind is CurveGeometryKind.Line3 or CurveGeometryKind.Circle3 || curve.BSpline3 is not null);
                var origin = exactPlanarProjection ? PcurveBindingOrigin.DerivedAnalytic
                    : surface.BSplineSurfaceWithKnots is null ? PcurveBindingOrigin.RecoveredAnalytic : PcurveBindingOrigin.RecoveredSpline;
                // A tolerant edge is qualified at its measured gap (with a little headroom), not at the cap.
                var bindingTolerance = tolerant ? double.Min(qualificationTolerance, double.Max(tolerance, liftResidual * 1.01d)) : qualificationTolerance;
                bindings.AddPcurveBinding(new(coedge.Id, face.Id, faceBinding.SurfaceGeometryId, built.Pcurve,
                    Qualification: new(origin, liftResidual, bindingTolerance, liftSamples,
                        tolerant ? $"{SourceTolerantMethod}:{built.Pcurve.Kind}" : boundaryBounded ? "BezierBoundaryControlHull" : built.Pcurve.Kind.ToString(), surface.Kind.ToString())));
                maximum = double.Max(maximum, liftResidual);
                count++;
            }
        }
        return new(diagnostics.Count == 0, count, maximum, diagnostics);
    }

    private static bool WithinDomain(SurfaceGeometry surface, PcurveGeometry pcurve)
    {
        if (surface.BSplineSurfaceWithKnots is not { } spline) return true;
        const double slack = 1e-9;
        return Enumerable.Range(0, 257).Select(i => pcurve.Evaluate(pcurve.Domain.Start + (pcurve.Domain.End - pcurve.Domain.Start) * i / 256d))
            .All(uv => double.IsFinite(uv.U) && double.IsFinite(uv.V)
                && uv.U >= spline.DomainStartU - slack && uv.U <= spline.DomainEndU + slack
                && uv.V >= spline.DomainStartV - slack && uv.V <= spline.DomainEndV + slack);
    }

    private static double ResolveQualificationTolerance(SurfaceGeometry surface, CurveGeometry curve, double baseTolerance)
    {
        var curveRecovery = curve.RecoveryProvenance;
        var surfaceRecovery = surface.RecoveryProvenance;
        if (curveRecovery is null && surfaceRecovery is null) return baseTolerance;
        var budget = double.Min(curveRecovery?.RecoveryToleranceMillimetres ?? double.PositiveInfinity,
            surfaceRecovery?.RecoveryToleranceMillimetres ?? double.PositiveInfinity);
        var observed = (curveRecovery?.MeasuredMaxDeviationMillimetres ?? 0d)
            + (surfaceRecovery?.MeasuredMaxDeviationMillimetres ?? 0d);
        return double.Min(budget, double.Max(baseTolerance, baseTolerance + observed * 1.25d));
    }

    private static (PcurveGeometry? Pcurve, double MaximumResidual, string? Diagnostic) Build(
        SurfaceGeometry surface, CurveGeometry curve, ParameterInterval interval, double tolerance, int samples)
    {
        if (TryBuildIsoParametricPcurve(surface, curve, interval) is { } exact)
            return (exact, 0d, null);
        if (surface.Plane is { } plane)
        {
            var start = PlaneUv(plane, EvaluateCurve(curve, interval.Start));
            var end = PlaneUv(plane, EvaluateCurve(curve, interval.End));
            if (curve.Kind == CurveGeometryKind.Line3) return (PcurveGeometry.Line(interval, start, end), 0d, null);
            if (curve.Kind == CurveGeometryKind.Circle3 && curve.Circle3 is { } circle)
            {
                var center = PlaneUv(plane, circle.Center);
                var cosinePoint = PlaneUv(plane, circle.Evaluate(0d));
                var sinePoint = PlaneUv(plane, circle.Evaluate(double.Pi / 2d));
                return (PcurveGeometry.Ellipse(interval, center,
                    new(cosinePoint.U - center.U, cosinePoint.V - center.V),
                    new(sinePoint.U - center.U, sinePoint.V - center.V)), 0d, null);
            }
            if (curve.BSpline3 is { } polynomial)
            {
                // Affine projection commutes with B-spline evaluation. The hull bound
                // certifies the whole 3D curve lies on this support, without fitting.
                var bound = polynomial.ControlPoints.Max(p => double.Abs((p - plane.Origin).Dot(plane.Normal.ToVector())));
                if (bound > tolerance) return (null, bound, "Polynomial edge control hull is not on the planar support.");
                var controls = polynomial.ControlPoints.Select(p => { var uv = PlaneUv(plane, p); return new Point3D(uv.U, uv.V, 0); }).ToArray();
                var uvCurve = new BSpline3Curve(polynomial.Degree, controls, polynomial.KnotMultiplicities, polynomial.KnotValues,
                    polynomial.CurveForm, polynomial.ClosedCurve, polynomial.SelfIntersect, polynomial.KnotSpec);
                return (PcurveGeometry.Polynomial(interval, uvCurve), bound, null);
            }
            var lineCandidate = PcurveGeometry.Line(interval, start, end);
            var lineResidual = MaximumResidual(surface, curve, lineCandidate, interval, 67);
            if (lineResidual <= tolerance) return (lineCandidate, lineResidual, null);
            const int denseSamples = 4097;
            return (PcurveGeometry.Polyline(interval, Sample(interval, denseSamples, t => PlaneUv(plane, EvaluateCurve(curve, t)))), 0d, null);
        }
        if (surface.Cylinder is { } cylinder)
            return BuildPeriodicAnalytic(surface, curve, interval, tolerance, point => CylinderUv(cylinder, point));
        if (surface.Cone is { } cone)
        {
            // A cone apex has no unique U coordinate. For a straight generator,
            // borrow its one-sided interior angle instead of fitting atan2(0,0).
            // The independent lift check still proves the complete admitted edge.
            if (curve.Line3 is { } generator)
            {
                var a = generator.Evaluate(interval.Start);
                var b = generator.Evaluate(interval.End);
                if ((a - cone.Apex).Length <= tolerance || (b - cone.Apex).Length <= tolerance)
                {
                    var interior = ConeUv(cone, generator.Evaluate((interval.Start + interval.End) / 2));
                    var start = ConeUv(cone, a) with { U = interior.U };
                    var end = ConeUv(cone, b) with { U = interior.U };
                    var candidate = PcurveGeometry.Line(interval, start, end);
                    var residual = MaximumResidual(surface, curve, candidate, interval, 1025);
                    if (residual <= tolerance) return (candidate, residual, null);
                }
            }
            return BuildPeriodicAnalytic(surface, curve, interval, tolerance, point => ConeUv(cone, point),
                singular: point => (point - cone.Apex).Length <= 1e-9 * double.Max(1d, (EvaluateCurve(curve, interval.Start) - cone.Apex).Length));
        }
        if (surface.Sphere is { } sphere)
            return BuildPeriodicAnalytic(surface, curve, interval, tolerance, point => SphereUv(sphere, point),
                singular: point => (point - sphere.Center - sphere.Axis.ToVector() * (point - sphere.Center).Dot(sphere.Axis.ToVector())).Length <= 1e-9 * sphere.Radius);
        if (surface.Torus is { } torus)
            return BuildPeriodicAnalytic(surface, curve, interval, tolerance, point => TorusUv(torus, point), unwrapV: true);
        if (surface.BSplineSurfaceWithKnots is not { } spline)
            return (null, double.PositiveInfinity, $"Surface family {surface.Kind} is outside the qualified pcurve matrix.");

        var startInverse = ProjectSplinePoint(spline, EvaluateCurve(curve, interval.Start), null, tolerance);
        var endInverse = ProjectSplinePoint(spline, EvaluateCurve(curve, interval.End), startInverse.Success ? startInverse.Uv : null, tolerance);
        if (startInverse.Success && endInverse.Success)
        {
            var lineCandidate = PcurveGeometry.Line(interval, startInverse.Uv, endInverse.Uv);
            var lineResidual = MaximumResidual(surface, curve, lineCandidate, interval, 67);
            if (lineResidual <= tolerance) return (lineCandidate, lineResidual, null);
        }

        var bestResidual = double.PositiveInfinity;
        for (var inverseSamples = 129; inverseSamples <= 4097; inverseSamples = (inverseSamples - 1) * 2 + 1)
        {
            var uv = new List<SurfaceParameterPoint>(inverseSamples);
            SurfaceParameterPoint? seed = null;
            var inversionFailed = false;
            for (var index = 0; index < inverseSamples; index++)
            {
                var t = interval.Start + ((interval.End - interval.Start) * index / (inverseSamples - 1d));
                var inverse = ProjectSplinePoint(spline, EvaluateCurve(curve, t), seed, tolerance);
                if (!inverse.Success)
                {
                    bestResidual = double.Min(bestResidual, inverse.Residual);
                    inversionFailed = true;
                    break;
                }
                seed = inverse.Uv;
                uv.Add(inverse.Uv);
            }
            if (inversionFailed) continue;
            var candidate = PcurveGeometry.Polyline(interval, uv);
            var residual = MaximumResidual(surface, curve, candidate, interval, (inverseSamples - 1) * 2 + 1);
            bestResidual = double.Min(bestResidual, residual);
            if (residual <= tolerance) return (candidate, residual, null);
        }
        return (null, bestResidual,
            $"Spline pcurve inversion/refinement exceeded 4097 samples; best lifted residual={bestResidual:R} mm, tolerance={tolerance:R} mm.");
    }

    internal static (bool Success, SurfaceParameterPoint Uv, double Residual) ProjectSplinePoint(BSplineSurfaceWithKnots spline, Point3D target, SurfaceParameterPoint? prior, double tolerance)
    {
        // Intersection traces are parameter-continuous, so the preceding inverse is
        // the deterministic seed after the first sample. Avoiding a fresh global grid
        // search at every dense qualification point keeps high-accuracy pcurves bounded.
        var best = prior ?? GridSeed(spline, target);
        for (var iteration = 0; iteration < 32; iteration++)
        {
            var point = spline.Evaluate(best.U, best.V);
            var residual = point - target;
            if (residual.Length <= 1e-8d) return (true, best, residual.Length);
            var hu = double.Max((spline.DomainEndU - spline.DomainStartU) * 1e-4d, 1e-7d);
            var hv = double.Max((spline.DomainEndV - spline.DomainStartV) * 1e-4d, 1e-7d);
            var uLow = double.Max(best.U - hu, spline.DomainStartU);
            var uHigh = double.Min(best.U + hu, spline.DomainEndU);
            var vLow = double.Max(best.V - hv, spline.DomainStartV);
            var vHigh = double.Min(best.V + hv, spline.DomainEndV);
            // These are parameter spans, not model-space distances. Avoid the
            // Vector3D division operator's world-space near-zero threshold.
            if (uHigh - uLow <= 1e-15d || vHigh - vLow <= 1e-15d) break;
            var du = (spline.Evaluate(uHigh, best.V) - spline.Evaluate(uLow, best.V)) * (1d / (uHigh - uLow));
            var dv = (spline.Evaluate(best.U, vHigh) - spline.Evaluate(best.U, vLow)) * (1d / (vHigh - vLow));
            var a = du.Dot(du); var b = du.Dot(dv); var c = dv.Dot(dv);
            var r1 = du.Dot(residual); var r2 = dv.Dot(residual);
            var determinant = (a * c) - (b * b);
            if (double.Abs(determinant) <= 1e-18d) break;
            var deltaU = ((c * r1) - (b * r2)) / determinant;
            var deltaV = ((a * r2) - (b * r1)) / determinant;
            var accepted = false;
            for (var damping = 1d; damping >= 1d / 64d; damping *= .5d)
            {
                var candidate = new SurfaceParameterPoint(
                    System.Math.Clamp(best.U - (deltaU * damping), spline.DomainStartU, spline.DomainEndU),
                    System.Math.Clamp(best.V - (deltaV * damping), spline.DomainStartV, spline.DomainEndV));
                if ((spline.Evaluate(candidate.U, candidate.V) - target).LengthSquared >= residual.LengthSquared) continue;
                best = candidate; accepted = true; break;
            }
            if (!accepted) break;
        }
        // Deterministic bounded pattern refinement handles domain-boundary minima where
        // the two-column normal equation can become poorly conditioned.
        var stepU = (spline.DomainEndU - spline.DomainStartU) / 32d;
        var stepV = (spline.DomainEndV - spline.DomainStartV) / 32d;
        var bestDistance = (spline.Evaluate(best.U, best.V) - target).LengthSquared;
        for (var iteration = 0; iteration < 64 && (stepU > 1e-13d || stepV > 1e-13d); iteration++)
        {
            var improved = false;
            foreach (var offsetU in new[] { -stepU, 0d, stepU }) foreach (var offsetV in new[] { -stepV, 0d, stepV })
            {
                if (offsetU == 0d && offsetV == 0d) continue;
                var candidate = new SurfaceParameterPoint(
                    System.Math.Clamp(best.U + offsetU, spline.DomainStartU, spline.DomainEndU),
                    System.Math.Clamp(best.V + offsetV, spline.DomainStartV, spline.DomainEndV));
                var distance = (spline.Evaluate(candidate.U, candidate.V) - target).LengthSquared;
                if (distance >= bestDistance) continue;
                best = candidate; bestDistance = distance; improved = true;
            }
            if (!improved) { stepU *= .5d; stepV *= .5d; }
        }
        var finalResidual = (spline.Evaluate(best.U, best.V) - target).Length;
        return (finalResidual <= tolerance, best, finalResidual);
    }

    private static SurfaceParameterPoint GridSeed(BSplineSurfaceWithKnots spline, Point3D target)
    {
        // BUILD-PERF-M2: the seed samples depend only on the surface, so they are evaluated once per
        // surface and scanned per target. Same samples, same order, same strict comparison: the
        // result is identical to evaluating them for every target (which was ~9300 surface
        // evaluations per seed and dominated spline-tube imports).
        var samples = SeedSamples.GetValue(spline, BuildSeedSamples);
        var best = new SurfaceParameterPoint(spline.DomainStartU, spline.DomainStartV);
        var distance = double.PositiveInfinity;
        for (var i = 0; i < samples.Length; i++)
        {
            var d = (samples[i].Point - target).LengthSquared;
            if (d < distance) { distance = d; best = samples[i].Uv; }
        }
        return best;
    }

    private static readonly System.Runtime.CompilerServices.ConditionalWeakTable<BSplineSurfaceWithKnots, (SurfaceParameterPoint Uv, Point3D Point)[]> SeedSamples = new();

    private static (SurfaceParameterPoint Uv, Point3D Point)[] BuildSeedSamples(BSplineSurfaceWithKnots spline)
    {
        const int divisions = 32;
        // Trim endpoints commonly lie on a support-domain boundary. A narrow patch can
        // be missed by a two-dimensional grid even when its boundary is easy to sample.
        const int boundaryDivisions = 2048;
        var samples = new List<(SurfaceParameterPoint, Point3D)>(((divisions + 1) * (divisions + 1)) + (4 * (boundaryDivisions + 1)));
        for (var i = 0; i <= divisions; i++) for (var j = 0; j <= divisions; j++)
        {
            var u = spline.DomainStartU + ((spline.DomainEndU - spline.DomainStartU) * i / divisions);
            var v = spline.DomainStartV + ((spline.DomainEndV - spline.DomainStartV) * j / divisions);
            Add(u, v);
        }
        for (var i = 0; i <= boundaryDivisions; i++)
        {
            var u = spline.DomainStartU + (spline.DomainEndU - spline.DomainStartU) * i / boundaryDivisions;
            var v = spline.DomainStartV + (spline.DomainEndV - spline.DomainStartV) * i / boundaryDivisions;
            Add(u, spline.DomainStartV);
            Add(u, spline.DomainEndV);
            Add(spline.DomainStartU, v);
            Add(spline.DomainEndU, v);
        }
        return samples.ToArray();

        void Add(double u, double v) => samples.Add((new SurfaceParameterPoint(u, v), spline.Evaluate(u, v)));
    }

    private static Point3D EvaluateCurve(CurveGeometry curve, double parameter) => curve.Kind switch
    {
        CurveGeometryKind.Line3 => curve.Line3!.Value.Evaluate(parameter),
        CurveGeometryKind.Circle3 => curve.Circle3!.Value.Evaluate(parameter),
        CurveGeometryKind.BSpline3 => curve.BSpline3!.Value.Evaluate(parameter),
        CurveGeometryKind.Ellipse3 => curve.Ellipse3!.Value.Evaluate(parameter),
        CurveGeometryKind.Hyperbola3 => curve.Hyperbola3!.Value.Evaluate(parameter),
        _ => throw new NotSupportedException($"Curve family {curve.Kind} is outside the qualified pcurve matrix.")
    };
    private static SurfaceParameterPoint PlaneUv(PlaneSurface plane, Point3D point)
    {
        var d = point - plane.Origin;
        return new(d.Dot(plane.UAxis.ToVector()), d.Dot(plane.VAxis.ToVector()));
    }
    private static SurfaceParameterPoint CylinderUv(CylinderSurface cylinder, Point3D point)
    {
        var d = point - cylinder.Origin;
        return new(double.Atan2(d.Dot(cylinder.YAxis.ToVector()), d.Dot(cylinder.XAxis.ToVector())), d.Dot(cylinder.Axis.ToVector()));
    }
    private static SurfaceParameterPoint ConeUv(ConeSurface cone, Point3D point)
    {
        var fromApex = point - cone.Apex;
        var axial = fromApex.Dot(cone.Axis.ToVector());
        var originRadial = cone.Evaluate(0d, 1d) - cone.Apex - cone.Axis.ToVector();
        var xAxis = Direction3D.Create(originRadial);
        var yAxis = Direction3D.Create(cone.Axis.ToVector().Cross(xAxis.ToVector()));
        return new(double.Atan2(fromApex.Dot(yAxis.ToVector()), fromApex.Dot(xAxis.ToVector())), axial);
    }
    private static SurfaceParameterPoint SphereUv(SphereSurface sphere, Point3D point)
    {
        var d = point - sphere.Center;
        var axial = d.Dot(sphere.Axis.ToVector());
        return new(double.Atan2(d.Dot(sphere.YAxis.ToVector()), d.Dot(sphere.XAxis.ToVector())),
            double.Atan2(axial, double.Sqrt(double.Max(0d, d.LengthSquared - axial * axial))));
    }
    private static SurfaceParameterPoint TorusUv(TorusSurface torus, Point3D point)
    {
        var d = point - torus.Center;
        var x = d.Dot(torus.XAxis.ToVector());
        var y = d.Dot(torus.YAxis.ToVector());
        var axial = d.Dot(torus.Axis.ToVector());
        return new(double.Atan2(y, x), double.Atan2(axial, double.Sqrt(x * x + y * y) - torus.MajorRadius));
    }
    // Recognize analytic isoparametric edges before the general inverse/fit path.
    // Geometry identities, rather than the import tolerance, establish this case.
    // Populate still independently validates the lifted curve over its full span.
    internal static PcurveGeometry? TryBuildIsoParametricPcurve(
        SurfaceGeometry surface, CurveGeometry curve, ParameterInterval interval)
    {
        const double angularRoundoff = 1e-12d;
        var span = interval.End - interval.Start;
        if (surface.Cylinder is { } cylinder)
        {
            var axis = cylinder.Axis.ToVector();
            var epsilon = 1e-12d * double.Max(1d, cylinder.Radius);
            if (curve.Line3 is { } generator
                && generator.Direction.ToVector().Cross(axis).Length <= angularRoundoff)
            {
                var offset = generator.Origin - cylinder.Origin;
                if (double.Abs((offset - axis * offset.Dot(axis)).Length - cylinder.Radius) > epsilon) return null;
                var start = CylinderUv(cylinder, generator.Evaluate(interval.Start));
                return PcurveGeometry.Line(interval, start,
                    new(start.U, start.V + span * generator.Direction.ToVector().Dot(axis)));
            }
            if (curve.Circle3 is { } ring && ring.Normal.ToVector().Cross(axis).Length <= angularRoundoff)
            {
                var offset = ring.Center - cylinder.Origin;
                if ((offset - axis * offset.Dot(axis)).Length > epsilon
                    || double.Abs(ring.Radius - cylinder.Radius) > epsilon) return null;
                var start = CylinderUv(cylinder, ring.Evaluate(interval.Start));
                return PcurveGeometry.Line(interval, start,
                    new(start.U + span * double.CopySign(1d, ring.Normal.ToVector().Dot(axis)), start.V));
            }
        }
        if (surface.Torus is { } torus && torus.MajorRadius > torus.MinorRadius && curve.Circle3 is { } circle)
        {
            var axis = torus.Axis.ToVector();
            var normal = circle.Normal.ToVector();
            var offset = circle.Center - torus.Center;
            var epsilon = 1e-12d * double.Max(1d, torus.MajorRadius + torus.MinorRadius);
            var start = TorusUv(torus, circle.Evaluate(interval.Start));
            if (normal.Cross(axis).Length <= angularRoundoff)
            {
                // Constant minor angle: a circle about the torus axis.
                if ((offset - axis * offset.Dot(axis)).Length > epsilon
                    || double.Abs(offset.Dot(axis) - torus.MinorRadius * double.Sin(start.V)) > epsilon
                    || double.Abs(circle.Radius - torus.MajorRadius - torus.MinorRadius * double.Cos(start.V)) > epsilon) return null;
                return PcurveGeometry.Line(interval, start,
                    new(start.U + span * double.CopySign(1d, normal.Dot(axis)), start.V));
            }
            if (double.Abs(normal.Dot(axis)) <= angularRoundoff
                && double.Abs(offset.Dot(axis)) <= epsilon
                && double.Abs(offset.Length - torus.MajorRadius) <= epsilon
                && double.Abs(normal.Dot(offset)) <= epsilon
                && double.Abs(circle.Radius - torus.MinorRadius) <= epsilon)
            {
                // Constant major angle: the generating circle in a radial plane.
                var radial = offset / torus.MajorRadius;
                var positiveTangent = radial * -double.Sin(start.V) + axis * double.Cos(start.V);
                var direction = circle.Tangent(interval.Start).Dot(positiveTangent);
                return PcurveGeometry.Line(interval, start,
                    new(start.U, start.V + span * double.CopySign(1d, direction)));
            }
        }
        return null;
    }

    private static (PcurveGeometry? Pcurve, double MaximumResidual, string? Diagnostic) BuildPeriodicAnalytic(
        SurfaceGeometry surface, CurveGeometry curve, ParameterInterval interval, double tolerance,
        Func<Point3D, SurfaceParameterPoint> inverse, bool unwrapV = false, Func<Point3D, bool>? singular = null)
    {
        var best = double.PositiveInfinity;
        for (var count = 17; count <= 513; count = (count - 1) * 2 + 1)
        {
            var uv = Sample(interval, count, t => inverse(EvaluateCurve(curve, t))).ToArray();
            // A sphere pole or cone apex has no U of its own (atan2 of zero returns noise). The pcurve's
            // U there is its limit along the curve: take it from the nearest regular sample.
            if (singular is not null)
            {
                var atSingular = Enumerable.Range(0, count).Select(i => singular(EvaluateCurve(curve, interval.Start + (interval.End - interval.Start) * i / (count - 1d)))).ToArray();
                if (atSingular.Any(x => x) && !atSingular.All(x => x))
                {
                    for (var i = 0; i < count; i++)
                    {
                        if (!atSingular[i]) continue;
                        var regular = Enumerable.Range(1, count).SelectMany(d => new[] { i - d, i + d }).First(j => j >= 0 && j < count && !atSingular[j]);
                        var limit = i == 0 || i == count - 1
                            ? inverse(EvaluateCurve(curve, interval.Start + (interval.End - interval.Start) * (i == 0 ? 1e-6 : 1 - 1e-6)))
                            : uv[regular];
                        uv[i] = uv[i] with { U = limit.U };
                    }
                }
            }
            UnwrapAngles(uv, unwrapV);
            var controls = new List<Point3D>((count - 1) * 3 + 1);
            var knots = new List<double>(count);
            var multiplicities = new List<int>(count);
            for (var index = 0; index < count - 1; index++)
            {
                var start = interval.Start + (interval.End - interval.Start) * index / (count - 1d);
                // The last knot is the interval end exactly; Start + (End - Start) * 1 can fall one ulp short,
                // which leaves the trim outside the curve's domain.
                var end = index == count - 2 ? interval.End : interval.Start + (interval.End - interval.Start) * (index + 1) / (count - 1d);
                var delta = (end - start) * 1e-4d;
                var nearStart = inverse(EvaluateCurve(curve, start + delta));
                var nearEnd = inverse(EvaluateCurve(curve, end - delta));
                var p0 = uv[index];
                var p3 = uv[index + 1];
                nearStart = nearStart with { U = UnwrapNear(nearStart.U, p0.U) };
                nearEnd = nearEnd with { U = UnwrapNear(nearEnd.U, p3.U) };
                if (unwrapV)
                {
                    nearStart = nearStart with { V = UnwrapNear(nearStart.V, p0.V) };
                    nearEnd = nearEnd with { V = UnwrapNear(nearEnd.V, p3.V) };
                }
                var scale = (end - start) / (3d * delta);
                var p1 = new SurfaceParameterPoint(p0.U + (nearStart.U - p0.U) * scale,
                    p0.V + (nearStart.V - p0.V) * scale);
                var p2 = new SurfaceParameterPoint(p3.U - (p3.U - nearEnd.U) * scale,
                    p3.V - (p3.V - nearEnd.V) * scale);
                if (index == 0)
                {
                    controls.Add(new Point3D(p0.U, p0.V, 0d));
                    knots.Add(start);
                    multiplicities.Add(4);
                }
                controls.Add(new Point3D(p1.U, p1.V, 0d));
                controls.Add(new Point3D(p2.U, p2.V, 0d));
                controls.Add(new Point3D(p3.U, p3.V, 0d));
                knots.Add(end);
                multiplicities.Add(index == count - 2 ? 4 : 3);
            }
            var polynomial = new BSpline3Curve(3, controls, multiplicities, knots,
                "UNSPECIFIED", false, false, "UNSPECIFIED");
            var candidate = PcurveGeometry.Polynomial(interval, polynomial);
            var residual = MaximumResidual(surface, curve, candidate, interval, (count - 1) * 4 + 1);
            best = double.Min(best, residual);
            if (residual <= tolerance) return (candidate, residual, null);
        }
        return (null, best, $"{surface.Kind} pcurve refinement could not meet {tolerance:R} mm (best sampled lift residual {best:R} mm).");
    }

    internal static double UnwrapNear(double value, double reference, double period = 2d * double.Pi)
    {
        while (value - reference > period / 2d) value -= period;
        while (value - reference < -period / 2d) value += period;
        return value;
    }
    private static void UnwrapAngles(SurfaceParameterPoint[] points, bool unwrapV)
    {
        for (var index = 1; index < points.Length; index++)
        {
            var u = points[index].U;
            while (u - points[index - 1].U > double.Pi) u -= 2d * double.Pi;
            while (u - points[index - 1].U < -double.Pi) u += 2d * double.Pi;
            points[index] = points[index] with { U = u,
                V = unwrapV ? UnwrapNear(points[index].V, points[index - 1].V) : points[index].V };
        }
    }
    private static IReadOnlyList<SurfaceParameterPoint> Sample(ParameterInterval interval, int count, Func<double, SurfaceParameterPoint> evaluator)
        => Enumerable.Range(0, count).Select(index => evaluator(interval.Start + ((interval.End - interval.Start) * index / (count - 1d)))).ToArray();

    private static double MaximumResidual(SurfaceGeometry surface, CurveGeometry curve, PcurveGeometry pcurve, ParameterInterval interval, int count)
    {
        var maximum = 0d;
        for (var index = 0; index < count; index++)
        {
            var parameter = interval.Start + ((interval.End - interval.Start) * index / (count - 1d));
            var uv = pcurve.Evaluate(parameter);
            var onSurface = surface.Kind switch
            {
                SurfaceGeometryKind.Plane => surface.Plane!.Value.Evaluate(uv.U, uv.V),
                SurfaceGeometryKind.Cylinder => surface.Cylinder!.Value.Evaluate(uv.U, uv.V),
                SurfaceGeometryKind.Cone => surface.Cone!.Value.Evaluate(uv.U, uv.V),
                SurfaceGeometryKind.Sphere => surface.Sphere!.Value.Evaluate(uv.U, uv.V),
                SurfaceGeometryKind.Torus => surface.Torus!.Value.Evaluate(uv.U, uv.V),
                SurfaceGeometryKind.BSplineSurfaceWithKnots => surface.BSplineSurfaceWithKnots!.Evaluate(uv.U, uv.V),
                _ => throw new InvalidOperationException()
            };
            maximum = double.Max(maximum, (onSurface - EvaluateCurve(curve, parameter)).Length);
        }
        return maximum;
    }
}