Unityでスクリプトから、Animatorコンポーネントの「Chest-Twist」などの値を取得する方法

Question

UnityのAnimationコンポーネントを触っていると、例えばHumanoidボーンが適応されているアバターですと、
腕や足の動きを「Chest Twist」や「Hand In-Out」なんかの値で制御することになりますが、
各項目の現在の値をスクリプトから参照するにはどうすればいいでしょうか。

Answer 1

エディター用スクリプトでならModelImporter経由でHumanDescriptionを取ってくることができ、その内容から設定値を調べることができそうでした。

Editorフォルダ内に下記のようなスクリプトを入れ、

using UnityEditor;
using UnityEngine;

public class HumanDescriptionExtractor : MonoBehaviour
{
    [MenuItem("Utility/Print HumanDescription")]
    public static void PrintHumanDescription()
    {
        var model = Selection.activeGameObject;
        var path = AssetDatabase.GetAssetPath(model);
        var importer = AssetImporter.GetAtPath(path) as ModelImporter;
        if (importer == null)
        {
            return;
        }

        var humanDescription = importer.humanDescription;
        Debug.Log($"HumanDescription for {model.name}:");
        Debug.Log("\tPer-Muscle Settings:");
        foreach (var humanBone in humanDescription.human)
        {
            var humanName = humanBone.humanName;

            // ボーン名一覧を見て、対応するボーン番号を見つける
            var boneIndex = -1;
            for (var j = 0; j < HumanTrait.BoneCount; j++)
            {
                if (HumanTrait.BoneName[j] == humanName)
                {
                    boneIndex = j;
                    break;
                }
            }

            if (boneIndex < 0)
            {
                continue;
            }

            // ボーンインデックスの各軸に対応するマッスル番号を見つける
            var muscleIndexX = HumanTrait.MuscleFromBone(boneIndex, 0);
            var muscleIndexY = HumanTrait.MuscleFromBone(boneIndex, 1);
            var muscleIndexZ = HumanTrait.MuscleFromBone(boneIndex, 2);

            // デフォルト値を使うよう設定されている場合は、limit内のmin・maxは無視するらしい?
            var limit = humanBone.limit;
            var useDefault = limit.useDefaultValues;
            var min = useDefault
                ? new Vector3(
                    muscleIndexX >= 0 ? HumanTrait.GetMuscleDefaultMin(muscleIndexX) : limit.min.x,
                    muscleIndexY >= 0 ? HumanTrait.GetMuscleDefaultMin(muscleIndexY) : limit.min.y,
                    muscleIndexZ >= 0 ? HumanTrait.GetMuscleDefaultMin(muscleIndexZ) : limit.min.z)
                : limit.min;
            var max = useDefault
                ? new Vector3(
                    muscleIndexX >= 0 ? HumanTrait.GetMuscleDefaultMax(muscleIndexX) : limit.max.x,
                    muscleIndexY >= 0 ? HumanTrait.GetMuscleDefaultMax(muscleIndexY) : limit.max.y,
                    muscleIndexZ >= 0 ? HumanTrait.GetMuscleDefaultMax(muscleIndexZ) : limit.max.z)
                : limit.max;

            // カスタム値が使われている場合は青文字で表示することにしました
            // インスペクタで範囲を個別に編集すると、その項目のuseDefaultValuesがfalseになるらしい?
            var minMaxColor = useDefault ? "<color=black>" : "<color=blue>";
            if (muscleIndexX >= 0)
            {
                Debug.Log(
                    $"\t\t{HumanTrait.MuscleName[muscleIndexX]}: {minMaxColor}{min.x}~{max.x}</color>");
            }

            if (muscleIndexY >= 0)
            {
                Debug.Log(
                    $"\t\t{HumanTrait.MuscleName[muscleIndexY]}: {minMaxColor}{min.y}~{max.y}</color>");
            }

            if (muscleIndexZ >= 0)
            {
                Debug.Log(
                    $"\t\t{HumanTrait.MuscleName[muscleIndexZ]}: {minMaxColor}{min.z}~{max.z}</color>");
            }
        }

        Debug.Log("\tAdditional Settings:");
        Debug.Log($"\t\tUpper Arm Twist:{humanDescription.upperArmTwist}");
        Debug.Log($"\t\tLower Arm Twist:{humanDescription.lowerArmTwist}");
        Debug.Log($"\t\tUpper Leg Twist:{humanDescription.upperLegTwist}");
        Debug.Log($"\t\tLower Leg Twist:{humanDescription.lowerLegTwist}");
        Debug.Log($"\t\tArm Stretch:{humanDescription.armStretch}");
        Debug.Log($"\t\tLeg Stretch:{humanDescription.legStretch}");
        Debug.Log($"\t\tFeet Spacing:{humanDescription.feetSpacing}");
        Debug.Log($"\t\tTranslation DoF:{humanDescription.hasTranslationDoF}");
    }
}

プロジェクトビュー内でモデルファイルを選択し「Utility」→「Print HumanDescription」を実行すると、下図のような出力結果が得られました。

