add animation codes, update dependency

Author: alvinliu0

README.md

@@ -12,13 +12,19 @@ Realistic 3D human generation from text prompts is a desirable yet challenging t
 <img src='./content/teaser-1.png' width=800>
 <img src='./content/teaser-2.png' width=800>
 
+## News
+
+* [2023-12-05] Update the real-time animation demo and codes!
+
+* [2023-11-28] Upload the paper. Release all the training codes and pretrained models!
+
 ## Installation
 ```
 # clone the github repo
 git clone https://github.com/alvinliu0/HumanGaussian.git
 cd HumanGaussian
 
-pip install torch==2.0.1+cu117 torchvision==0.15.2+cu117 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cu117
+pip install torch==2.0.1+cu118 torchvision==0.15.2+cu118 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cu118
 pip install -r requirements.txt
 
 # a modified gaussian splatting (+ depth, alpha rendering)
@@ -52,6 +58,60 @@ python launch.py --config configs/test.yaml --train --gpu 0 system.prompt_proces
 
 Though the **HumanGaussian framework** is trained on a single body pose at the training stage, it can be animated with unseen pose sequences in a zero-shot manner, *i.e.*, we can use a sequence of SMPL-X pose parameters to animate the pre-trained avatars w/o further finetuning.
 
+<img src='./content/animation-realtime.gif' width=800>
+
+### Animation-Related Installation
+We rely on some extra dependencies:
+```bash
+# for GUI
+pip install dearpygui
+
+# cubvh
+pip install git+https://github.com/ashawkey/cubvh
+
+# a modified gaussian splatting (+ depth, alpha rendering)
+git clone --recursive https://github.com/ashawkey/diff-gaussian-rasterization
+pip install ./diff-gaussian-rasterization
+
+# nvdiffrast
+pip install git+https://github.com/NVlabs/nvdiffrast/
+
+# kiuikit
+pip install -U git+https://github.com/ashawkey/kiuikit
+
+# smplx
+pip install smplx[all]
+# please also download SMPL-X files to ./smplx_models/smplx/*.pkl
+```
+
+### Animation-Related Usage
+
+Gaussian files are generated by HumanGaussian and saved as ply files.
+Motions should follow the SMPL-X body pose format (21 joints), which could read by:
+```python
+motion = np.load('content/amass_test_17.npz')['poses'][:, 1:22, :3]
+# motion = np.load('content/Aeroplane_FW_part9.npz')['poses'][:, 1:22, :3]
+```
+
+Then, perform the zero-shot animating by:
+```bash
+# visualize in gui
+python animation.py --ply <path/to/ply> --motion <path/to/motion> --gui
+
+# play motion and save to videos/xxx.mp4
+python animation.py --ply <path/to/ply> --motion <path/to/motion> --play
+
+# also self-rotate during playing
+python animation.py --ply <path/to/ply> --motion <path/to/motion> --play --rotate
+```
+
+For example, you can animate the "A boy with a beanie wearing a hoodie and joggers" avatar with some sample motions as:
+```bash
+# play motion and save to .mp4 for "A boy with a beanie wearing a hoodie and joggers" case
+python animation.py --ply "content/sample.ply" --motion "content/Aeroplane_FW_part9.npz" --play
+```
+
+
 ## Acknowledgement
 This work is built on many amazing research works and open-source projects, including [Threestudio](https://github.com/threestudio-project/threestudio), [3DGS](https://github.com/graphdeco-inria/gaussian-splatting), [diff-gaussian-rasterization](https://github.com/graphdeco-inria/diff-gaussian-rasterization), [GaussianDreamer](https://github.com/hustvl/GaussianDreamer). Thanks a lot to all the authors for sharing!