jme3/animation/AnimationFactory.java

/*
 * Copyright (c) 2009-2011 jMonkeyEngine
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 * * Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * * Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 *
 * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
 *   may be used to endorse or promote products derived from this software
 *   without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package com.jme3.animation;

import com.jme3.math.FastMath;
import com.jme3.math.Quaternion;
import com.jme3.math.Transform;
import com.jme3.math.Vector3f;

/**
 * A convenience class to easily setup a spatial keyframed animation
 * you can add some keyFrames for a given time or a given keyFrameIndex, for translation rotation and scale.
 * The animationHelper will then generate an appropriate SpatialAnimation by interpolating values between the keyFrames.
 * <br><br>
 * Usage is : <br>
 * - Create the AnimationHelper<br>
 * - add some keyFrames<br>
 * - call the buildAnimation() method that will retruna new Animation<br>
 * - add the generated Animation to any existing AnimationControl<br>
 * <br><br>
 * Note that the first keyFrame (index 0) is defaulted with the identy transforms.
 * If you want to change that you have to replace this keyFrame with any transform you want.
 *
 * @author Nehon
 */
public class AnimationFactory {

    /**
     * step for splitting rotation that have a n ange above PI/2
     */
    private final static float EULER_STEP = FastMath.QUARTER_PI * 3;

    /**
     * enum to determine the type of interpolation
     */
    private enum Type {

        Translation, Rotation, Scale;
    }

    /**
     * Inner Rotation type class to kep track on a rotation Euler angle
     */
    protected class Rotation {

        /**
         * The rotation Quaternion
         */
        Quaternion rotation = new Quaternion();
        /**
         * This rotation expressed in Euler angles
         */
        Vector3f eulerAngles = new Vector3f();
        /**
         * the index of the parent key frame is this keyFrame is a splitted rotation
         */
        int masterKeyFrame = -1;

        public Rotation() {
            rotation.loadIdentity();
        }

        void set(Quaternion rot) {
            rotation.set(rot);
            float[] a = new float[3];
            rotation.toAngles(a);
            eulerAngles.set(a[0], a[1], a[2]);
        }

        void set(float x, float y, float z) {
            float[] a = {x, y, z};
            rotation.fromAngles(a);
            eulerAngles.set(x, y, z);
        }
    }
    /**
     * Name of the animation
     */
    protected String name;
    /**
     * frames per seconds
     */
    protected int fps;
    /**
     * Animation duration in seconds
     */
    protected float duration;
    /**
     * total number of frames
     */
    protected int totalFrames;
    /**
     * time per frame
     */
    protected float tpf;
    /**
     * Time array for this animation
     */
    protected float[] times;
    /**
     * Translation array for this animation
     */
    protected Vector3f[] translations;
    /**
     * rotation array for this animation
     */
    protected Quaternion[] rotations;
    /**
     * scales array for this animation
     */
    protected Vector3f[] scales;
    /**
     * The map of keyFrames to compute the animation. The key is the index of the frame
     */
    protected Vector3f[] keyFramesTranslation;
    protected Vector3f[] keyFramesScale;
    protected Rotation[] keyFramesRotation;

    /**
     * Creates and AnimationHelper
     * @param duration the desired duration for the resulting animation
     * @param name the name of the resulting animation
     */
    public AnimationFactory(float duration, String name) {
        this(duration, name, 30);
    }

    /**
     * Creates and AnimationHelper
     * @param duration the desired duration for the resulting animation
     * @param name the name of the resulting animation
     * @param fps the number of frames per second for this animation (default is 30)
     */
    public AnimationFactory(float duration, String name, int fps) {
        this.name = name;
        this.duration = duration;
        this.fps = fps;
        totalFrames = (int) (fps * duration) + 1;
        tpf = 1 / (float) fps;
        times = new float[totalFrames];
        translations = new Vector3f[totalFrames];
        rotations = new Quaternion[totalFrames];
        scales = new Vector3f[totalFrames];
        keyFramesTranslation = new Vector3f[totalFrames];
        keyFramesTranslation[0] = new Vector3f();
        keyFramesScale = new Vector3f[totalFrames];
        keyFramesScale[0] = new Vector3f(1, 1, 1);
        keyFramesRotation = new Rotation[totalFrames];
        keyFramesRotation[0] = new Rotation();

    }

