<h1 align="center">[ICCV 2025] GUAVA: Generalizable Upper Body 3D Gaussian Avatar</h1> <a href="https://github.com/EastbeanZhang">Dongbin Zhang</a>1,2, <a href="https://liuyunfei.net/">Yunfei Liu</a>2†, <a href="https://scholar.google.com/citations?hl=en&user=Xf5_TfcAAAAJ">Lijian Lin</a>2, <a href="https://scholar.google.com/citations?hl=en&user=qhp9rIMAAAAJ">Ye Zhu</a>2, <a href="None">Yang Li</a>1, <a href="https://github.com/minghanqin">Minghan Qin</a>1, <a href="https://yu-li.github.io/">Yu Li</a>2‡, <a href="https://www.sigs.tsinghua.edu.cn/whq_en/main.htm">Haoqian Wang</a>1† ( 1Tsinghua University, 2International Digital Economy Academy ) <div style="text-align: center;">

</div>

🗓️ Roadmap

Here's our current progress and upcoming plans for the GUAVA:

Inference Code: Released on August 10, 2025 ☑️
Tracking Code: Released on October 08, 2025 ☑️
Training Code: Released on October 08, 2025 ☑️

📌 Introduction

This repository contains the official author's implementation associated with the paper "GUAVA: Generalizable Upper Body 3D Gaussian Avatar".

With just a single image and a tracked pose, GUAVA can generate a 3D upper-body Gaussian avatar in sub-second time via feed-forward inference, enabling real-time expressive animation.

<img src="assets/Docs/teaser.png" alt="Teaser image" style="background:white; padding:10px; border-radius:10px;" />

🛠️ Setup

This guide outlines the steps to set up and run the project components, which have been tested on Ubuntu Linux 20.04.

Cloning the Repository

# Via SSH
git clone git@github.com:Pixel-Talk/GUAVA.git --recursive
or
# Via HTTPS 
git clone https://github.com/Pixel-Talk/GUAVA.git --recursive

cd GUAVA

Hardware Requirements

GPU: CUDA-ready GPU with Compute Capability 7.0 or higher.
VRAM: At least 6GB of VRAM for inference or 48GB to achieve paper-quality training results.

Software Requirements

Python: Version 3.10
CUDA SDK: Version 11 (specifically tested with 11.8) for PyTorch extensions.
C++ Compiler: Must be compatible with your installed CUDA SDK.

Environment Setup

Our default, provided install method is based on Conda package and environment management:

# Create and Activate Conda Environment:
conda create --name GUAVA python=3.10
conda activate GUAVA

# Install Core Dependencies:
pip install -r requirements.txt

# Install PyTorch3D:
pip install "git+https://github.com/facebookresearch/pytorch3d.git@v0.7.7"

# Install Submodule Dependencies:
cd submodules
pip install diff-gaussian-rasterization-32
pip install simple-knn
pip install fused-ssim
cd ..

📦 Model Preparation

Parametric Models:

SMPLX: Download SMPLX_NEUTRAL_2020.npz from SMPLX and place it in the assets/SMPLX.
FLAME: Download the generic_model.pkl from FLAME2020. Save this file to both assets/FLAME/FLAME2020/generic_model.pkl and assets/SMPLX/flame_generic_model.pkl.

For inference:

To run inference, you will need to acquire the following:

Manual Download:
- GUAVA Pretrained Model Weight: Download the pretrained weight, unzip the file, and place it in the assets/GUAVA.
- Example Tracked Videos: Donwnload some tracked example videos for inference. Unzip the downloaded files and place them in the assets/example.
Command-line Download:
```
bash assets/Docs/run_download.sh
```

🚀 Inference Scripts

Execute the following command to perform self-reenactment:

 python main/test.py \
 -d '0' \
 -m assets/GUAVA \
 -s outputs/example \
 --data_path assets/example/tracked_video/6gvP8f5WQyo__056

Execute this command to perform cross-reenactment, transferring the motion and expression from a target video to the person in a source image:

 python main/test.py \
 -d '0' \
 -m assets/GUAVA \
 -s outputs/example \
 --data_path assets/example/tracked_video/6gvP8f5WQyo__056 \
 --source_data_path assets/example/tracked_image/NTFbJBzjlts__047 \
 --skip_self_act \
 --render_cross_act

🎯 Tracking

To process your own videos, images, or to build a custom tracking training dataset, you will need to use our EHM-Tracker.

Navigate into the EHM-Tracker directory and follow the instructions provided in its README.md file for detailed guidance.

🚂 Training Scripts

You can use the EHM-Tracker to build your own dataset.

Once your dataset is prepared, run the following command to train your own GUAVA model.

python main/train.py -c train/ubody_512 -d '0,1'

🖥️ Interface Demo

After setting up the environment, necessary files, and the EHM-Tracker, you can try our interactive demo by running:

python app.py

GUAVA Interface Demo

📖 BibTeX

If you find our work helpful, please ⭐ our repository and cite:

@article{GUAVA,
  title={GUAVA: Generalizable Upper Body 3D Gaussian Avatar},
  author={Zhang, Dongbin and Liu, Yunfei and Lin, Lijian and Zhu, Ye and Li, Yang and Qin, Minghan and Li, Yu and Wang, Haoqian},
  journal={arXiv preprint arXiv:2505.03351},
  year={2025}
}

🙏 Acknowledgement

We sincerely appreciate the contributions of the research community that made this work possible.

Our implementation is built upon the PyTorch framework for 3D Gaussian Splatting from GraphDeco-Inria. We thank the authors for their open-source efforts and inspiring research.

We also acknowledge the developers and maintainers of the following projects, which played a crucial role in our implementation:

diff-gaussian-rasterization: The differentiable Gaussian rasterization library, essential for rendering.
FLAME: A 3D head parametric model.
SMPLX: A 3D human parametric model.

Finally, we thank our collaborators, colleagues, and the open-source community for their valuable discussions and continuous support.

GUAVA

Install / Use

README