Core: Anim Utils: Fix IK/FK match for 3jnt leg and roll control fixes #626

Generalize match_fk_to_ik_scale_slide, place_upv_from_fk, and
match_fk_to_ik_arbitrary_lengths to support chains with 3+ FK
controls instead of hardcoded 3-way unpacking. Fixes ValueError
on leg_3jnt_01 components which have 4 FK controls.

Fix roll_ctl matching: use match_ref connection to snap to roll_mth
when available (leg_3jnt_01), fall back to rotateX reset when no
match reference exists (arm components).

Author: miquelcampos

release/scripts/mgear/core/anim_utils.py

@@ -957,28 +957,52 @@ def _get_mth(name):
 
     # if is IK then snap FK
     if val == ik_val:
-
         for target, ctl in zip(fk_targets, fk_ctrls):
             transform.matchWorldTransform(target, ctl)
         pm.setAttr(o_attr, fk_val)
 
     # if is FK then snap IK
     elif val == fk_val:
-        transform.matchWorldTransform(ik_targets["ik_control"], ik_ctrl["ik_control"])
-        transform.matchWorldTransform(ik_targets["pole_vector"], ik_ctrl["pole_vector"])
+        transform.matchWorldTransform(
+            ik_targets["ik_control"], ik_ctrl["ik_control"]
+        )
+        transform.matchWorldTransform(
+            ik_targets["pole_vector"], ik_ctrl["pole_vector"]
+        )
+
         try:
-            transform.matchWorldTransform(ik_targets["toes_ik"], ik_ctrl["toes_ik"])
-            transform.matchWorldTransform(ik_targets["toeRollIk"], ik_ctrl["toeRollIk"])
-            transform.matchWorldTransform(ik_targets["heelIk"], ik_ctrl["heelIk"])
             transform.matchWorldTransform(
-                ik_targets["reverse_ankle_ik"], ik_ctrl["reverse_ankle_ik"]
+                ik_targets["toes_ik"], ik_ctrl["toes_ik"]
+            )
+            transform.matchWorldTransform(
+                ik_targets["toeRollIk"], ik_ctrl["toeRollIk"]
+            )
+            transform.matchWorldTransform(
+                ik_targets["heelIk"], ik_ctrl["heelIk"]
+            )
+            transform.matchWorldTransform(
+                ik_targets["reverse_ankle_ik"],
+                ik_ctrl["reverse_ankle_ik"],
+            )
+            match_fk_to_ik_arbitrary_lengths(
+                fk_controls, ui_node, ikfk_attr,
+                ik_ctrl["pole_vector"],
             )
-            match_fk_to_ik_arbitrary_lengths(fk_controls, ui_node,
-                                             ikfk_attr, ik_ctrl["pole_vector"])
         except KeyError:
             pass
+
+        # Set the blend attr to IK BEFORE matching roll, because
+        # the rig needs to evaluate in IK mode first so the roll
+        # control's parent hierarchy is in its final state.
         pm.setAttr(o_attr, ik_val)
 
