[ICCV 2025] GUAVA: Generalizable Upper Body 3D Gaussian Avatar

Dongbin Zhang^1,2, Yunfei Liu^2†, Lijian Lin², Ye Zhu², Yang Li¹, Minghan Qin¹, Yu Li^2‡, Haoqian Wang^1†
( ¹Tsinghua University, ²International Digital Economy Academy )

🗓️ 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.

🛠️ 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 [email protected]: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/[email protected]"

# 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

📖 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.