Let Follow custom animations use the average of two parameters

New Follow animations pair a left/right parameter automatically. The generator
computes the average in the Inputs layer and the preview uses it too.

Author: hchoki

Packages/net.pawlygon.unitytools/Editor/FTExtrasCustomAnimations.cs

@@ -91,6 +91,9 @@ public class FTExtrasCustomAnimation
 
         // --- Follow ---
         public string followParameter;
+        [Tooltip("Follow the average of Follow Parameter and this one (e.g. left and right brow).")]
+        public bool followAverage;
+        public string followParameterB;
         public FTExtrasFollowStyle followStyle = FTExtrasFollowStyle.FadeIn;
         public float fromValue;
         public float toValue = 1f;
@@ -119,9 +122,19 @@ public class FTExtrasCustomAnimation
         /// <summary>Every parameter this animation reads.</summary>
         public IEnumerable<string> UsedParameters =>
             mode == FTExtrasCustomMode.Follow
-                ? new[] { followParameter }.Where(p => !string.IsNullOrEmpty(p))
+                ? new[] { followParameter, IsAveraged ? followParameterB : null }.Where(p => !string.IsNullOrEmpty(p)).Distinct()
                 : conditions.Select(c => c.parameter).Where(p => !string.IsNullOrEmpty(p)).Distinct();
 
+        /// <summary>Follow: whether the value is the average of two parameters.</summary>
+        public bool IsAveraged => followAverage && !string.IsNullOrEmpty(followParameterB);
+
+        /// <summary>Follow: the value that drives the animation (one parameter, or the average of two).</summary>
+        public float FollowValue(Func<string, float> valueOf)
+        {
+            float a = string.IsNullOrEmpty(followParameter) ? 0f : valueOf(followParameter);
+            return IsAveraged ? (a + valueOf(followParameterB)) * 0.5f : a;
+        }
+
         /// <summary>
         /// Whether the conditions start the animation (All: every one met; Any: at least one).
         /// </summary>

Packages/net.pawlygon.unitytools/Editor/FTExtrasGenerator.cs