    /**
     * Adds a key frame for the given Transform at the given time
     * @param time the time at which the keyFrame must be inserted
     * @param transform the transforms to use for this keyFrame
     */
    public void addTimeTransform(float time, Transform transform) {
        addKeyFrameTransform((int) (time / tpf), transform);
    }

    /**
     * Adds a key frame for the given Transform at the given keyFrame index
     * @param keyFrameIndex the index at which the keyFrame must be inserted
     * @param transform the transforms to use for this keyFrame
     */
    public void addKeyFrameTransform(int keyFrameIndex, Transform transform) {
        addKeyFrameTranslation(keyFrameIndex, transform.getTranslation());
        addKeyFrameScale(keyFrameIndex, transform.getScale());
        addKeyFrameRotation(keyFrameIndex, transform.getRotation());
    }

    /**
     * Adds a key frame for the given translation at the given time
     * @param time the time at which the keyFrame must be inserted
     * @param translation the translation to use for this keyFrame
     */
    public void addTimeTranslation(float time, Vector3f translation) {
        addKeyFrameTranslation((int) (time / tpf), translation);
    }

    /**
     * Adds a key frame for the given translation at the given keyFrame index
     * @param keyFrameIndex the index at which the keyFrame must be inserted
     * @param translation the translation to use for this keyFrame
     */
    public void addKeyFrameTranslation(int keyFrameIndex, Vector3f translation) {
        Vector3f t = getTranslationForFrame(keyFrameIndex);
        t.set(translation);
    }

    /**
     * Adds a key frame for the given rotation at the given time<br>
     * This can't be used if the interpolated angle is higher than PI (180°)<br>
     * Use {@link addTimeRotationAngles(float time, float x, float y, float z)}  instead that uses Euler angles rotations.<br>     *
     * @param time the time at which the keyFrame must be inserted
     * @param rotation the rotation Quaternion to use for this keyFrame
     * @see #addTimeRotationAngles(float time, float x, float y, float z)
     */
    public void addTimeRotation(float time, Quaternion rotation) {
        addKeyFrameRotation((int) (time / tpf), rotation);
    }

    /**
     * Adds a key frame for the given rotation at the given keyFrame index<br>
     * This can't be used if the interpolated angle is higher than PI (180°)<br>
     * Use {@link addKeyFrameRotationAngles(int keyFrameIndex, float x, float y, float z)} instead that uses Euler angles rotations.
     * @param keyFrameIndex the index at which the keyFrame must be inserted
     * @param rotation the rotation Quaternion to use for this keyFrame
     * @see #addKeyFrameRotationAngles(int keyFrameIndex, float x, float y, float z)
     */
    public void addKeyFrameRotation(int keyFrameIndex, Quaternion rotation) {
        Rotation r = getRotationForFrame(keyFrameIndex);
        r.set(rotation);
    }

    /**
     * Adds a key frame for the given rotation at the given time.<br>
     * Rotation is expressed by Euler angles values in radians.<br>
     * Note that the generated rotation will be stored as a quaternion and interpolated using a spherical linear interpolation (slerp)<br>
     * Hence, this method may create intermediate keyFrames if the interpolation angle is higher than PI to ensure continuity in animation<br>
     *
     * @param time the time at which the keyFrame must be inserted
     * @param x the rotation around the x axis (aka yaw) in radians
     * @param y the rotation around the y axis (aka roll) in radians
     * @param z the rotation around the z axis (aka pitch) in radians
     */
    public void addTimeRotationAngles(float time, float x, float y, float z) {
        addKeyFrameRotationAngles((int) (time / tpf), x, y, z);
    }