エディタスクリプトでは何とかなりそうでしたが、実際の実行時にAvatarからHumanDescriptionを取り出すのはやっかいそうです。探した限りではそれらしきクラス・メソッドは見つからず、ModelImporterがどのようにHumanDescriptionを作っているかの詳細も公開されていないようで、もっと詳しく調査・解析する必要がありそうです（もしかすると不可能かもしれません）。
逆に、実行時にHumanDescriptionをもとにAvatarを作ることはAvatarBuilderを使えば可能らしいんですがね...

#追記
UnityEditorに頼らず実行時に値を取得する方法はないものか調べてみたものの、結局AvatarからのHumanDescription取得は困難そうでしたのであきらめました。
代案として、モデルのマッスルを最大・最小まで動かし、部位の回転を調べることでマッスル可動範囲の上限・下限を求められないかと思い、ちょっと試してみました。

モデルに対して特定のマッスル値を持つポーズを取らせるのは、HumanPoseHandlerを使えば可能なようです。そこで、各マッスルを1つずつ動かして、回転が起こった部位の角度変化を見てみました。
下記スクリプトをモデルにアタッチして実行したところ...

using System.Linq;
using UnityEngine;

[RequireComponent(typeof(Animator))]
public class MuscleRangeInvestigator : MonoBehaviour
{
    private void Start()
    {
        var animator = this.GetComponent<Animator>();
        var avatar = animator.avatar;
        Debug.Log($"Muscle ranges of {avatar.name}:");

        // マッスル名一覧を取得
        var muscleNames = HumanTrait.MuscleName;
        var muscleCount = HumanTrait.MuscleCount;

        // アバターと紐付いたポーズハンドラーを作成
        var poseHandler = new HumanPoseHandler(avatar, this.transform);

        // 現在のポーズを覚えておく
        // 後で姿勢を復元する際に、リターゲッティング処理の都合上姿勢がずれる可能性が
        // あるらしいので、ポーズを覚える前に親・位置・回転をそれぞれ覚えておき
        // 親子関係を一旦解除、位置・回転もゼロにする
        var initialLocalPosition = this.transform.localPosition;
        var initialLocalRotation = this.transform.localRotation;
        var initialParent = this.transform.parent;
        this.transform.SetParent(null);
        this.transform.localPosition = Vector3.zero;
        this.transform.localRotation = Quaternion.identity;
        var initialPose = new HumanPose();
        poseHandler.GetHumanPose(ref initialPose);

        // マッスル値をいじって実験するためのポーズを作る
        var pose = new HumanPose
        {
            bodyPosition = Vector3.zero,
            bodyRotation = Quaternion.identity,
            muscles = new float[initialPose.muscles.Length]
        };

        // モデルルート以下の全Transformを配列化
        var transforms = this.GetComponentsInChildren<Transform>();

        // ゼロ姿勢（膝や腕を半曲げにした、あの姿勢）をセット
        poseHandler.SetHumanPose(ref pose);

        // ゼロ姿勢でのローカル回転を覚えておく
        var zeroTransforms = transforms.Select(t => (Transform: t, Rotation: t.localRotation)).ToArray();

        // 全マッスルについて...
        for (var i = 0; i < muscleCount; i++)
        {
            // まずi番目マッスルを1にし、姿勢を適用
            pose.muscles[i] = 1.0f;
            poseHandler.SetHumanPose(ref pose);

            // 回転が発生したTransformを抜き出し、おそらくそれらのうち
            // 最大の角度変化量を可動角度上限として採用すればいいと思う...?
            var max = zeroTransforms.Where(t => t.Rotation != t.Transform.localRotation)
                .Select(t => Quaternion.Angle(t.Transform.localRotation, t.Rotation))
                .OrderByDescending(a => a).FirstOrDefault();

            // 引き続きi番目マッスルを-1にし、姿勢を適用
            pose.muscles[i] = -1.0f;
            poseHandler.SetHumanPose(ref pose);

            // 同じく最大の角度変化量を求め、符号を反転して可動角度下限として採用...?
            var min = -zeroTransforms.Where(t => t.Rotation != t.Transform.localRotation)
                .Select(t => Quaternion.Angle(t.Transform.localRotation, t.Rotation))
                .OrderByDescending(a => a).FirstOrDefault();

            // コンソールに結果を表示
            Debug.Log($"\t{muscleNames[i]}: {min:F1}~{max:F1}");

            // i番目マッスルを0に戻す
            pose.muscles[i] = 0.0f;
        }

        // 姿勢を元に戻して終わり
        poseHandler.SetHumanPose(ref initialPose);
        this.transform.SetParent(initialParent);
        this.transform.localPosition = initialLocalPosition;
        this.transform.localRotation = initialLocalRotation;
    }
}

下図のように、どうやらそれらしい値が得られました。ですが少々ごまかしがありまして、表示される値を小数点以下第1位で丸めています。実際の値はインスペクタ上の値とぴったり一致はしませんでした。おそらく計算誤差によるものでしょう...

※おまけ
各マッスルを動かしているときにそれぞれどのような姿勢になっているか見てみたところ、下図のようにEthanとユニティちゃんが体操する姿を撮影できました。ちょうどインスペクタ上の各マッスルのプレビュースライダーを操作したときと同様の動きをしていることがお分かりいただけるでしょうか?