Build

The simulated environments are written in C++, and the python wrapper is built using SWIG.
To install the python dependencies, run

pip install -r requirements.txt

Note that MPI must be installed before MPI4Py. When building Bullet, be sure to disable double precision with the build flag USE_DOUBLE_PRECISION=OFF.

Windows

The wrapper is built using DeepMimicCore.sln.

Select the x64 configuration from the configuration manager.

Under the project properties for DeepMimicCore modify Additional Include Directories to specify

Bullet source directory

Eigen include directory

python include directory

Modify Additional Library Directories to specify

Bullet lib directory

python lib directory

Build DeepMimicCore project with the Release_Swig configuration and this should
generate DeepMimicCore.py in DeepMimicCore/.

Linux

Modify the Makefile in DeepMimicCore/ by specifying the following,

EIGEN_DIR: Eigen include directory

BULLET_INC_DIR: Bullet source directory

PYTHON_INC: python include directory

PYTHON_LIB: python lib directory

Build wrapper,

make python

This should generate DeepMimicCore.py in DeepMimicCore/

How to Use

Once the python wrapper has been built, training is done entirely in python using Tensorflow.
DeepMimic.py runs the visualizer used to view the simulation. Training is done with mpi_run.py,
which uses MPI to parallelize training across multiple processes.

DeepMimic.py is run by specifying an argument file that provides the configurations for a scene.
For example,

python DeepMimic.py --arg_file args/run_humanoid3d_spinkick_args.txt

will run a pre-trained policy for a spinkick. Similarly,

python DeepMimic.py --arg_file args/kin_char_args.txt

will load and play a mocap clip.

To train a policy, run mpi_run.py by specifying an argument file and the number of worker processes.
For example,

will train a policy to perform a spinkick using 4 workers. As training progresses, it will regularly
print out statistics and log them to output/ along with a .ckpt of the latest policy.
It typically takes about 60 millions samples to train one policy, which can take a day
when training with 16 workers. 16 workers is likely the max number of workers that the
framework can support, and it can get overwhelmed if too many workers are used.

A number of argument files are already provided in args/ for the different skills.
train_[something]_args.txt files are setup for mpi_run.py to train a policy, and
run_[something]_args.txt files are setup for DeepMimic.py to run one of the pretrained policies.
To run your own policies, take one of the run_[something]_args.txt files and specify
the policy you want to run with --model_file. Make sure that the reference motion --motion_file
corresponds to the motion that your policy was trained for, otherwise the policy will not run properly.

Interface

the plot on the top-right shows the predictions of the value function

right click and drag will pan the camera

left click and drag will apply a force on the character at a particular location

scrollwheel will zoom in/out

pressing 'r' will reset the episode

pressing 'l' will reload the argument file and rebuild everything

pressing 'x' will pelt the character with random boxes

pressing space will pause/resume the simulation

pressing '>' will step the simulation one step at a time

Mocap Data

Mocap clips are located in data/motions/. To play a clip, first modify
args/kin_char_args.txt and specify the file to play with
--motion_file, then run

python DeepMimic.py --arg_file args/kin_char_args.txt

The motion files follow the JSON format. The "Loop" field specifies whether or not the motion is cyclic.
"wrap" specifies a cyclic motion that will wrap back to the start at the end, while "none" specifies an
acyclic motion that will stop once it reaches the end of the motion. Each vector in the "Frames" list
specifies a keyframe in the motion. Each frame has the following format:

Positions are specified in meters, 3D rotations for spherical joints are specified as quaternions (w, x, y ,z),
and 1D rotations for revolute joints (e.g. knees and elbows) are represented with a scalar rotation in radians. The root
positions and rotations are in world coordinates, but all other joint rotations are in the joint's local coordinates.
To use your own motion clip, convert it to a similar style JSON file.