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.
## :star: 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/`](data) or link them as symbolic links at [`data/`](data). For more information please see [`data/data.md`](data/data.md).
* [Ubisoft La Forge Animation Dataset (LAFAN1)](https://github.com/ubisoft/ubisoft-laforge-animation-dataset)
* [SMPL](https://smpl.is.tue.mpg.de/)
* [SMPL+H](https://mano.is.tue.mpg.de/)
* [SMPL-X](https://smpl-x.is.tue.mpg.de/)
* [AMASS](https://amass.is.tue.mpg.de/)
* [AIST++](https://google.github.io/aistplusplus_dataset/factsfigures.html)
## :question: How to use?
### 1. Load and Save Animation
open
#### 1.1 Load Animation from [bvh](https://research.cs.wisc.edu/graphics/Courses/cs-838-1999/Jeff/BVH.html) file.
```Python
from anim import bvh
from anim.animation import Animation
anim_bvh: Animation = bvh.load(filepath="data/**.bvh")
```
#### 1.2 Load Animation from [AIST++](https://google.github.io/aistplusplus_dataset/factsfigures.html).
You need to install chumpy to use vanilla SMPL model.
```Python
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](https://amass.is.tue.mpg.de/).
I recommend you to download extended SMPL+H model (16 beta components).
```Python
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.
```Python
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).
```Python
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).
```Python
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.)
```Python
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).
```bash
python anim/inverse_kinematics/two_bone_ik.py
```
#### 3.2 CCD-IK
Simple demo.
```bash
python anim/inverse_kinematics/ccd_ik.py
```
#### 3.3 FABRIK
Simple demo.
```bash
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
python test/path_following.py
```
## :eyes: Notification
* [`util/quat.py`](util/quat.py) inspired by [Motion-Matching](https://github.com/orangeduck/Motion-Matching).
* This repository is MIT licensed, but some datasets requires a separate license. Please check them.
## :speech_balloon: Contact
This repository is under construction.
Feel free to contact me on [issue](https://github.com/KosukeFukazawa/CharacterAnimationTools/issues).
## :books:License
This code is distributed under an [MIT LICENSE](LICENSE).