    /**
     * Adds a key frame for the given rotation at the given key frame index.<br>
     * Rotation is expressed by Euler angles values in radians.<br>
     * Note that the generated rotation will be stored as a quaternion and interpolated using a spherical linear interpolation (slerp)<br>
     * Hence, this method may create intermediate keyFrames if the interpolation angle is higher than PI to ensure continuity in animation<br>
     *
     * @param keyFrameIndex the index at which the keyFrame must be inserted
     * @param x the rotation around the x axis (aka yaw) in radians
     * @param y the rotation around the y axis (aka roll) in radians
     * @param z the rotation around the z axis (aka pitch) in radians
     */
    public void addKeyFrameRotationAngles(int keyFrameIndex, float x, float y, float z) {
        Rotation r = getRotationForFrame(keyFrameIndex);
        r.set(x, y, z);

        // if the delta of euler angles is higher than PI, we create intermediate keyframes
        // since we are using quaternions and slerp for rotation interpolation, we cannot interpolate over an angle higher than PI
        int prev = getPreviousKeyFrame(keyFrameIndex, keyFramesRotation);
        //previous rotation keyframe
        Rotation prevRot = keyFramesRotation[prev];
        //the maximum delta angle (x,y or z)
        float delta = Math.max(Math.abs(x - prevRot.eulerAngles.x), Math.abs(y - prevRot.eulerAngles.y));
        delta = Math.max(delta, Math.abs(z - prevRot.eulerAngles.z));
        //if delta > PI we have to create intermediates key frames
        if (delta >= FastMath.PI) {
            //frames delta
            int dF = keyFrameIndex - prev;
            //angle per frame for x,y ,z
            float dXAngle = (x - prevRot.eulerAngles.x) / (float) dF;
            float dYAngle = (y - prevRot.eulerAngles.y) / (float) dF;
            float dZAngle = (z - prevRot.eulerAngles.z) / (float) dF;

            // the keyFrame step
            int keyStep = (int) (((float) (dF)) / delta * (float) EULER_STEP);
            // the current keyFrame
            int cursor = prev + keyStep;
            while (cursor < keyFrameIndex) {
                //for each step we create a new rotation by interpolating the angles
                Rotation dr = getRotationForFrame(cursor);
                dr.masterKeyFrame = keyFrameIndex;
                dr.set(prevRot.eulerAngles.x + cursor * dXAngle, prevRot.eulerAngles.y + cursor * dYAngle, prevRot.eulerAngles.z + cursor * dZAngle);
                cursor += keyStep;
            }

        }

    }

    /**
     * Adds a key frame for the given scale at the given time
     * @param time the time at which the keyFrame must be inserted
     * @param scale the scale to use for this keyFrame
     */
    public void addTimeScale(float time, Vector3f scale) {
        addKeyFrameScale((int) (time / tpf), scale);
    }

    /**
     * Adds a key frame for the given scale at the given keyFrame index
     * @param keyFrameIndex the index at which the keyFrame must be inserted
     * @param scale the scale to use for this keyFrame
     */
    public void addKeyFrameScale(int keyFrameIndex, Vector3f scale) {
        Vector3f s = getScaleForFrame(keyFrameIndex);
        s.set(scale);
    }

    /**
     * returns the translation for a given frame index
     * creates the translation if it doesn't exists
     * @param keyFrameIndex index
     * @return the translation
     */
    private Vector3f getTranslationForFrame(int keyFrameIndex) {
        if (keyFrameIndex < 0 || keyFrameIndex > totalFrames) {
            throw new ArrayIndexOutOfBoundsException("keyFrameIndex must be between 0 and " + totalFrames + " (received " + keyFrameIndex + ")");
        }
        Vector3f v = keyFramesTranslation[keyFrameIndex];
        if (v == null) {
            v = new Vector3f();
            keyFramesTranslation[keyFrameIndex] = v;
        }
        return v;
    }

    /**
     * returns the scale for a given frame index
     * creates the scale if it doesn't exists
     * @param keyFrameIndex index
     * @return the scale
     */
    private Vector3f getScaleForFrame(int keyFrameIndex) {
        if (keyFrameIndex < 0 || keyFrameIndex > totalFrames) {
            throw new ArrayIndexOutOfBoundsException("keyFrameIndex must be between 0 and " + totalFrames + " (received " + keyFrameIndex + ")");
        }
        Vector3f v = keyFramesScale[keyFrameIndex];
        if (v == null) {
            v = new Vector3f();
            keyFramesScale[keyFrameIndex] = v;
        }
        return v;
    }

