Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


OptAnim ("Optimal Animation") is a Python library for the procedural generation of 3D skeletal character animations. It uses the principles of Optimal Control, coupled with a simple but powerful parameter-space system to ease the generation of large quantities of physically-accurate animations.


  • use virtually any character morphology
  • physically accurate animation
  • scalable: produce hundreds of animations quickly
  • flexible: easily accommodate design changes
  • precise: satisfy technical animation requirements exactly
  • seamless animation looping (for walk cycles etc.)
  • parallel processing on multi-core machines
  • outputs .BVH and Ogre3D skeleton.XML files


Other versions of these may also work. Try your luck.


First install Python, SymPy, NumPy and cgkit. Install the AMPL and IPOPT executables on your system, and make sure they can be accessed via the system PATH variable. Now download the OptAnim source and run:

$ python install

You can test the install by running one of the examples:

$ cd examples
$ python ./

Example Usage

Define characters by connecting rigid-bodies with joints. In this simple example we'll just use a single body:

>>> char = Character('Basketball')
>>> body = RigidBody(Id=0, Name='BasketballBody', Mass=0.6237, Diameter=[0.239, 0.239, 0.239])
>>> char.add_body(body)

Create parameter spaces to generate animations for characters:

>>> anim = ParameterSpace(Name='ShotTrajectory', FPS=30, Length=2.0)
>>> anim.add_character(char)

For each parameter space, specify what animations we want using constraints and objectives functions:

>>> #for a ball starting at each of these coordinates:
>>> anim.add_dimension([[ConstraintEq("Xstart", body.tx(0), x)] for x in range(2,8)])
>>> anim.add_dimension([[ConstraintEq("Ystart", body.ty(0), 0.0)]])
>>> anim.add_dimension([[ConstraintEq("Zstart",, z)] for z in range(-3,4)])
>>> #and passing through the hoop on frame 50
>>> anim.add_dimension([[ConstraintEq("Xend", body.tx(50), 0.0), ConstraintEq("Yend", body.ty(50), 3.0), ConstraintEq("Zend",, 0.0)]])

Generate the animations:

>>> anim.generate()
>>> anim.wait_for_results()


There's no official documentation yet. For now, this video provides a quick overview: and my thesis has many more details:


I'd like to get feedback from animators, developers and researchers alike. Tell me what you think. Or jump right in, fork the repository and try something (there are some ideas in the TODO file). And send me a pull request!


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

OptAnim 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 General Public License for more details.

You should have received a copy of the GNU General Public License along with OptAnim. If not, see <>.


Copyright (c) 2010-2012, Lorne McIntosh


A library for the procedural generation of 3D skeletal character animations







No releases published


No packages published