+        # Match roll control after blend switch
+        if "roll" in ik_ctrl and ik_ctrl["roll"] is not None:
+            if "roll" in ik_targets and ik_targets["roll"] is not None:
+                transform.matchWorldTransform(
+                    ik_targets["roll"], ik_ctrl["roll"]
+                )
+
     # sets keyframes
     if keyframe:
         [
@@ -1234,10 +1258,20 @@ def _get_mth(name):
             roll_att = ik_ctrl.attr(roll_att_name)
         roll_att.set(0.0)
 
-        # reset roll ctl if exist
+        # match roll ctl to its reference if it exists,
+        # otherwise reset rotateX (arm components have no roll_mth)
         if ik_controls and "roll" in ik_controls.keys():
-            roll_ctl = _get_node(ik_controls["roll"])
-            roll_ctl.rotateX.set(0)
+            roll_ctl_node = _get_node(ik_controls["roll"])
+            if roll_ctl_node.hasAttr("match_ref"):
+                match_nodes = roll_ctl_node.match_ref.listConnections()
+                if match_nodes:
+                    transform.matchWorldTransform(
+                        match_nodes[0], roll_ctl_node
+                    )
+                else:
+                    roll_ctl_node.rotateX.set(0)
+            else:
+                roll_ctl_node.rotateX.set(0)
 
         # reset IK foot ctls
         if foot_cnx:
@@ -2614,99 +2648,86 @@ def bakeAnimation(
 
 # Functions to support arbitraty limb length for FK to IK
 
-def match_fk_to_ik_scale_slide(arm_ctl, forearm_ctl, hand_ctl,
-                               ui_host, scale_attr='scale',
-                               slide_attr='slide'):
+def match_fk_to_ik_scale_slide(fk_controls, ui_host,
+                               scale_attr="scale",
+                               slide_attr="slide"):
     """Match FK limb to IK using scale and slide on a uiHost node.
 
+    Supports chains with 2 or more segments (3+ FK controls).
+
     Args:
-        arm_ctl (str): Arm or upper leg FK control.
-        forearm_ctl (str): Forearm or lower leg FK control.
-        hand_ctl (str): Hand or foot FK control.
+        fk_controls (list): FK control names in chain order.
         ui_host (str): Node where scale/slide attrs live.
         scale_attr (str): Name of scale attribute.
         slide_attr (str): Name of slide attribute.
 
     Raises:
-        RuntimeError: On missing nodes or zero‐length setup.
+        RuntimeError: On missing nodes or zero-length setup.
     """
-    # get default max values and rest values
     s_path = "{}.{}".format(ui_host, scale_attr)
     sl_path = "{}.{}".format(ui_host, slide_attr)
     s_path_info = attribute.get_attr_info(ui_host, scale_attr)
     sl_path_info = attribute.get_attr_info(ui_host, slide_attr)
     s_default_val = s_path_info["default"]
-    s_min_val = s_path_info["min"]
-    s_max_val = s_path_info["max"]
-
-    sl_default_val = sl_path_info["default"]
     sl_min_val = sl_path_info["min"]
     sl_max_val = sl_path_info["max"]
 
-    # verify controls & parents
     def parent_of(obj):
-        p = cmds.listRelatives(obj, parent=True, f=True)
+        p = cmds.listRelatives(obj, parent=True, fullPath=True)
         if not p:
             raise RuntimeError("No parent for {}".format(obj))
         return p[0]
 
-    for ctl in (arm_ctl, forearm_ctl, hand_ctl):
+    for ctl in fk_controls:
         if not cmds.objExists(ctl):
             raise RuntimeError("Control not found: {}".format(ctl))
 
-    # arm_p = parent_of(arm_ctl)
-    # arm_p_p = parent_of(arm_p)
-    fore_p = parent_of(forearm_ctl)
-    fore_p_p = parent_of(fore_p)
-    hand_p = parent_of(hand_ctl)
-    hand_p_p = parent_of(hand_p)
-
-    # rest lengths
-    rest_upper = vector.getDistance2(fore_p_p, fore_p)
-    rest_lower = vector.getDistance2(hand_p_p, hand_p)
-    # rest_lower = 2.0
-    rest_total = rest_upper + rest_lower
-    # print("Rest lengths: upper={:.3f}, lower={:.3f}, total={:.3f}"
-    #       .format(rest_upper, rest_lower, rest_total))
+    # Rest lengths from parent hierarchy for each segment
+    rest_segments = []
+    for ctl in fk_controls[1:]:
+        ctl_p = parent_of(ctl)
+        ctl_pp = parent_of(ctl_p)
+        rest_segments.append(vector.getDistance2(ctl_pp, ctl_p))
+    rest_total = sum(rest_segments)
 
     if rest_total == 0:
         raise RuntimeError("Rest pose total length is zero.")
 
-    # current lengths
-    cur_upper = vector.getDistance2(arm_ctl, forearm_ctl)
-    cur_lower = vector.getDistance2(forearm_ctl, hand_ctl)
-    cur_total = cur_upper + cur_lower
-    # print("Cur lengths:  upper={:.3f}, lower={:.3f}, total={:.3f}"
-    #       .format(cur_upper, cur_lower, cur_total))
+    # Current lengths between consecutive FK controls
+    cur_segments = []
+    for i in range(len(fk_controls) - 1):
+        cur_segments.append(
+            vector.getDistance2(fk_controls[i], fk_controls[i + 1])
+        )
+    cur_total = sum(cur_segments)
 
-    # scale
+    # Scale
     scale_val = cur_total / rest_total
-    # print("Scale value: {:.3f}".format(scale_val))
 
-    # slide: piecewise around rest ratio
+    # Slide: ratio of upper portion vs total
+    mid_idx = len(fk_controls) // 2
+    rest_upper = sum(rest_segments[:mid_idx])
+    cur_upper = sum(cur_segments[:mid_idx])
     rest_ratio = rest_upper / rest_total
-    cur_ratio = cur_upper / cur_total
-    # print("Ratios: rest_ratio={:.3f}, cur_ratio={:.3f}"
-    #       .format(rest_ratio, cur_ratio))
+    cur_ratio = cur_upper / cur_total if cur_total > 0 else rest_ratio
 
     if cur_ratio <= rest_ratio:
         slide_val = (cur_ratio / rest_ratio) * 0.5
     else:
-        slide_val = 0.5 + ((cur_ratio - rest_ratio) / (1 - rest_ratio)) \
-            * 0.5
+        slide_val = (
+            0.5
+            + ((cur_ratio - rest_ratio) / (1 - rest_ratio)) * 0.5
+        )
 
     slide_val = max(0.0, min(1.0, slide_val))
-    # print("Slide value: {:.3f}".format(slide_val))
 
-    # map normalized values to attribute ranges
+    # Map normalized values to attribute ranges
     if s_default_val is not None:
         scale_val = scale_val * s_default_val
 
     if sl_min_val is not None and sl_max_val is not None:
         slide_val = (sl_max_val - sl_min_val) * slide_val + sl_min_val
 
-    # set attrs
-
     for p in (s_path, sl_path):
         if not cmds.objExists(p):
             raise RuntimeError("Missing attribute: {}".format(p))
@@ -2716,33 +2737,35 @@ def parent_of(obj):
 
 
 
-def place_upv_from_fk(arm_ctl, forearm_ctl, hand_ctl,
-                      upv_ctl, distance_multiplier=2.0):
+def place_upv_from_fk(fk_controls, upv_ctl, distance_multiplier=2.0):
     """Place up vector control based on the FK plane.
 
-    Calculates the pole vector (up vector) position defined by the FK
-    controls and places the upv_ctl at that position.
+    Uses the first, middle, and last FK controls to define the limb
+    plane and places the pole vector perpendicular to it.
+    Supports chains with 3 or more FK controls.
 
     Args:
-        arm_ctl (str): Arm or upper leg FK control.
-        forearm_ctl (str): Forearm or lower leg FK control.
-        hand_ctl (str): Hand or foot FK control.
+        fk_controls (list): FK control names in chain order.
         upv_ctl (str): Up vector control to be moved.
         distance_multiplier (float): Distance scale factor.
 
     Raises:
         RuntimeError: If any control does not exist.
     """
-    for ctl in [arm_ctl, forearm_ctl, hand_ctl, upv_ctl]:
+    for ctl in list(fk_controls) + [upv_ctl]:
         if not cmds.objExists(ctl):
             raise RuntimeError("Control not found: {}".format(ctl))
 
-    v1 = vector.get_mvector(arm_ctl)
-    v2 = vector.get_mvector(forearm_ctl)
-    v3 = vector.get_mvector(hand_ctl)
+    first = fk_controls[0]
+    mid = fk_controls[len(fk_controls) // 2]
+    last = fk_controls[-1]
 
-    a = v2 - v1  # vector from arm to elbow
-    b = v3 - v1  # vector from arm to wrist
+    v1 = vector.get_mvector(first)
+    v2 = vector.get_mvector(mid)
+    v3 = vector.get_mvector(last)
+
+    a = v2 - v1
+    b = v3 - v1
 
     b_normalized = b.normal()
     proj = a * b_normalized
@@ -2761,23 +2784,26 @@ def match_fk_to_ik_arbitrary_lengths(fk_controls, ui_host,
                                      blend_attr, upv_ctl):
     """Match FK to IK for arbitrary limb lengths.
 
+    Supports chains with 3 or more FK controls (2jnt, 3jnt, etc.).
+
     Args:
-        fk_controls (list[str or PyNode]): [arm_ctl, forearm_ctl, hand_ctl].
+        fk_controls (list): FK controls as strings or PyNodes.
         ui_host (str or PyNode): Node with blend attr.
         blend_attr (str): Name of blend or switch attr.
         upv_ctl (str or PyNode): Up-vector control.
 
     Returns:
         bool: True if match ran, False if attrs missing.
     """
-    arm_str, fore_str, hand_str = [], [], []
     names = []
     for c in fk_controls:
         if not isinstance(c, str):
             names.append(c.name())
         else:
             names.append(c)
-    arm_str, fore_str, hand_str = names
+
+    if len(names) < 3:
+        return False
 
     if not isinstance(ui_host, str):
         ui_node = ui_host
@@ -2791,45 +2817,46 @@ def match_fk_to_ik_arbitrary_lengths(fk_controls, ui_host,
     else:
         upv_str = upv_ctl
 
-    # Derive scale/slide attr names
-    if blend_attr.endswith('_blend'):
+    if blend_attr.endswith("_blend"):
         base = blend_attr[:-6]
-    elif blend_attr.endswith('_Switch'):
+    elif blend_attr.endswith("_Switch"):
         base = blend_attr[:-7]
     else:
         base = blend_attr
-    scale_attr = base + '_ikscale'
-    slide_attr = base + '_slide'
+    scale_attr = base + "_ikscale"
+    slide_attr = base + "_slide"
 
-    # Check required attrs on PyNode
     if not ui_node.hasAttr(scale_attr) or not ui_node.hasAttr(
-            slide_attr):
+        slide_attr
+    ):
         return False
 
-    keyframe = pm.keyframe(f"{ui_str}.{blend_attr}",
-                           query=True,
-                           keyframeCount=True)
-
-    # if keyframe:
-    #     cmds.setKeyframe(f"{ui_str}.{scale_attr}", time=(cmds.currentTime(query=True) - 1.0))
-    #     cmds.setKeyframe(f"{ui_str}.{slide_attr}", time=(cmds.currentTime(query=True) - 1.0))
+    keyframe = pm.keyframe(
+        "{}.{}".format(ui_str, blend_attr),
+        query=True,
+        keyframeCount=True,
+    )
 
-    # Run FK to IK match
     match_fk_to_ik_scale_slide(
-        arm_ctl=arm_str, forearm_ctl=fore_str,
-        hand_ctl=hand_str, ui_host=ui_str,
-        scale_attr=scale_attr, slide_attr=slide_attr
+        fk_controls=names,
+        ui_host=ui_str,
+        scale_attr=scale_attr,
+        slide_attr=slide_attr,
     )
 
-    # Place up-vector
     place_upv_from_fk(
-        arm_ctl=arm_str, forearm_ctl=fore_str,
-        hand_ctl=hand_str, upv_ctl=upv_str,
-        distance_multiplier=1.0
+        fk_controls=names,
+        upv_ctl=upv_str,
+        distance_multiplier=1.0,
     )
 
     if keyframe:
-        cmds.setKeyframe(f"{ui_str}.{scale_attr}", time=(cmds.currentTime(query=True)))
-        cmds.setKeyframe(f"{ui_str}.{slide_attr}", time=(cmds.currentTime(query=True)))
+        cur_time = cmds.currentTime(query=True)
+        cmds.setKeyframe(
+            "{}.{}".format(ui_str, scale_attr), time=cur_time
+        )
+        cmds.setKeyframe(
+            "{}.{}".format(ui_str, slide_attr), time=cur_time
+        )
 
     return True