https://github.com/user-attachments/assets/ecc9e9ec-e91f-4eba-927d-86322796459a
SUPRA-Tex generates textured 3D assets from a single image, preserving details
such as lettering, patterns, and material boundaries. It predicts PBR materials
in the reference view, encodes them as surface-aligned 3D observations, and
completes unseen regions with an Interleaved Flow Transformer. The output is
a relightable GLB with base color, metallic, and roughness textures.
- Image-aligned textures. Use visible surface observations to guide 3D
material generation and retain the details of the input image.
- Complete PBR assets. Generate materials for unseen surfaces and export
textures that support rendering under new lighting.
- Image-to-3D and mesh texturing. Generate an asset from an image, or texture
an existing mesh with matching camera and material observations.
Learn more on the project page, or try the
online demo.
Release Notes
Pretrained Models
Our models are openly available on Hugging Face.
| Model | Parameters | Download |
|---|
| SUPRA-Tex 3D Completion | 2.1B | completion |
| SUPRA-Tex Material Adapter | 33.6M trainable | material |
Installation
SUPRA-Tex requires Linux with an NVIDIA GPU, a CUDA 12.4 toolkit with
nvcc, Git, and a C++ compiler. The installer sets up a dedicated Python 3.10
Conda environment with PyTorch 2.6.0 and the native CUDA extensions:
git clone https://github.com/Supra-3D/SUPRA-Tex.git
cd SUPRA-Tex
conda create -n supra-tex python=3.10 -y
conda activate supra-tex
python scripts/install_runtime.py --conda
For faster attention, also install
FlashAttention: FlashAttention-2
on Ampere, Ada, or Hopper GPUs, and FlashAttention-3 on Hopper. Without it,
inference uses PyTorch SDPA; once installed, it is selected automatically. See the
installation guide
for the commands.
The full image-to-3D pipeline has been tested on an NVIDIA RTX 3090 (24 GB), where
CPU offload is enabled automatically. See the installation guide
for venv setup and manual installation, and
GPU compatibility for memory options.
Quick Start
1. Prepare the models. The SUPRA-Tex models
need no access request, but the image-to-3D pipeline also uses Meta's
DINOv3, which
requires access approval. Request access on its model page, log in with an
approved account, then download and assemble all models into ckpts/ready:
hf auth login
python scripts/prepare_models.py
By default the models are downloaded into ckpts/ready, which stays
self-contained. If your Hugging Face cache already holds some of them, add
--cache-dir ~/.cache/huggingface/hub to reuse it instead of downloading again.
Point it at the hub cache (HF_HUB_CACHE), not HF_HOME; ckpts/ready then
links to that cache, so keep it.
Add --with-rmbg to prepare RMBG-2
for opaque RGB inputs; images with a foreground alpha channel do not need it.
RMBG-2 also requires access approval. To avoid it, use the public
BiRefNet, which RMBG-2 is built on
and which loads the same way: download it and pass its directory with
--rmbg /path/to/BiRefNet instead of --with-rmbg.
2. Check the runtime and run the bundled example (the spiny whelk shell in
assets/):
python scripts/check_runtime.py
python scripts/run_example.py --output outputs/spiny_whelk_shell.glb
3. Generate a textured asset from your own image:
python scripts/run_example.py --input assets/metalwork_candle_jar.png \
--output outputs/metalwork_candle_jar.glb
This example uses the opaque RGB candle jar in assets/, so it needs
the RMBG-2 or BiRefNet model from step 1; replace --input with your own image.
The output is a GLB with base color, metallic, and roughness textures. A sibling
work directory keeps intermediate files and a run.json receipt.
Local web app. After installing the runtime and preparing the models above,
start the Gradio interface on a single GPU:
pip install -e '.[app]'
python app.py
Upload an RGB/RGBA image, choose a seed, then preview and download the GLB.
Low-memory mode and the depth pre-filter are enabled by default; texture
refinement is optional. RGB inputs need RMBG-2 or BiRefNet from step 1.
See the local web app guide for settings and remote access.
Texture an existing mesh. Given a mesh, its camera, a foreground image, and
reference-view material maps, complete the PBR textures directly. The repository
bundles the project-page pitcher plant mesh with its inputs in
assets/examples/pitcher_plant, the default
input of texturing.py:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
