[GeospatialCamera] Update flyToAsync hop behavior to animate center with parabolic hop (vs scale radius) (#17512)

Rather than using customKeys for customizing the interpolating behavior,
allow user to customize any part of the animation via callback.

This is now used to animate center rather than radius so that center can
have a parabolic hop animation based on passed in scale factor.

The problem with previous approach was that just animating radius is not
super noticeable if the camera is already very close to ground /
pitchedtowards horizon. This approach creates a true parabolic arc
motion

#17451

Co-authored-by: Georgina Halpern <[email protected]>

Author: georginahalpern

packages/dev/core/src/Behaviors/Cameras/interpolatingBehavior.ts

@@ -5,7 +5,6 @@ import type { Animatable } from "../../Animations/animatable.core";
 import { Animation } from "../../Animations/animation";
 import type { Camera } from "../../Cameras/camera";
 import type { IColor3Like, IColor4Like, IMatrixLike, IQuaternionLike, IVector2Like, IVector3Like } from "../../Maths/math.like";
-import type { IAnimationKey } from "../../Animations/animationKey";
 
 export type AllowedAnimValue = number | IVector2Like | IVector3Like | IQuaternionLike | IMatrixLike | IColor3Like | IColor4Like | SizeLike | undefined;
 
@@ -110,7 +109,7 @@ export class InterpolatingBehavior<C extends Camera = Camera> implements Behavio
         properties: Map<K, AllowedAnimValue>,
         transitionDuration: number = this.transitionDuration,
         easingFn: EasingFunction = this.easingFunction,
-        customKeys?: Map<K, IAnimationKey[]>
+        updateAnimation?: (key: string, animation: Animation) => void
     ): Promise<void> {
         const promise = new Promise<void>((resolve) => {
             this.stopAllAnimations();
@@ -139,22 +138,14 @@ export class InterpolatingBehavior<C extends Camera = Camera> implements Behavio
             };
 
             properties.forEach((value, key) => {
-                if (value !== undefined) {
+                if (value !== undefined && camera[key] !== value) {
                     const propertyName = String(key);
                     const animation = Animation.CreateAnimation(propertyName, GetAnimationType(value), 60, easingFn);
+                    // Optionally allow caller to further customize the animation
+                    updateAnimation?.(propertyName, animation);
+
                     // Pass false for stopCurrent so that we can interpolate multiple properties at once
-                    const animatable = Animation.TransitionTo(
-                        propertyName,
-                        value,
-                        camera,
-                        scene,
-                        60,
-                        animation,
-                        transitionDuration,
-                        () => checkClear(propertyName),
-                        false,
-                        customKeys?.get(key)
-                    );
+                    const animatable = Animation.TransitionTo(propertyName, value, camera, scene, 60, animation, transitionDuration, () => checkClear(propertyName), false);
                     if (animatable) {
                         this._animatables.set(propertyName, animatable);
                     }

packages/dev/core/src/Cameras/geospatialCamera.ts

@@ -8,11 +8,12 @@ import type { DeepImmutable } from "../types";
 import { GeospatialLimits } from "./Limits/geospatialLimits";
 import { ClampCenterFromPolesInPlace, ComputeLocalBasisToRefs, GeospatialCameraMovement } from "./geospatialCameraMovement";
 import type { IVector3Like } from "../Maths/math.like";
-import { Vector3CopyToRef } from "../Maths/math.vector.functions";
+import { Vector3CopyToRef, Vector3Distance } from "../Maths/math.vector.functions";
 import { Clamp } from "../Maths/math.scalar.functions";
 import type { AllowedAnimValue } from "../Behaviors/Cameras/interpolatingBehavior";
 import { InterpolatingBehavior } from "../Behaviors/Cameras/interpolatingBehavior";
 import type { EasingFunction } from "../Animations/easing";
+import type { Animation } from "../Animations/animation";
 
 type CameraOptions = {
     planetRadius: number; // Radius of the planet
@@ -212,7 +213,6 @@ export class GeospatialCamera extends Camera {
         this._flyingBehavior.updateProperties(this._flyToTargets);
     }
 
-    private _customKeys = new Map();
     /**
      * Animate camera towards passed in property values. If undefined, will use current value
      * @param targetYaw
@@ -221,7 +221,7 @@ export class GeospatialCamera extends Camera {
      * @param targetCenter
      * @param flightDurationMs
      * @param easingFunction
-     * @param overshootRadiusScale If defined, will first fly to radius*scale before flying to targetRadius to create a "bounce" effect
+     * @param centerHopScale If supplied, will define the parabolic hop height scale for center animation to create a "bounce" effect
      * @returns Promise that will return when the animation is complete (or interuppted by pointer input)
      */
     public async flyToAsync(
@@ -231,30 +231,47 @@ export class GeospatialCamera extends Camera {
         targetCenter?: Vector3,
         flightDurationMs: number = 1000,
         easingFunction?: EasingFunction,
-        overshootRadiusScale?: number
+        centerHopScale?: number
     ): Promise<void> {
         this._flyToTargets.clear();
-        this._customKeys.clear();
 
         this._flyToTargets.set("yaw", targetYaw);
         this._flyToTargets.set("pitch", targetPitch);
         this._flyToTargets.set("radius", targetRadius);
         this._flyToTargets.set("center", targetCenter);
 
-        const overshootRadius = overshootRadiusScale !== undefined ? this.radius * overshootRadiusScale : undefined;
-        if (overshootRadius !== undefined && overshootRadius !== targetRadius) {
-            // Start the animation with overshoot radius
-            const frameRate = 60;
-            const totalFrames = (flightDurationMs / 1000) * frameRate;
-            const midFrame = totalFrames / 2;
-
-            this._customKeys.set("radius", [
-                { frame: 0, value: this.radius },
-                { frame: midFrame, value: overshootRadius },
-                { frame: totalFrames, value: targetRadius },
-            ]);
+        let overrideAnimationFunction;
+        if (targetCenter !== undefined && !targetCenter.equals(this.center)) {
+            // Animate center directly with custom interpolation
+            const start = this.center.clone();
+            const end = targetCenter.clone();
+
+            overrideAnimationFunction = (key: string, animation: Animation): void => {
+                if (key === "center") {
+                    // Override the Vector3 interpolation to use SLERP + hop
+                    animation.vector3InterpolateFunction = (startValue, endValue, gradient) => {
+                        // gradient is the eased value (0 to 1) after easing function is applied
+
+                        // Slerp between start and end
+                        const newCenter = Vector3.SlerpToRef(start, end, gradient, this._tempCenter);
+
+                        // Apply parabolic hop if requested
+                        if (centerHopScale && centerHopScale > 0) {
+                            // Parabolic formula: peaks at t=0.5, returns to 0 at gradient=0 and gradient=1
+                            // if hopPeakT = .5 the denominator would be hopPeakT * hopPeakT - hopPeakT, which = -.25
+                            const hopPeakOffset = centerHopScale * Vector3Distance(start, end);
+                            const hopOffset = hopPeakOffset * Clamp((gradient * gradient - gradient) / -0.25);
+                            // Scale the center outward (away from origin)
+                            newCenter.scaleInPlace(1 + hopOffset / newCenter.length());
+                        }
+
+                        return newCenter;
+                    };
+                }
+            };
         }
-        return await this._flyingBehavior.animatePropertiesAsync(this._flyToTargets, flightDurationMs, easingFunction, this._customKeys);
+
+        return await this._flyingBehavior.animatePropertiesAsync(this._flyToTargets, flightDurationMs, easingFunction, overrideAnimationFunction);
     }
 
     /**