Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

9.3 KB
Raw Blame
using Aetheris.Kernel.Core.Math;

namespace Aetheris.Continuum.Reconstruction;

public enum PointTorusSignCapability
{
    SignedClosedOriented,
    UnsignedOnlyOpenSurface,
    UnsignedOnlyUnoriented,
    UnsignedOnlyMultiSheet
}

public enum PointTorusQualification
{
    Qualified,
    UnsignedOnly,
    OutsideValidityBand,
    InsufficientNeighborhood
}

public sealed record PointTorusProvenance(
    string Source,
    string ParameterProducer,
    string? ModelRevision,
    string? ModelHash,
    IReadOnlyDictionary<string, string>? Properties = null);

public sealed record PointTorusFieldSettings(
    int NeighborCount = 32,
    double ValidityBandMm = 5d,
    PointTorusSignCapability SignCapability = PointTorusSignCapability.SignedClosedOriented)
{
    public void Validate(int sampleCount)
    {
        if (NeighborCount < 1 || NeighborCount > sampleCount)
            throw new ArgumentOutOfRangeException(nameof(NeighborCount), "Neighbor count must be within the imported sample count.");
        if (!double.IsFinite(ValidityBandMm) || ValidityBandMm <= 0d)
            throw new ArgumentOutOfRangeException(nameof(ValidityBandMm), "Validity band must be finite and positive.");
    }
}

/// <summary>One precomputed local analytic torus. Learned fitting is deliberately outside this assembly.</summary>
public sealed record PointTorusSample(
    Point3D SourcePoint,
    Vector3D SourceNormal,
    Point3D Center,
    Vector3D Axis,
    double MajorRadius,
    double SignedMinorRadius);

public readonly record struct PointTorusEvaluation(
    double ValueMm,
    PointTorusQualification Qualification,
    bool IsSigned,
    int NeighborsUsed,
    double NearestSourceDistanceMm,
    string Reason);

/// <summary>
/// Source-derived approximate field using precomputed Points-as-Tori local parameters.
/// This is reconstruction/query evidence, never BRep, topology, or manufacturing authority.
/// </summary>
public sealed class PointTorusField
{
    private readonly PointTorusSample[] _samples;
    private readonly KdIndex _index;

    public PointTorusField(IEnumerable<PointTorusSample> samples, PointTorusFieldSettings settings, PointTorusProvenance provenance)
    {
        ArgumentNullException.ThrowIfNull(samples);
        ArgumentNullException.ThrowIfNull(settings);
        ArgumentNullException.ThrowIfNull(provenance);
        _samples = samples.ToArray();
        if (_samples.Length == 0) throw new ArgumentException("At least one local torus is required.", nameof(samples));
        settings.Validate(_samples.Length);
        for (var i = 0; i < _samples.Length; i++) Validate(_samples[i], i);
        Settings = settings;
        Provenance = provenance;
        _index = new KdIndex(_samples.Select(static s => s.SourcePoint).ToArray());
    }

    public IReadOnlyList<PointTorusSample> Samples => _samples;
    public PointTorusFieldSettings Settings { get; }
    public PointTorusProvenance Provenance { get; }
    public string Acceleration => "deterministic-kd-tree";

    public PointTorusEvaluation Evaluate(Point3D query)
    {
        var neighbors = _index.Nearest(query, Settings.NeighborCount);
        if (neighbors.Length == 0)
            return new(double.NaN, PointTorusQualification.InsufficientNeighborhood, false, 0, double.PositiveInfinity, "No local torus was available.");

        var maxDistance = Math.Sqrt(neighbors[^1].DistanceSquared);
        var nearest = Math.Sqrt(neighbors[0].DistanceSquared);
        var shift = 0.5d * maxDistance;
        var weighted = 0d;
        var weightSum = 0d;
        var signed = Settings.SignCapability == PointTorusSignCapability.SignedClosedOriented;
        foreach (var neighbor in neighbors)
        {
            var distance = Math.Sqrt(neighbor.DistanceSquared);
            var weight = shift <= 1e-15 ? 1d : Math.Exp((-64d / shift) * (distance - shift));
            var local = EvaluateTorus(_samples[neighbor.Index], query);
            weighted += weight * (signed ? local : Math.Abs(local));
            weightSum += weight;
        }

        var value = weighted / weightSum;
        if (nearest > Settings.ValidityBandMm)
            return new(value, PointTorusQualification.OutsideValidityBand, signed, neighbors.Length, nearest,
                $"Nearest source sample is {nearest:G6} mm away, outside the {Settings.ValidityBandMm:G6} mm validity band." +
                (signed ? string.Empty : $" {SignReason(Settings.SignCapability)}"));
        if (!signed)
            return new(value, PointTorusQualification.UnsignedOnly, false, neighbors.Length, nearest, SignReason(Settings.SignCapability));
        return new(value, PointTorusQualification.Qualified, true, neighbors.Length, nearest, "Closed, globally oriented source within the declared validity band.");
    }

