The Animation3D Module

Project Name: MakeHuman

Product Home Page: http://www.makehuman.org/

Code Home Page: https://bitbucket.org/MakeHuman/makehuman/

Authors: Marc Flerackers

Copyright(c): MakeHuman Team 2001-2015

Licensing: AGPL3 (http://www.makehuman.org/doc/node/the_makehuman_application.html)

This file is part of MakeHuman (www.makehuman.org).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>.

Coding Standards: See http://www.makehuman.org/node/165

Abstract

This module contains functions and classes to animate a wide range of objects and attributes.

To know more about the interpolation methods used, see the following references:

• http://local.wasp.uwa.edu.au/~pbourke/miscellaneous/interpolation/
• http://en.wikipedia.org/wiki/Cubic_Hermite_spline
• http://en.wikipedia.org/wiki/Kochanek-Bartels_spline
• http://www.geometrictools.com/Documentation/KBSplines.pdf
• http://www.tinaja.com/glib/cubemath.pdf

class animation3d.Action

Base action class, does nothing

class animation3d.CameraAction(cam, startParams, endParams)

CameraAction action class. Animates all camera attributes.

class animation3d.PathAction(obj, positions)

Path action class. Moves an object along a path

class animation3d.RotateAction(obj, startAngles, endAngles)

Rotate action class. Rotates an object from a start orientation to an end orientation.

classmethod closestAngle(beginAngle, endAngle)

Assumes that beginAngle and endAngle are clipped between [0, 360[ Calculates end angle so that linear interpolation between beginAngle and the returned end angle results in a minimal rotation.

class animation3d.ScaleAction(obj, startScale, endScale)

Scale action class. Scales an object from a start scale to an end scale.

class animation3d.Timeline(seconds)

A timeline combines several animation3d.Action objects to an animation.

class animation3d.UpdateAction(app)

Updates the scene. Without this acton and animation is not visible.

class animation3d.ZoomAction(obj, startZoom, endZoom)

A zoom transition for a camera

animation3d.animate(app, seconds, actions)

Animates the given actions by creating a animation3d.Timeline, adding an animation3d.UpdateAction and calling start.

animation3d.cosineInterpolate(v1, v2, alpha)

When you have more than 2 points two interpolate (for example following a path), this is a better choice than a linear interpolator.

animation3d.cubicBSplineInterpolator(v0, v1, v2, v3, alpha)

Cubic b-spline interpolator. v0 and v3 are begin and end point respectively, v1 and v2 are control points.

\frac{1}{6} \begin{bmatrix} -1 & 3 & -3 & 1 \\ 3 & -6 & 3 & 0 \\ -3 & 0 & 3 & 0 \\ 1 & 4 & 1 & 0 \end{bmatrix}

animation3d.cubicBezierInterpolator(v0, v1, v2, v3, alpha)

Cubic Bezier interpolator. v0 and v3 are begin and end point respectively, v1 and v2 are control points.

\begin{bmatrix} -1 & 3 & -3 & 1 \\ 3 & -6 & 3 & 0 \\ -3 & 3 & 0 & 0 \\ 1 & 0 & 0 & 0 \end{bmatrix}

animation3d.cubicCatmullRomInterpolator(v0, v1, v2, v3, alpha)

Cubic Catmull Rom interpolator. v0 and v3 are begin and end point respectively, v1 and v2 are control points.

\frac{1}{2} \begin{bmatrix} -1 & 3 & -3 & 1 \\ 2 & -5 & 4 & -1 \\ -1 & 0 & 1 & 0 \\ 1 & 2 & 0 & 0 \end{bmatrix}

animation3d.cubicHermiteInterpolator(v0, v1, v2, v3, alpha)

Cubic hermite interpolator. v0 and v3 are begin and end point respectively, v1 and v2 are control points.

\frac{1}{6} \begin{bmatrix} 2 & 1 & -2 & 1 \\ -3 & -2 & 3 & -1 \\ 0 & 1 & 0 & 0 \\ 1 & 0 & 0 & 0 \end{bmatrix}

animation3d.cubicInterpolate(v0, v1, v2, v3, alpha)

Cubic interpolator. Gives better continuity along the spline than the cosine interpolator, however needs 4 points to interpolate.

animation3d.hermiteInterpolate(v0, v1, v2, v3, alpha, tension, bias)

Hermite interpolator. Allows better control of the bends in the spline by providing two parameters to adjust them:

• tension: 1 for high tension, 0 for normal tension and -1 for low tension.
• bias: 1 for bias towards the next segment, 0 for even bias, -1 for bias towards the previous segment.

Using 0 bias gives a cardinal spline with just tension, using both 0 tension and 0 bias gives a Catmul-Rom spline.

animation3d.kochanekBartelsInterpolator(v0, v1, v2, v3, alpha, tension, continuity, bias)

Kochanek-Bartels interpolator. Allows even better control of the bends in the spline by providing three parameters to adjust them:

• tension: 1 for high tension, 0 for normal tension and -1 for low tension.
• continuity: 1 for inverted corners, 0 for normal corners, -1 for box corners.
• bias: 1 for bias towards the next segment, 0 for even bias, -1 for bias towards the previous segment.

Using 0 continuity gives a hermite spline.

animation3d.lerpVector(v0, v1, alpha, interpolator=<function linearInterpolate at 0x348ec80>)

Interpolates a whole vector at once.

animation3d.linearInterpolate(v1, v2, alpha)

Good interpolator when you have two values to interpolate between, but doesn’t give fluid animation when more points are involved since it follows straight lines between the points.

animation3d.quadraticBSplineInterpolator(v0, v1, v2, alpha)

Quadratic b-spline interpolator. v0 and v2 are begin and end point respectively, v1 is a control point.

\frac{1}{2} \begin{bmatrix} 1 & -2 & 1 \\ -2 & 2 & 0 \\ 1 & 1 & 0 \end{bmatrix}

animation3d.quadraticBezierInterpolator(v0, v1, v2, alpha)

Quadratic Bezier interpolator. v0 and v2 are begin and end point respectively, v1 is a control point.

\begin{bmatrix} 1 & -2 & 1 \\ -2 & 2 & 0 \\ 1 & 1 & 0 \end{bmatrix}