CAT: Character Animation Tools for Python

This repository includes scripts for Character Animation. All the code is written entirely in python.

It is useful for pre-processing and post-processing motions in Deep Learning.
It will be also useful for create character animations.

⭐ Requirements

I tested on python3.10 (for match-case syntax).

Package

• NumPy
• SciPy
• matplotlib
• chumpy (if you use vanilla SMPL for AIST++).
• easydict

Motion Data

Some of the scripts in this repository need motion data below.
Please download them and place them in data/ or link them as symbolic links at data/. For more information please see data/data.md.

• Ubisoft La Forge Animation Dataset (LAFAN1)
• SMPL
• SMPL+H
• SMPL-X
• AMASS
• AIST++

❓ How to use?

1. Load and Save Animation

open

1.1 Load Animation from bvh file.

from anim import bvh
from anim.animation import Animation
anim_bvh: Animation = bvh.load(filepath="data/**.bvh")

1.2 Load Animation from AIST++.

You need to install chumpy to use vanilla SMPL model.

from anim import aistpp
anim: Animation = aistpp.load(
    aistpp_motion_path="data/aistpp/**.pkl",
    smpl_path="data/smpl/neutral/model.pkl"
)

1.3 Load Animation from AMASS.

I recommend you to download extended SMPL+H model (16 beta components).

from anim import amass
anim: Animation = amass.load(
    amass_motion_path="data/amass/**.npz",
    smplh_path="data/smplh/neutral/model.npz"
)

1.4 Save as bvh.

You can convert SMPL based motion files (AIST++, AMASS) to BVH files.

from anim import bvh
from anim.animation import Animation

...

anim: Animation
bvh.save(
    filepath="data/***.bvh",
    anim=anim
)

2. Get motion features

open

2.1 Get positions (global, root-centric, character space).

import numpy as np
from anim.animation import Animation

...

anim: Animation
global_positions: np.ndarray = anim.gpos
rcentric_positions: np.ndarray = anim.rtpos
cspace_positions: np.ndarray = anim.cpos

2.2 Get velocities(positions, rotations).

anim: Animation
pos_velocities: np.ndarray = anim.gposvel
rot_velocities: np.ndarray = anim.lrotvel

2.3 Get mirrored Animation.

(caution: Skel offsets must be symmetric.)

anim: Animation
anim_M: Animation = anim.mirror()

3. Inverse Kinematics

open

3.1 Two bone IK

Analytical method of foot IK example (define heels positon and knees forward vector).

python anim/inverse_kinematics/two_bone_ik.py

3.2 CCD-IK

Simple demo.

python anim/inverse_kinematics/ccd_ik.py

3.3 FABRIK

Simple demo.

python anim/inverse_kinematics/fabrik.py

4. Motion Blending

open

4.1 Linear blending for pose.

TBD

5. Motion Matching

open

5.1 Character Control by predefined trajectories

python test/path_following.py

👀 Notification

• util/quat.py inspired by Motion-Matching.
• This repository is MIT licensed, but some datasets requires a separate license. Please check them.

💬 Contact

This repository is under construction.
Feel free to contact me on issue.

📚License

This code is distributed under an MIT LICENSE.