    public PointTorusEvaluation[] EvaluateBatch(IEnumerable<Point3D> queries)
    {
        ArgumentNullException.ThrowIfNull(queries);
        return queries.Select(Evaluate).ToArray();
    }

    public static double EvaluateTorus(PointTorusSample torus, Point3D query)
    {
        var delta = query - torus.Center;
        var axis = torus.Axis;
        var axial = delta.Dot(axis);
        var radial = delta.Cross(axis).Length;
        var tubeDistance = Math.Sqrt(((radial - torus.MajorRadius) * (radial - torus.MajorRadius)) + (axial * axial));
        return Math.Sign(torus.SignedMinorRadius) * (tubeDistance - Math.Abs(torus.SignedMinorRadius));
    }

    private static void Validate(PointTorusSample sample, int index)
    {
        static bool FinitePoint(Point3D p) => double.IsFinite(p.X) && double.IsFinite(p.Y) && double.IsFinite(p.Z);
        static bool FiniteVector(Vector3D v) => double.IsFinite(v.X) && double.IsFinite(v.Y) && double.IsFinite(v.Z);
        if (!FinitePoint(sample.SourcePoint) || !FiniteVector(sample.SourceNormal) || !FinitePoint(sample.Center) || !FiniteVector(sample.Axis) ||
            !double.IsFinite(sample.MajorRadius) || !double.IsFinite(sample.SignedMinorRadius))
            throw new ArgumentException($"Local torus {index} contains a non-finite value.");
        if (Math.Abs(sample.Axis.Length - 1d) > 1e-8)
            throw new ArgumentException($"Local torus {index} axis must be unit length.");
        if (sample.MajorRadius < 0d || Math.Abs(sample.SignedMinorRadius) <= 1e-15)
            throw new ArgumentException($"Local torus {index} radii are invalid.");
    }

    private static string SignReason(PointTorusSignCapability capability) => capability switch
    {
        PointTorusSignCapability.UnsignedOnlyOpenSurface => "Open source surfaces do not define authoritative inside/outside.",
        PointTorusSignCapability.UnsignedOnlyUnoriented => "Globally consistent oriented normals are required for sign.",
        PointTorusSignCapability.UnsignedOnlyMultiSheet => "Thin or locally multi-sheet neighborhoods are restricted to unsigned residuals.",
        _ => "Sign is not qualified."
    };

    private readonly record struct Neighbor(int Index, double DistanceSquared);

    private sealed class KdIndex
    {
        private readonly Point3D[] _points;
        private readonly Node? _root;

        public KdIndex(Point3D[] points)
        {
            _points = points;
            _root = Build(Enumerable.Range(0, points.Length).ToArray(), 0);
        }

        public Neighbor[] Nearest(Point3D query, int count)
        {
            var heap = new PriorityQueue<Neighbor, double>();
            Search(_root, query, count, heap);
            return heap.UnorderedItems.Select(static x => x.Element).OrderBy(static x => x.DistanceSquared).ThenBy(static x => x.Index).ToArray();
        }

        private Node? Build(int[] indices, int depth)
        {
            if (indices.Length == 0) return null;
            var axis = depth % 3;
            Array.Sort(indices, (a, b) => Coordinate(_points[a], axis).CompareTo(Coordinate(_points[b], axis)) is var c && c != 0 ? c : a.CompareTo(b));
            var middle = indices.Length / 2;
            return new(indices[middle], axis,
                Build(indices[..middle], depth + 1),
                Build(indices[(middle + 1)..], depth + 1));
        }

        private void Search(Node? node, Point3D query, int count, PriorityQueue<Neighbor, double> heap)
        {
            if (node is null) return;
            var point = _points[node.Index];
            var d = query - point;
            var distanceSquared = d.LengthSquared;
            if (heap.Count < count) heap.Enqueue(new(node.Index, distanceSquared), -distanceSquared);
            else if (heap.TryPeek(out _, out var worstPriority) && distanceSquared < -worstPriority)
            {
                heap.Dequeue();
                heap.Enqueue(new(node.Index, distanceSquared), -distanceSquared);
            }

            var delta = Coordinate(query, node.Axis) - Coordinate(point, node.Axis);
            var near = delta <= 0d ? node.Left : node.Right;
            var far = delta <= 0d ? node.Right : node.Left;
            Search(near, query, count, heap);
            var worst = heap.Count < count || !heap.TryPeek(out _, out var p) ? double.PositiveInfinity : -p;
            if ((delta * delta) <= worst) Search(far, query, count, heap);
        }

        private static double Coordinate(Point3D p, int axis) => axis == 0 ? p.X : axis == 1 ? p.Y : p.Z;
        private sealed record Node(int Index, int Axis, Node? Left, Node? Right);
    }
}