Editor/Core/Hands/HandPose.cs

Editor-side hand pose data for the weapon importer. Stores wrist transform, per-finger joint flexion, spread and thumb opposition, converts them to local bone rotations, clones and linearly blends poses.

#nullable enable annotations

using System.Numerics;
using WeaponImporter.EditorTools.Core.Maths;

namespace WeaponImporter.EditorTools.Core.Hands;

using Vector3 = System.Numerics.Vector3;

/// <summary>
/// A hand pose: wrist transform plus per-joint flexion (and base spread) angles. Stored as
/// angles so blending, limits and "smallest change" comparisons stay meaningful; converted to
/// bone rotations with <see cref="LocalRotation"/>.
/// </summary>
public sealed class HandPose
{
    /// <summary>Hand bone transform in the space the pose was solved in (weapon space for grips).</summary>
    public XForm Wrist;

    /// <summary>Flexion per finger joint (radians), keyed by finger then joint index.</summary>
    public Dictionary<FingerKind, float[]> Flex { get; } = new();

    /// <summary>Base-joint spread per finger (radians, + toward the thumb).</summary>
    public Dictionary<FingerKind, float> Spread { get; } = new();

    /// <summary>Thumb opposition (radians): swings the thumb across the palm.</summary>
    public float ThumbOpposition;

    public HandPose(XForm wrist) => Wrist = wrist;

    public static HandPose Open(HandRig rig, XForm wrist)
    {
        var pose = new HandPose(wrist);
        foreach (var f in rig.Fingers)
        {
            pose.Flex[f.Kind] = new float[f.Joints.Length];
            pose.Spread[f.Kind] = 0f;
        }
        return pose;
    }

    public HandPose Clone()
    {
        var c = new HandPose(Wrist) { ThumbOpposition = ThumbOpposition };
        foreach (var (k, v) in Flex)
            c.Flex[k] = v.ToArray();
        foreach (var (k, v) in Spread)
            c.Spread[k] = v;
        return c;
    }

    public float[] FlexOf(FingerKind kind) => Flex.TryGetValue(kind, out var f) ? f : Array.Empty<float>();

    /// <summary>Local rotation of finger joint <paramref name="j"/> for this pose.</summary>
    public Quaternion LocalRotation(HandRig rig, FingerRig finger, int j)
    {
        var rest = rig.Skeleton[finger.Joints[j]].RestLocal.Rot;
        // What the character shows: a pinky its model copies from the ring takes the ring's angles.
        var kind = rig.PinkyFollowsRing && finger.Kind == FingerKind.Pinky && Flex.ContainsKey(FingerKind.Ring) ? FingerKind.Ring : finger.Kind;
        var flex = Flex.TryGetValue(kind, out var f) && j < f.Length ? f[j] : 0f;
        var q = Quaternion.CreateFromAxisAngle(finger.FlexAxes[j], flex);
        if (j == 0)
        {
            var spread = Spread.TryGetValue(kind, out var sp) ? sp : 0f;
            if (MathF.Abs(spread) > 1e-5f)
                q = Quaternion.CreateFromAxisAngle(finger.SpreadAxis, spread) * q;
            if (finger.Kind == FingerKind.Thumb && MathF.Abs(ThumbOpposition) > 1e-5f)
            {
                // Opposition rolls the thumb about its own length while swinging it across the palm.
                q = Quaternion.CreateFromAxisAngle(finger.Along[0], ThumbOpposition * 0.6f) * Quaternion.CreateFromAxisAngle(finger.SpreadAxis, -ThumbOpposition * (rig.Side == Side.Right ? 1f : -1f) * 0.5f) * q;
            }
        }
        return MathQ.Normalize(rest * q);
    }

    /// <summary>Linear blend between two poses (angles and wrist).</summary>
    public static HandPose Lerp(HandPose a, HandPose b, float t)
    {
        var r = new HandPose(new XForm(Vector3.Lerp(a.Wrist.Pos, b.Wrist.Pos, t), MathQ.Slerp(a.Wrist.Rot, b.Wrist.Rot, t)))
        {
            ThumbOpposition = a.ThumbOpposition + (b.ThumbOpposition - a.ThumbOpposition) * t,
        };
        foreach (var (k, fa) in a.Flex)
        {
            var fb = b.Flex.TryGetValue(k, out var x) ? x : fa;
            r.Flex[k] = fa.Select((v, i) => v + ((i < fb.Length ? fb[i] : v) - v) * t).ToArray();
        }
        foreach (var (k, sa) in a.Spread)
            r.Spread[k] = sa + ((b.Spread.TryGetValue(k, out var sb) ? sb : sa) - sa) * t;
        return r;
    }
}