@@ -478,7 +478,9 @@ private static void BuildInputsLayer(ControllerBuilder builder, ClipStore clips,
         /// </summary>
         private static BlendTree InputsTree(ControllerBuilder builder, ClipStore clips, FTExtrasGenerationSettings settings, CustomAnimationPlan customs, bool includeJaw)
         {
-            var outputs = new[] { ParamGazeLeftX, ParamGazeRightX, ParamGazeY, ParamMood, ParamJaw };
+            var outputs = new[] { ParamGazeLeftX, ParamGazeRightX, ParamGazeY, ParamMood, ParamJaw }
+                .Concat(customs.Animations.Where(a => a.HasComputedDriver).Select(a => a.Driver))
+                .ToArray();
             AnimationClip zero = clips.Parameters("Inputs - Zero", outputs.Select(p => (p, 0f)).ToArray());
 
             BlendTree root = builder.NewTree(includeJaw ? "Inputs (Jaw On)" : "Inputs (Jaw Off)", BlendTreeType.Direct, null);
@@ -497,6 +499,13 @@ private static BlendTree InputsTree(ControllerBuilder builder, ClipStore clips,
                 children.Add(Direct(RangeTree(builder, clips, settings.jawX, settings.jawFullAt, ParamJaw, 1f), settings.lipTrackingActive));
             }
 
+            // Followed averages: each parameter adds half of its value.
+            foreach (CustomAnimationSpec spec in customs.Animations.Where(a => a.HasComputedDriver))
+            {
+                children.Add(Direct(HalfTree(builder, clips, spec.Animation.followParameter, spec.Driver, $"{spec.SafeName} A"), ParamOne));
+                children.Add(Direct(HalfTree(builder, clips, spec.Animation.followParameterB, spec.Driver, $"{spec.SafeName} B"), ParamOne));
+            }
+
             // Scrubbed custom animations: map the parameter's from..to range onto a 0..1 playback position.
             foreach (CustomAnimationSpec spec in customs.Animations.Where(a => a.ScrubParameter != null))
             {
@@ -508,15 +517,31 @@ private static BlendTree InputsTree(ControllerBuilder builder, ClipStore clips,
         }
 
         /// <summary>
-        /// 1D tree mapping the Follow parameter's from..to range to a 0..1 playback position (clamped outside).
+        /// 1D tree writing half of the input into the output, linear over the parameter's range (at least
+        /// -1..1); two of them in the Direct tree make the average.
+        /// </summary>
+        private static BlendTree HalfTree(ControllerBuilder builder, ClipStore clips, string input, string output, string label)
+        {
+            FTExtrasParameterCatalog.Entry info = FTExtrasParameterCatalog.Describe(input);
+            float low = Mathf.Min(-1f, info.Min);
+            float high = Mathf.Max(1f, info.Max);
+
+            BlendTree tree = builder.NewTree($"Custom - {label} half of {input}", BlendTreeType.Simple1D, input);
+            tree.AddChild(clips.Parameters($"Custom - {label} - Low", (output, low * 0.5f)), low);
+            tree.AddChild(clips.Parameters($"Custom - {label} - High", (output, high * 0.5f)), high);
+            return tree;
+        }
+
+        /// <summary>
+        /// 1D tree mapping the Follow value's from..to range to a 0..1 playback position (clamped outside).
         /// </summary>
         private static BlendTree PositionTree(ControllerBuilder builder, ClipStore clips, CustomAnimationSpec spec)
         {
             FTExtrasCustomAnimation animation = spec.Animation;
             AnimationClip start = clips.Parameters($"Custom - {spec.SafeName} - Position 0", (spec.ScrubParameter, 0f));
             AnimationClip end = clips.Parameters($"Custom - {spec.SafeName} - Position 1", (spec.ScrubParameter, 1f));
 
-            BlendTree tree = builder.NewTree($"{animation.name} position from {animation.followParameter}", BlendTreeType.Simple1D, animation.followParameter);
+            BlendTree tree = builder.NewTree($"{animation.name} position from {spec.Driver}", BlendTreeType.Simple1D, spec.Driver);
             AddSorted(tree, (animation.fromValue, start), (animation.toValue, end));
             return tree;
         }
@@ -771,6 +796,10 @@ private class CustomAnimationSpec
             public List<string> Gates = new List<string>();
             public string Toggle;
             public string ScrubParameter;
+
+            /// <summary>Follow: the parameter the layer reads; a computed average when following two.</summary>
+            public string Driver;
+            public bool HasComputedDriver => Driver != null && Driver != Animation.followParameter;
         }
 
         /// <summary>
@@ -819,6 +848,11 @@ public CustomAnimationPlan(FTExtrasProfile profile, FTExtrasGenerationSettings s
                         Toggles.Add(new CustomToggle { Label = animation.name, Parameter = spec.Toggle, DefaultOn = animation.toggleDefaultOn });
                     }
 
+                    if (animation.mode == FTExtrasCustomMode.Follow)
+                    {
+                        spec.Driver = animation.IsAveraged ? CustomParamPrefix + safeName + "/Value" : animation.followParameter;
+                    }
+
                     if (animation.mode == FTExtrasCustomMode.Follow && animation.followStyle == FTExtrasFollowStyle.Scrub)
                     {
                         spec.ScrubParameter = CustomParamPrefix + safeName + "/Position";
@@ -836,6 +870,7 @@ public void AddParameters(ControllerBuilder builder)
                     foreach (string gate in spec.Gates) builder.AddFloat(gate, 0f);
                     if (spec.Toggle != null) builder.AddBool(spec.Toggle, spec.Animation.toggleDefaultOn);
                     if (spec.ScrubParameter != null) builder.AddFloat(spec.ScrubParameter, 0f);
+                    if (spec.HasComputedDriver) builder.AddFloat(spec.Driver, 0f);
                 }
             }
 
@@ -845,6 +880,7 @@ private static string DescribeProblem(FTExtrasCustomAnimation animation)
                 if (animation.mode == FTExtrasCustomMode.Follow)
                 {
                     if (string.IsNullOrWhiteSpace(animation.followParameter)) return "no parameter is set.";
+                    if (animation.followAverage && string.IsNullOrWhiteSpace(animation.followParameterB)) return "the parameter to average with is not set.";
                     if (Mathf.Approximately(animation.fromValue, animation.toValue)) return "'From' and 'To' are the same value.";
                 }
                 else
@@ -901,14 +937,14 @@ private static void BuildFollowLayer(ControllerBuilder builder, ClipStore clips,
             {
                 case FTExtrasFollowStyle.FadeIn:
                 {
-                    BlendTree tree = builder.NewTree($"{animation.name} (fade in)", BlendTreeType.Simple1D, animation.followParameter);
+                    BlendTree tree = builder.NewTree($"{animation.name} (fade in)", BlendTreeType.Simple1D, spec.Driver);
                     AddSorted(tree, (animation.fromValue, empty), (animation.toValue, animation.clip));
                     active.motion = tree;
                     break;
                 }
                 case FTExtrasFollowStyle.TwoSided:
                 {
-                    BlendTree tree = builder.NewTree($"{animation.name} (two-sided)", BlendTreeType.Simple1D, animation.followParameter);
+                    BlendTree tree = builder.NewTree($"{animation.name} (two-sided)", BlendTreeType.Simple1D, spec.Driver);
                     float middle = (animation.fromValue + animation.toValue) * 0.5f;
                     AddSorted(tree, (animation.fromValue, animation.negativeClip != null ? (Motion)animation.negativeClip : empty), (middle, empty), (animation.toValue, animation.clip));
                     active.motion = tree;
@@ -947,8 +983,8 @@ private static void BuildFollowLayer(ControllerBuilder builder, ClipStore clips,
                 float span = Mathf.Abs(animation.toValue - animation.fromValue);
                 float enter = animation.fromValue + direction * span * 0.02f;
                 float leave = animation.fromValue + direction * span * 0.01f;
-                start.AddCondition(direction > 0f ? AnimatorConditionMode.Greater : AnimatorConditionMode.Less, enter, animation.followParameter);
-                Transition(active, off, Blend).AddCondition(direction > 0f ? AnimatorConditionMode.Less : AnimatorConditionMode.Greater, leave, animation.followParameter);
+                start.AddCondition(direction > 0f ? AnimatorConditionMode.Greater : AnimatorConditionMode.Less, enter, spec.Driver);
+                Transition(active, off, Blend).AddCondition(direction > 0f ? AnimatorConditionMode.Less : AnimatorConditionMode.Greater, leave, spec.Driver);
             }
 
             AddStopTransitions(sm, off, spec, Blend);

Packages/net.pawlygon.unitytools/Editor/FaceTrackingExtras.Custom.cs

@@ -170,6 +170,12 @@ private void AddCustomAnimation(FTExtrasCustomMode mode)
                 if (first != null)
                 {
                     animation.followParameter = first.Name;
+
+                    // Left/right pairs are usually followed together.
+                    string otherSide = MatchingSide(first.Name, catalog);
+                    animation.followAverage = otherSide != first.Name;
+                    animation.followParameterB = animation.followAverage ? otherSide : null;
+
                     animation.fromValue = Mathf.Max(0f, first.Min);
                     animation.toValue = first.Max;
                 }
@@ -330,7 +336,31 @@ private void DrawCustomAnimationEditor(int index, FTExtrasCustomAnimation animat
 
         private void DrawFollowSettings(FTExtrasCustomAnimation animation, List<FTExtrasParameterCatalog.Entry> catalog)
         {
+            string previous = animation.followParameter;
             animation.followParameter = DrawParameterField("Parameter", animation.followParameter, catalog);
+
+            // Keep a left/right pair together when the first parameter changes.
+            if (animation.followParameter != previous && animation.followParameterB == MatchingSide(previous, catalog))
+            {
+                animation.followParameterB = MatchingSide(animation.followParameter, catalog);
+            }
+
+            bool average = EditorGUILayout.Toggle(
+                new GUIContent("Average with", "Follow the average of two parameters, e.g. the left and right brow."), animation.followAverage);
+            if (average && !animation.followAverage && string.IsNullOrEmpty(animation.followParameterB))
+            {
+                animation.followParameterB = MatchingSide(animation.followParameter, catalog);
+            }
+            animation.followAverage = average;
+            if (average)
+            {
+                animation.followParameterB = DrawParameterField(" ", animation.followParameterB, catalog);
+                if (animation.followParameterB == animation.followParameter)
+                {
+                    EditorGUILayout.HelpBox("Both parameters are the same; pick the other one to average.", MessageType.Info);
+                }
+            }
+
             FTExtrasParameterCatalog.Entry info = FTExtrasParameterCatalog.Describe(animation.followParameter);
 
             animation.followStyle = (FTExtrasFollowStyle)EditorGUILayout.Popup("Style", (int)animation.followStyle, FollowStyleLabels);
@@ -503,7 +533,10 @@ private static string DescribeCustomAnimation(FTExtrasCustomAnimation animation)
             if (animation.mode == FTExtrasCustomMode.Follow)
             {
                 string style = FollowStyleLabels[(int)animation.followStyle].Split(' ')[0].ToLowerInvariant();
-                return $"{clip} follows {ParameterLabel(animation.followParameter)} ({style}, {animation.fromValue:0.##} → {animation.toValue:0.##})";
+                string source = animation.IsAveraged
+                    ? $"the average of {ParameterLabel(animation.followParameter)} and {ParameterLabel(animation.followParameterB)}"
+                    : ParameterLabel(animation.followParameter);
+                return $"{clip} follows {source} ({style}, {animation.fromValue:0.##} → {animation.toValue:0.##})";
             }
 
             string joiner = animation.combine == FTExtrasConditionCombine.All ? " and " : " or ";
@@ -521,6 +554,7 @@ private static string DescribeCustomProblem(FTExtrasCustomAnimation animation)
             if (animation.mode == FTExtrasCustomMode.Follow)
             {
                 if (string.IsNullOrWhiteSpace(animation.followParameter)) return "no parameter is set.";
+                if (animation.followAverage && string.IsNullOrWhiteSpace(animation.followParameterB)) return "the parameter to average with is not set.";
                 if (Mathf.Approximately(animation.fromValue, animation.toValue)) return "'From' and 'To' are the same value.";
             }
             else
@@ -658,7 +692,7 @@ float ClipTimeAt(AnimationClip clip) => clip == null ? 0f
 
             if (animation.mode == FTExtrasCustomMode.Follow)
             {
-                float value = ValueOf(animation.followParameter);
+                float value = animation.FollowValue(ValueOf);
                 switch (animation.followStyle)
                 {
                     case FTExtrasFollowStyle.FadeIn: