animatelib

3D viewer

Download | Quick start guide | Documentation | License

animatelib is a free C++ library that allows one to easily animate multiple rigid bodies in a 3D scene. The 3D models are either imported into the scene or automatically generated from basic shapes. The library is currently available as Visual Studio 2015 binaries, and can be called from C++ and MATLAB. It is built upon OpenSceneGraph/OpenGL, and has been used in multiple real-time applications.

Download

Release 0.0 (alpha)


Quick start guide

Library

Download and unzip the following libraries:

animatelib      https://sites.google.com/site/alcallejo/animatelib
OpenSceneGraph  http://objexx.com/OpenSceneGraph.html
Eigen           http://eigen.tuxfamily.org

Create the following environment variables (*): 

ANIMATELIB_INCLUDE  C:\PathToInstallDirectory\animatelib\include
ANIMATELIB_LIB      C:\PathToInstallDirectory\animatelib\lib
EIGEN_INCLUDE       C:\PathToInstallDirectory\Eigen-3.2.10 (**)

Add the following directories to the Windows Path:

C:\PathToInstallDirectory\animatelib\bin
C:\PathToInstallDirectory\OpenSceneGraph\bin
C:\PathToInstallDirectory\MATLAB\R2016b\bin\win64

(*) Directories are given merely as an example

(**) Note that Eigen's header files should be inside /Eigen-3.2.10/Eigen/

C++ examples

  1. Open animatelib/examples.sln with Visual Studio
  2. Uncomment the desired example in main.cpp
  3. Select the 64-bit Debug or Release configuration
  4. Build the solution
  5. Run

MATLAB examples

1. Open one of these examples with MATLAB:

  animatelib/examples/pendulum.m
  animatelib/examples/triangle.m
  animatelib/examples/teapot.m

2. Run

Documentation

The rendering function (render in C++ or animatelib_mex in MATLAB) takes 5 arguments. These include the current simulation time, lists of configurations, bodies and joints, and a structure with the simulation properties. A brief summary of the C++ datatypes is provided here (the values between square brackets are default values). Lists of objects are defined in a similar way in MATLAB, as shown in the examples.

Time

double t

BodyConfiguration 

Vector3d position       [Vector3d::Zero()]
Matrix3d rotationMatrix [Matrix3d::Identity()]

Body 

string           name        [""]
Vector3d         cog         [Vector3d::Zero()]
vector<Vector3d> points
vector<Vector3d> unitVectors
vector<Vector2i> lines
int              render      [1]
string           graphics    [""]
string           color       ["Default"]

Joint

string   name        [""]
char     type        ['\0']
Vector2i bodies      [Vector2i::Zero()]
Vector2i points      [Vector2i::Zero()]
Vector2i unitVectors [Vector2i::Zero()]
int      render      [1]
string   color       ["Default"]

SimulationSetup 

double time_step    [0.01]
double total_time   [0]
double camera_zoom  [3]
double camera_dispx [0]
string name         ["untitled"]

Each system requires its own folder in animatelib/models. The name of the folder must be the same as SimulationSetup.name. The geometry of the Body is defined in the local reference frame, whereas BodyConfiguration contains the global position and orientation of such reference frame.

Each body/joint must have a unique name defined in Body.name or Joint.name. If the name of the body/joint contains an asterisk (*), its transparency will be interactively adjustable (by using the [f] control key) when the viewer is launched.

If a 3D graphics filename is specified in Body.graphics, the viewer will attempt to find it in animatelib/models/<system> and import it.

Supported 3D model formats are, among others, 3ds, stl, obj, osg, ive. IVE format is particularly efficient in OpenSceneGraph. If Body.graphics is not defined, animatelib will generate the 3D model based on the lines provided in Body.lines.

The first time render (or animatelib_mex) is called, the bodies are generated and stored in animatelib/models/<system> for later use. To regenerate the 3D files, please manually delete the IVE files in animatelib/models/<system>. This is usually necessary, for instance, when the user modifies the local geometry (Body.lines, etc.).

Subsequent render (or animatelib_mex) calls simply update the positions and rotations based on the current BodyConfiguration values.


License

animatelib by Alfonso Callejo is licensed under a Creative Commons Attribution 4.0 International License. The library is not open source, but can be freely downloaded and used "as is", with no warranty whatsoever.