feat(hand-pose): drive dynamic finger curl from touch and analog axis

Touching a finger's tracked control curls it to a baseline, then the
analog axis (trigger for the index, grip for the bottom three fingers)
drives the remaining curl up to a full fist. The thumb has no curl-depth
axis, so it curls to a fixed pose and splays its proximal joint toward
whichever face control it rests on (thumbstick, A, or B).

Add a pointing gesture (index off the trigger, grip held, thumb on A/B)
as an implicit authored pose, and exclude A/B from the thumbs-up gesture
so the two no longer overlap.

Author: ArthurHub

src/skeleton/HandPose.cpp

@@ -1,6 +1,7 @@
 #include "HandPose.h"
 
 #include <algorithm>
+#include <optional>
 #include <string>
 #include <string_view>
 
@@ -51,18 +52,57 @@ namespace
     }
 
     /**
-     * Map a finger to the controller input that should drive its dynamic curl.
+     * Map a (non-thumb) finger to the controller button that should drive its dynamic curl.
+     * The index finger follows the trigger; the bottom three fingers (middle, ring, pinky) follow the grip.
      */
     VRButtonId getTrackedButton(const std::string& bone)
     {
-        switch (boneToFingerIndex(bone)) {
-        case 0:
-            return k_EButton_SteamVR_Touchpad;
-        case 1:
-            return k_EButton_SteamVR_Trigger;
+        return boneToFingerIndex(bone) == 1 ? k_EButton_SteamVR_Trigger : k_EButton_Grip;
+    }
+
+    /**
+     * Map a tracked finger button to its analog curl-depth axis, when the controller exposes one.
+     * Touch-only inputs (face buttons, thumbstick) report no axis.
+     */
+    std::optional<Axis> getTrackedButtonAxis(const VRButtonId button)
+    {
+        switch (button) { // NOLINT(clang-diagnostic-switch-enum)
+        case k_EButton_SteamVR_Trigger:
+            return Axis::Trigger;
+        case k_EButton_Grip:
+            return Axis::Grip;
         default:
-            return k_EButton_Grip;
+            return std::nullopt;
+        }
+    }
+
+    struct DynamicThumbCurl
+    {
+        float curl; // 0 = open, 1 = fully closed
+        float splay; // proximal lateral splay, right-hand convention
+    };
+
+    /**
+     * Resolve the thumb's dynamic curl and proximal splay from the face control it rests on.
+     *
+     * The thumb has no usable curl-depth axis, so touching any of its controls curls it to a fixed
+     * mid pose while the touched control selects a distinct splay, shifting the thumb tip toward the
+     * thumbstick, A, or B button. Returns a neutral open thumb when nothing is touched. The A and B
+     * buttons are checked before the thumbstick so a deliberate button reach wins over the resting
+     * thumbstick contact.
+     */
+    DynamicThumbCurl resolveDynamicThumbCurl(const Hand hand)
+    {
+        if (VRControllers.isTouching(hand, k_EButton_A)) {
+            return { .curl = 0.7f, .splay = 0.2f };
+        }
+        if (VRControllers.isTouching(hand, k_EButton_ApplicationMenu)) {
+            return { .curl = 0.2f, .splay = 0.1f };
         }
+        if (VRControllers.isTouching(hand, k_EButton_SteamVR_Touchpad)) {
+            return { .curl = 0.4f, .splay = 0.3f };
+        }
+        return { .curl = 0.0f, .splay = 0.0f };
     }
 
     /**
@@ -374,6 +414,11 @@ namespace frik
             return HandPoseSource{ .kind = HandPoseSourceKind::OverridePose, .pose = &activeOverride->pose };
         }
 
+        if (shouldUsePointingPose(isLeft)) {
+            // Pointing is treated as an implicit authored override.
+            return HandPoseSource{ .kind = HandPoseSourceKind::OverridePose, .pose = &getPointingPose() };
+        }
+
         if (shouldUseThumbsUpPose(isLeft)) {
             // Thumbs-up is treated as an implicit authored override.
             return HandPoseSource{ .kind = HandPoseSourceKind::OverridePose, .pose = &getThumbsUpPose() };
@@ -452,21 +497,37 @@ namespace frik
 
     /**
      * Apply hand pose by what controller buttons are touched/pressed.
+     *
+     * Touching a finger's tracked control curls it to a baseline; if that control exposes an analog
+     * axis (trigger, grip) the axis drives the remaining curl up to a full fist, otherwise the curl
+     * rests at that fixed touch baseline. The thumb has no curl-depth axis, so it instead reads which face
+     * control it rests on (thumbstick, A, or B) and splays its proximal joint toward that control.
      */
     void HandPose::applyDynamicHandPose(const std::string& boneName, const float frameTime)
     {
-        float flex = 1.0F; // open
         const auto boneHand = isLeftHandBone(boneName) ? Hand::Left : Hand::Right;
-        const auto controllerButtonForBone = getTrackedButton(boneName);
-        if (controllerButtonForBone == k_EButton_Grip) {
-            flex = 1.0f - VRControllers.getAxisValue(boneHand, Axis::Grip).x;
-        } else if (controllerButtonForBone == k_EButton_SteamVR_Trigger) {
-            flex = 1.0f - 2 * VRControllers.getAxisValue(boneHand, Axis::Trigger).x;
-        } else if (VRControllers.isTouching(boneHand, controllerButtonForBone)) {
-            flex = 0.0F;
+
+        float curl = 0.0f; // 0 = open, 1 = fully closed
+        float splay = 0.0f;
+        if (boneToFingerIndex(boneName) == 0) {
+            const auto thumb = resolveDynamicThumbCurl(boneHand);
+            curl = thumb.curl;
+            splay = boneName.back() == '1' ? thumb.splay : 0.0f;
+        } else {
+            constexpr float DYNAMIC_CURL_ON_TOUCH = 0.35f;
+            const auto button = getTrackedButton(boneName);
+            const auto axis = getTrackedButtonAxis(button);
+            const float axisVal = axis ? VRControllers.getAxisValue(boneHand, *axis).x : 0.0f;
+            if (axisVal > 0.1f) {
+                // Past the deadzone the analog axis drives curl from the touch baseline up to a full fist.
+                curl = DYNAMIC_CURL_ON_TOUCH + (1.0f - DYNAMIC_CURL_ON_TOUCH) * std::clamp(axisVal, 0.0f, 1.0f);
+            } else if (axisVal > 0.001f || VRControllers.isTouching(boneHand, button)) {
+                // Resting on or lightly holding the control curls to the baseline only.
+                curl = DYNAMIC_CURL_ON_TOUCH;
+            }
         }
 
-        blendBoneTowardRotation(boneName, blendBoneRotation(boneName, fmax(0.0f, fmin(1.0f, flex)), 0), frameTime);
+        blendBoneTowardRotation(boneName, blendBoneRotation(boneName, 1.0f - curl, splay), frameTime);
     }
 
     /**
@@ -528,14 +589,27 @@ namespace frik
         return overrides.empty() ? nullptr : &overrides.back();
     }
 
+    /**
+     * Detect the controller gesture that should temporarily map to pointing:
+     * the index lifted off the trigger, the grip held, and the thumb resting on a face button (A or B).
+     */
+    bool HandPose::shouldUsePointingPose(const bool isLeft)
+    {
+        const auto hand = isLeft ? Hand::Left : Hand::Right;
+        return !VRControllers.isTouching(hand, vr::k_EButton_SteamVR_Trigger) &&
+            (VRControllers.getAxisValue(hand, Axis::Grip).x > 0.01f || VRControllers.isTouching(hand, k_EButton_Grip)) &&
+            (VRControllers.isTouching(hand, vr::k_EButton_A) || VRControllers.isTouching(hand, vr::k_EButton_ApplicationMenu));
+    }
+
     /**
      * Detect the controller gesture that should temporarily map to thumbs-up.
      */
     bool HandPose::shouldUseThumbsUpPose(const bool isLeft)
     {
         const auto hand = isLeft ? Hand::Left : Hand::Right;
         return VRControllers.isTouching(hand, k_EButton_Grip) && VRControllers.isTouching(hand, vr::k_EButton_SteamVR_Trigger) &&
-            !VRControllers.isTouching(hand, vr::k_EButton_SteamVR_Touchpad);
+            !VRControllers.isTouching(hand, vr::k_EButton_SteamVR_Touchpad) && !VRControllers.isTouching(hand, vr::k_EButton_A) &&
+            !VRControllers.isTouching(hand, vr::k_EButton_ApplicationMenu);
     }
 
     /**

src/skeleton/HandPose.h

@@ -69,6 +69,7 @@ namespace frik
         void blendBoneTowardRotation(const std::string& boneName, const RE::NiMatrix3& targetRotation, float frameTime);
         RE::NiMatrix3 getPoseBoneRotation(const std::string& boneName, const HandFingersPose& pose) const;
         RE::NiMatrix3 blendBoneRotation(const std::string& boneName, float flex, float splay) const;
+        static bool shouldUsePointingPose(bool isLeft);
         static bool shouldUseThumbsUpPose(bool isLeft);
         static void setHandPoseOverrideIntr(bool isLeft, std::string_view tag, const HandFingersPose& pose, bool forceTop);
         static void clearHandPoseOverrideIntr(bool isLeft, std::string_view tag);