    /**
     * returns the rotation for a given frame index
     * creates the rotation if it doesn't exists
     * @param keyFrameIndex index
     * @return the rotation
     */
    private Rotation getRotationForFrame(int keyFrameIndex) {
        if (keyFrameIndex < 0 || keyFrameIndex > totalFrames) {
            throw new ArrayIndexOutOfBoundsException("keyFrameIndex must be between 0 and " + totalFrames + " (received " + keyFrameIndex + ")");
        }
        Rotation v = keyFramesRotation[keyFrameIndex];
        if (v == null) {
            v = new Rotation();
            keyFramesRotation[keyFrameIndex] = v;
        }
        return v;
    }

    /**
     * Creates an Animation based on the keyFrames previously added to the helper.
     * @return the generated animation
     */
    public Animation buildAnimation() {
        interpolateTime();
        interpolate(keyFramesTranslation, Type.Translation);
        interpolate(keyFramesRotation, Type.Rotation);
        interpolate(keyFramesScale, Type.Scale);

        SpatialTrack spatialTrack = new SpatialTrack(times, translations, rotations, scales);

        //creating the animation
        Animation spatialAnimation = new Animation(name, duration);
        spatialAnimation.setTracks(new SpatialTrack[]{spatialTrack});

        return spatialAnimation;
    }

    /**
     * interpolates time values
     */
    private void interpolateTime() {
        for (int i = 0; i < totalFrames; i++) {
            times[i] = i * tpf;
        }
    }

    /**
     * Interpolates over the key frames for the given keyFrame array and the given type of transform
     * @param keyFrames the keyFrames array
     * @param type the type of transforms
     */
    private void interpolate(Object[] keyFrames, Type type) {
        int i = 0;
        while (i < totalFrames) {
            //fetching the next keyFrame index transform in the array
            int key = getNextKeyFrame(i, keyFrames);
            if (key != -1) {
                //computing the frame span to interpolate over
                int span = key - i;
                //interating over the frames
                for (int j = i; j <= key; j++) {
                    // computing interpolation value
                    float val = (float) (j - i) / (float) span;
                    //interpolationg depending on the transform type
                    switch (type) {
                        case Translation:
                            translations[j] = FastMath.interpolateLinear(val, (Vector3f) keyFrames[i], (Vector3f) keyFrames[key]);
                            break;
                        case Rotation:
                            Quaternion rot = new Quaternion();
                            rotations[j] = rot.slerp(((Rotation) keyFrames[i]).rotation, ((Rotation) keyFrames[key]).rotation, val);
                            break;
                        case Scale:
                            scales[j] = FastMath.interpolateLinear(val, (Vector3f) keyFrames[i], (Vector3f) keyFrames[key]);
                            break;
                    }
                }
                //jumping to the next keyFrame
                i = key;
            } else {
                //No more key frame, filling the array witht he last transform computed.
                for (int j = i; j < totalFrames; j++) {

                    switch (type) {
                        case Translation:
                            translations[j] = ((Vector3f) keyFrames[i]).clone();
                            break;
                        case Rotation:
                            rotations[j] = ((Quaternion) ((Rotation) keyFrames[i]).rotation).clone();
                            break;
                        case Scale:
                            scales[j] = ((Vector3f) keyFrames[i]).clone();
                            break;
                    }
                }
                //we're done
                i = totalFrames;
            }
        }
    }

    /**
     * Get the index of the next keyFrame that as a transform
     * @param index the start index
     * @param keyFrames the keyFrames array
     * @return the index of the next keyFrame
     */
    private int getNextKeyFrame(int index, Object[] keyFrames) {
        for (int i = index + 1; i < totalFrames; i++) {
            if (keyFrames[i] != null) {
                return i;
            }
        }
        return -1;
    }

    /**
     * Get the index of the previous keyFrame that as a transform
     * @param index the start index
     * @param keyFrames the keyFrames array
     * @return the index of the previous keyFrame
     */
    private int getPreviousKeyFrame(int index, Object[] keyFrames) {
        for (int i = index - 1; i >= 0; i--) {
            if (keyFrames[i] != null) {
                return i;
            }
        }
        return -1;
    }
}