I. DANCE MANUAL - Ari Shapiro

141 Pages·2009·1.62 MB·English

by  Ari Shapiro

Ari Shapiro
[email protected]
http://www.arishapiro.com
Updated 4/11/09
I. DANCE MANUAL
Help
For help, please refer to the DANCE website: http://www.arishapiro.com/dance/
To subscribe to the DANCE development email list, send an email to:
[email protected]
To post a message to this email list, subscribe first, then send an email to:
[email protected]
If you have any specific issues you would like to discuss about DANCE, you can email Ari Shapiro
directly at:
[email protected]
http://www.arishapiro.com
For a technical overview of the DANCE platform, please see our research paper at:
http://www.arishapiro.com/shapiroa_DANCE.pdf
and for our paper on controllers:
http://www.arishapiro.com/Sandbox07_DynamicToolkit.pdf
1. Overview
DANCE is a software environment for graphics and animation with an emphasis on rigid body
dynamic and character controller development. DANCE allows you to create ragdoll simulations,
rigid body collisions, and control characters under physical simulation. DANCE contains the
following features:
• Ragdoll simulation
• Physical simulation of characters with dynamic control
• Pose-based dynamic control
• Physically-based controller scripting language via Python
• Import/Export of motion capture (BVH, ASF/AMC)
• Loading/saving of standard 3-D model object types.
• Skinning algorithm to create deformable meshes driven by skeletons/bones.
• Creation of videos from OpenGL or high quality output via POVRay
http://www.povray.org
• Integrated with the Open Dynamics Engine (ODE) http://www.ode.org
• Multi-platform (Windows, linux, OSX)
The DANCE environment operates using a plugin architecture. Users can create and manipulate
plugins that perform various actions in the DANCE environment. For example:
• The Cube plugin will create a 3-dimensional cube that can be manipulated and
animated.
• The ODESim plugin will create a rigid body simulator that uses the Open Dynamics
Engine (www.ode.org).
• The MotionPlayer plugin will allow the user to load, save and manipulate motion
capture data.
Each plugin typically has a visual representation that is shown in the DANCE window, a set of
GUI widget that allows the user to interactive control various parameters, and a set of
commands that can be accessed via the Python scripting language. DANCE comes with a set of
plugins that include shapes, physical simulation, motion capture display and so forth. Each of
the plugins can be modified if needed. In addition, custom plugins can be built in order to
expand functionality as well.
Initial DANCE screen. The window on the left displays objects in the DANCE
environment. The empty panel on the right holds the GUI interface for each object.
The timeline on the bottom shows the simulation time. The controls on the lower
left control the simulators. The controls in the middle control the playback for
simulated objects.
1.1.1 Supported Platforms
DANCE currently runs on both the the Windows and Linux platforms and has been adapted to
work on OSX. The source code for DANCE is available and may be used to port to other
platforms as well. Windows code is compiled using Microsoft Studio .NET (v8.0/2005,
v9.0/2008) and using g++ on Linux. The DANCE code is cross-platform compatible and all
libraries used by DANCE (FLTK, ImageMagick, ODE) are cross-platform libraries.
1.1.2 License
Noncommercial License
The DANCE software is distributed for noncommercial use in the hope that it will be useful but
WITHOUT ANY WARRANTY. The author(s) do not accept responsibility to anyone for the
consequence of using it or for whether it serves any particular purpose or works at all. No
warranty is made about the software or its performance.
Any plugin code written for DANCE belongs to the developer of that plugin, who is free to
license that code in any manner desired.
Content and code development by third parties (such as FLTK, Python, ImageMagick, ODE) may
be governed by different licenses.
You may modify and distribute this software for noncommercial use
as long as you give credit to the original authors by including the following text in every file that
is distributed:
/*********************************************************
Copyright 2005 by Ari Shapiro and Petros Faloutsos
DANCE
Dynamic ANimation and Control Environment
-----------------------------------------
AUTHOR:
Ari Shapiro ([email protected])
ORIGINAL AUTHORS:
Victor Ng ([email protected])
Petros Faloutsos ([email protected])
CONTRIBUTORS:
Yong Cao ([email protected])
Paco Abad ([email protected])
**********************************************************/
Commercial Use
DANCE may be used commercially only for internal purposes under the following conditions:
- Any commercial users of DANCE must notify Ari Shapiro by email at
[email protected] as to:
o The purpose of the use of DANCE, in whole or in part.
- The authors of DANCE reserve the right to advertise that the software is being used
commercially by such commercial entity.
- DANCE may not be sold in whole or in part, and can only be used for internal purposes
or development of software used internally and not for sale.
- An example of valid commercial use is:
o Internal development of applications to generate images or videos – this is
allowed by the commercial license indicated here.
o Extraction of algorithms or techniques from DANCE for use as a plugin into
another software program that is used for internal purposes – this is allowed by
the commercial license indicated here.
- An example of invalid use is:
o DANCE being sold in whole or in part – this is NOT allowed by the commercial
license indicated here.
o Packaging DANCE independently or extracting algorithms from DANCE and
selling them as part of a commercial entity’s software products – this is NOT
allowed by the commercial license indicated here.
If you are interested in using DANCE in whole or in part for commercial uses not covered by the
license, please contact Ari Shapiro at [email protected].
1.3 DANCE_DIR Environment Variable
Before running DANCE, it is important to set a system variable called:
DANCE_DIR
to the directory that contains the main DANCE distribution. Users on all platforms (including
Windows) should use forward slashes (‘/’) and not backslashes (‘\’). For example, if the DANCE
distribution is located in c:\programs\dance_v4, the DANCE_DIR variable should be:
c:/programs/dance_v4.
1.4 Compilation
1.4.1 Windows Compilation
DANCE will compile on the Windows platform using Microsoft Studio v8.0 (Visual Studio 2005)
and Microsoft Visual Studio 2008.
1) Unzip the DANCE distribution. The DANCE distribution will be
dance_v4_MMddyy_hhmm.zip where MMddyy_hhmm is the month, day, year, hour and
minute of the build time.
2) Create the environmental variable: DANCE_DIR and make this variable indicate the location of
the dance_v4/ directory. Use forward slashes (/) and not backslashes(\) to separate
subdirectories. For example, if your dance_v4/ directory is located in
c:\my\subdirectory\dance_v4, your DANCE_DIR variable should be:
c:/my/subdirectory/dance_v4
3) Download the 8-bit DLL version of image magick.
http://www.imagemagick.org/download/binaries/ImageMagick-6.4.5-3-Q8-
windows-dll.exe
(Note that the latest version of the ImageMagick libraries may change. Please choose the latest
8-bit version at http://www.imagemagick.org/script/binary-releases.php#windows). Install the
executable. During the installation process, make sure that you check ‘Install development
headers and libraries for C and C++”. The paths to the image magick directory will need to be
added to your Visual Studio directories in step 6 below.
4) Download the Python DLL:
http://www.python.org/ftp/python/2.5.2/python-2.5.2.msi
Install the executable. Note that the latest version of the Python libraries may change. DANCE is
compatible with Python 2.3, Python 2.4 and Python 2.5.
5) Perform the following additional steps in order to link the proper runtime library with both
FLTK, ODE and lib3ds:
1. Recompile FLTK dlls:
• Open %DANCE_DIR%/extensions/fltk-2.0.x-r4773/ide/vcnet/fltk.sln
• Build the fltkdll project in Debug and Release modes.
• Build the fltkdll_images project in Debug and Release modes.
• The compiled .DLLs will be automatically placed in the $DANCE_DIR/bin
directory, and the .lib files will be automatically places in the
$DANCE_DIR/lib/win directory.
• Note that more recent versions of FLT ~may~ be substituted for the 4773
version included in the DANCE distribution. However, the more recent versions
of FLTK on Windows have much worse performance than the 4773 versions. If
you choose to use a more recent version of FLTK, make sure that the .lib files
are placed in $DANCE_DIR/lib/win and the .DLLs are placed in the $DANCE_DIR/
bin directories.
2. Recompile ODE dlls:
• Open %DANCE_DIR%/extensions/ode-0.10.1/build/vs2005/ode.sln
• Build the ode project in debugdoubledll and releasedoubledll modes.
• The compiled .DLLs will be automatically placed in the $DANCE_DIR/bin
directory, and the .lib files will be automatically places in the
$DANCE_DIR/lib/win directory.
3. Recompile lib3ds libs:
• Open %DANCE_DIR%/extensions/lib3ds-1.3.0/msvc8/llib3ds.sln
• Build the lib3ds project in debug and release modes.
• The compiled .DLLs will be automatically placed in the $DANCE_DIR/bin
directory, and the .lib files will be automatically places in the
$DANCE_DIR/lib/win directory.
6) For Visual Studio 2005, open the %DANCE_DIR% /build/vs2005/dance_v4_2005.sln
solution in Microsoft’s Visual Studio.
For Visual Studio 2008, open the %DANCE_DIR% /build/vs2008/dance_v4_2005.sln
solution in Microsoft’s Visual Studio and allow Visual Studio to automatically convert the project
and solution files automatically.
6) Make sure the proper Python and ImageMagick paths have been properly added to the Visual
Studio include and library directories:
Go to: Tools -> Options
Choose: Projects (left hand side)
Select: VC++ Directories
Under “Show Directories For” (upper right), select “Include Files”
Make sure that the ImageMagick include directory is correct. For example: c:\program
files\ImageMagic-6.4.5-Q8\include.
Make sure that the Python include directory. For example: c:\Python25\include.
Under “Show Directories For” (upper right), select “Library Files”
Make sure the ImageMagick lib directory is correct. For example: c:\program files\ImageMagic-
6.4.5-Q8\lib
Make sure the Python lib directory is correct. For example: c:\Python25\libs
7) Build the entire solution (right click on ‘Solution ‘dance_v4’/Build Solution). Note that there
are two building configurations: Debug and Release. The Debug configuration will build DANCE
with debug symbols and will run slower that the Release version. The Debug version of DANCE
creates an executable named
%DANCE_DIR%/bin/dance_d.exe
The Release version of DANCE creates an executable named
%DANCE_DIR%/bin/dance.exe
1.3.2 Linux Compilation
The Linux version of DANCE requires the g++ compiler as well as the following libraries:
Python 2.5 (Python 2.3 and 2.4 are compatible)
ImageMagick (with development libraries)
Mesa (OpenGL)
1) Unzip the DANCE distribution. The DANCE distribution will be
dance_v4_MMddyy_hhmm.zip where MMddyy_hhmm is the month, day, year, hour and
minute of the build time.
2) Create the environmental variable: DANCE_DIR and make this variable indicate the location of
the dance_v4/ directory. For example, if your dance_v4/ directory is located in
/home/mydir/dance_v4, your DANCE_DIR variable should be:
/home/mydir/dance_v4:
Using bash, sh or ksh:
export DANCE_DIR=/home/mydir/dance_v4 or
Using csh:
setenv DANCE_DIR /home/mydir/dance_v4
3) Install the latest version of FLTK (you will need to have the X11 development and
Mesa/OpenGL development installed already):
• Download from http://ftp.easysw.com/pub/fltk/snapshots/fltk-2.0.x-
r6140.tar.gz
• Unzip to the $DANCE_DIR/extensions directory:
• cd $DANCE_DIR/extensions
• unzip fltk-2.0.x-r6140.tar.gz
• Build the FLTK libraries into the DANCE_DIR with shared library support:
o ./configure --prefix=$DANCE_DIR --enable-shared
o make
o make install
• Note that more recent versions of FLTK may be used from www.fltk.org.
4) Build and install the version of ODE in this DANCE distribution:
• cd $DANCE_DIR/extensions/ode-0.10.1
• chmod +x configure
• ./configure –prefix=$DANCE_DIR --enable-double-precision –enable-shared
• make
• make install
• Note that if you use a different version of ODE than is included in this
distribution, make the following changes:
o In file ode-10.1/src/