Package com.google.ar.sceneform.animation

Class ModelAnimator

  • public class ModelAnimator
extends java.lang.Object
    This class provides support for animating an AnimatableModel

    Usage

    By default the ModelAnimator can play the full ModelAnimation starting from 0 to the animation duration with: 

     ofAnimation(AnimatableModel, String...)

    If you want to specify a start and end, you should use: 

     ofAnimationTime(AnimatableModel, String, float...)
 
     ofAnimationFrame(AnimatableModel, String, int...)
 
     ofAnimationFraction(AnimatableModel, String, float...)

    Use cases

    Simple usage

    On a very basic 3D model like a single infinite rotating sphere, you should not have to use ModelAnimator but probably instead just call: 

     AnimatableModel.animate(boolean)

    Single Model with Single Animation

    If you want to animate a single model to a specific timeline position, use: 

     ofAnimationTime(AnimatableModel, String, float...)
 
     ofAnimationFrame(AnimatableModel, String, int...)
 
     ofAnimationFraction(AnimatableModel, String, float...)
    • A single time, frame, fraction value will go from the actual position to the desired one
    • Two values means form value1 to value2
    • More than two values means form value1 to value2 then to value3
    Example: 
     ModelAnimator.ofAnimationFraction(model, "VerticalTranslation", 0f, 0.8f, 0f).start();

    Single Model with Multiple Animations

    If the model is a character, for example, there may be one ModelAnimation for a walkcycle, a second for a jump, a third for sidestepping and so on. 

     ofAnimation(AnimatableModel, String...)
 
     ofMultipleAnimations(AnimatableModel, String...)
    Example:

    Here you can see that no call to animator.cancel() is required because the animator.setAutoCancel(boolean) is set to true by default. 

     ObjectAnimator walkAnimator = ModelAnimator.ofAnimation(model, "walk");
 walkButton.setOnClickListener(v -> walkAnimator.start());

 ObjectAnimator runAnimator = ModelAnimator.ofAnimation(model, "run");
 runButton.setOnClickListener(v -> runAnimator.start());
    or sequentially: 
     AnimatorSet animatorSet = new AnimatorSet();
 animatorSet.playSequentially(ModelAnimator.ofMultipleAnimations(model, "walk", "run"));
 animatorSet.start();

    Multiple Models with Multiple Animations

    For a synchronised animation set like animating a complete scene with multiple models time or sequentially, please consider using an AnimatorSet with one ModelAnimator parametrized per step :

    Example: 
     AnimatorSet completeFly = new AnimatorSet();

 ObjectAnimator liftOff = ModelAnimator.ofAnimationFraction(airPlaneModel, "FlyAltitude",0, 40);
 liftOff.setInterpolator(new AccelerateInterpolator());

 AnimatorSet flying = new AnimatorSet();
 ObjectAnimator flyAround = ModelAnimator.ofAnimation(airPlaneModel, "FlyAround");
 flyAround.setRepeatCount(ValueAnimator.INFINITE);
 flyAround.setDuration(10000);
 ObjectAnimator airportBusHome = ModelAnimator.ofAnimationFraction(busModel, "Move", 0);
 flying.playTogether(flyAround, airportBusHome);

 ObjectAnimator land = ModelAnimator.ofAnimationFraction(airPlaneModel, "FlyAltitude", 0);
 land.setInterpolator(new DecelerateInterpolator());

 completeFly.playSequentially(liftOff, flying, land);

    Morphing animation

    Assuming a character object has a skeleton, one keyframe track could store the data for the position changes of the lower arm bone over time, a different track the data for the rotation changes of the same bone, a third the track position, rotation or scaling of another bone, and so on. It should be clear, that an ModelAnimation can act on lots of such tracks.

    Assuming the model has morph targets (for example one morph target showing a friendly face and another showing an angry face), each track holds the information as to how the influence of a certain morph target changes during the performance of the clip.

    In a glTF context, this Animator updates matrices according to glTF animation and skin definitions.

    ModelAnimator can be used for two things

    • Updating matrices in TransformManager components according to the model animation definitions.
    • Updating bone matrices in RenderableManager components according to the model skin definitions.

    Every PropertyValuesHolder that applies a modification on the time position of the animation must use the ModelAnimation.TIME_POSITION instead of its own Property in order to possibly cancel any ObjectAnimator operating time modifications on the same ModelAnimation.

    More information about Animator: https://developer.android.com/guide/topics/graphics/prop-animation

    • Constructor Detail

      • ModelAnimator

        public ModelAnimator()

    • Method Detail

      • ofMultipleAnimations

        public static java.util.List<android.animation.ObjectAnimator> ofMultipleAnimations​(AnimatableModel model,
                                                                                    java.lang.String... animationNames)
        Constructs and returns list of ObjectAnimator given names inside an AnimatableModel. Can be used directly with AnimatorSet.playTogether(Collection) AnimatorSet.playSequentially(List)
        Parameters:
        model - The targeted model to animate
        Returns:
        The constructed ObjectAnimator
        See Also:
        ofAnimation(AnimatableModel, ModelAnimation...)

      • ofAnimation

        public static android.animation.ObjectAnimator ofAnimation​(AnimatableModel model,
                                                           java.lang.String... animationNames)
        Constructs and returns an ObjectAnimator for targeted ModelAnimation with a given name inside an AnimatableModel. The setAutoCancel(true) won't work for new call with different animations.

        Don't forget to call ObjectAnimator.start()

        Parameters:
        model - The targeted model to animate
        animationNames - The string names of the animations.
        This name should correspond to the one defined and exported in the model.
        Typically the action name defined in the 3D creation software. ModelAnimation.getName()
        Returns:
        The constructed ObjectAnimator
        See Also:
        ofAnimation(AnimatableModel, ModelAnimation...)

      • ofAnimation

        public static android.animation.ObjectAnimator ofAnimation​(AnimatableModel model,
                                                           int... animationIndexes)
        Constructs and returns an ObjectAnimator for targeted ModelAnimation with a given index inside an AnimatableModel. The setAutoCancel(true) won't work for new call with different animations.

        Don't forget to call ObjectAnimator.start()

        Parameters:
        model - The targeted animatable to animate
        animationIndexes - Zero-based indexes for the animations of interest.
        Returns:
        The constructed ObjectAnimator
        See Also:
        ofAnimation(AnimatableModel, ModelAnimation...)

      • ofAnimation

        public static android.animation.ObjectAnimator ofAnimation​(AnimatableModel model,
                                                           ModelAnimation... animations)
        Constructs and returns an ObjectAnimator for a targeted ModelAnimation inside an AnimatableModel. The setAutoCancel(true) won't work for new call with different animations. This method applies by default this to the returned ObjectAnimator :
        • The duration value to the max ModelAnimation.getDuration() in order to match the original animation speed.
        • The interpolator to LinearInterpolator in order to match the natural animation interpolation.

        Don't forget to call ObjectAnimator.start()

        Parameters:
        model - The targeted animatable to animate
        animations - The animations of interest
        Returns:
        The constructed ObjectAnimator

      • ofAnimationTime

        public static android.animation.ObjectAnimator ofAnimationTime​(AnimatableModel model,
                                                               ModelAnimation animation,
                                                               float... times)
        Constructs and returns an ObjectAnimator clipping a ModelAnimation to a given set of time values.

        Time values can help you targeting a specific position on an animation coming from a 3D creation software with a default times based timeline. It's the 3D designer responsibility to tell you what specific timeline position corresponds to a specific model appearance.

        • A single value implies that that value is the one being animated to starting from the actual value on the provided ModelAnimation.
        • Two values imply a starting and ending values.
        • More than two values imply a starting value, values to animate through along the way, and an ending value (these values will be distributed evenly across the duration of the animation).

        The properties (time, frame,... position) are applied to the AnimatableModel
        This method applies by default this to the returned ObjectAnimator :

        • The duration value to the ModelAnimation.getDuration() in order to match the original animation speed.
        • The interpolator to LinearInterpolator in order to match the natural animation interpolation.

        Don't forget to call ObjectAnimator.start()

        Parameters:
        model - The targeted model to animate
        animation - The animation of interest
        times - The elapsed times (between 0 and ModelAnimation.getDuration() that the ModelAnimation will animate between.
        Returns:
        The constructed ObjectAnimator

      • ofAnimationFrame

        public static android.animation.ObjectAnimator ofAnimationFrame​(AnimatableModel model,
                                                                ModelAnimation animation,
                                                                int... frames)
        Constructs and returns an ObjectAnimator clipping a ModelAnimation to a given set of frame values.

        Frame number can help you targeting a specific position on an animation coming from a 3D creation software with a frame numbers based timeline. It's the 3D designer responsibility to tell you what specific timeline position corresponds to a specific model appearance.
        The corresponding time of a frame number is calculated using ModelAnimation.getFrameRate().

        • A single value implies that that value is the one being animated to starting from the actual value on the provided ModelAnimation.
        • Two values imply a starting and ending values.
        • More than two values imply a starting value, values to animate through along the way, and an ending value (these values will be distributed evenly across the duration of the animation).

        The properties (time, frame,... position) are applied to the AnimatableModel
        This method applies by default this to the returned ObjectAnimator :

        • The duration value to the ModelAnimation.getDuration() in order to match the original animation speed.
        • The interpolator to LinearInterpolator in order to match the natural animation interpolation.

        Don't forget to call ObjectAnimator.start()

        Parameters:
        model - The targeted model to animate
        animation - The animation of interest
        frames - The frame numbers (between 0 and ModelAnimation.getFrameCount() that the ModelAnimation will animate between.
        Returns:
        The constructed ObjectAnimator
        See Also:
        ofAnimationTime(AnimatableModel, ModelAnimation, float...)

      • ofAnimationFraction

        public static android.animation.ObjectAnimator ofAnimationFraction​(AnimatableModel model,
                                                                   java.lang.String animationName,
                                                                   float... fractions)
        Constructs and returns an ObjectAnimator clipping a ModelAnimation to a given set of fraction values.

        Don't forget to call ObjectAnimator.start()

        Parameters:
        model - The targeted model to animate
        animationName - The string name of the animation.
        This name should correspond to the one defined and exported in the model.
        Typically the action name defined in the 3D creation software. ModelAnimation.getName()
        fractions - The fractions (percentage) (between 0 and 1)
        Returns:
        The constructed ObjectAnimator
        See Also:
        ofAnimationFraction(AnimatableModel, ModelAnimation, float...), ModelAnimation.getName()

      • ofAnimationFraction

        public static android.animation.ObjectAnimator ofAnimationFraction​(AnimatableModel model,
                                                                   int animationIndex,
                                                                   float... fractions)
        Constructs and returns an ObjectAnimator clipping a ModelAnimation to a given set of fraction values.

        Don't forget to call ObjectAnimator.start()

        Parameters:
        model - The targeted model to animate
        animationIndex - Zero-based index for the animation of interest.
        fractions - The fractions (percentage) (between 0 and 1)
        Returns:
        The constructed ObjectAnimator
        See Also:
        ofAnimationFraction(AnimatableModel, ModelAnimation, float...)

      • ofAnimationFraction

        public static android.animation.ObjectAnimator ofAnimationFraction​(AnimatableModel model,
                                                                   ModelAnimation animation,
                                                                   float... fractions)
        Constructs and returns an ObjectAnimator clipping a ModelAnimation to a given set of fraction values.
        • A single value implies that that value is the one being animated to starting from the actual value on the provided ModelAnimation.
        • Two values imply a starting and ending values.
        • More than two values imply a starting value, values to animate through along the way, and an ending value (these values will be distributed evenly across the duration of the animation).

        The properties (time, frame,... position) are applied to the AnimatableModel This method applies by default this to the returned ObjectAnimator :

        • The duration value to the ModelAnimation.getDuration() in order to match the original animation speed.
        • The interpolator to LinearInterpolator in order to match the natural animation interpolation.

        Don't forget to call ObjectAnimator.start()

        Parameters:
        model - The targeted model to animate
        animation - The animation of interest
        fractions - The fractions (percentage) (between 0 and 1)
        Returns:
        The constructed ObjectAnimator
        See Also:
        ofAnimationTime(AnimatableModel, ModelAnimation, float...)

      • ofPropertyValuesHolder

        public static android.animation.ObjectAnimator ofPropertyValuesHolder​(AnimatableModel model,
                                                                      android.animation.PropertyValuesHolder... values)
        Constructs and returns an ObjectAnimator a ModelAnimation applying PropertyValuesHolders.
        • A single value implies that that value is the one being animated to starting from the actual value on the provided ModelAnimation.
        • Two values imply a starting and ending values.
        • More than two values imply a starting value, values to animate through along the way, and an ending value (these values will be distributed evenly across the duration of the animation).

        The properties (time, frame,... position) are applied to the AnimatableModel
        This method applies by default this to the returned ObjectAnimator :

        • The interpolator to LinearInterpolator in order to match the natural animation interpolation.

        Don't forget to call ObjectAnimator.start()

        Parameters:
        model - The targeted model to animate
        values - A set of PropertyValuesHolder objects whose values will be animated between over time.
        Returns:
        The constructed ObjectAnimator