SUPRA-Tex

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

• 🛡️ [2026-10-29] Added a default-on depth pre-filter for single-view image-to-3D, improving robustness to texture leakage near occlusion boundaries. See the comparison and usage.
• 🔥 [2026-10-19] Inference code released for image-to-3D and mesh texturing, along with a training overview.
• 🎨 [2026-10-18] The SUPRA-Tex Studio is open for a tour.
• 📄 [2026-10-16] Project page and paper released.

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:

python texturing.py --pipeline supra3d/supra-tex --output outputs/pitcher_plant_textured.glb

Pass --input-dir to texture your own mesh; see texturing for the input format.

Improving Results

The defaults suit most inputs. When a result falls short, these options help; for run time, see Inference Speed.

• Reduce texture leakage. The depth pre-filter is enabled by default for single-view image-to-3D. It rejects unreliable material observations near occlusion boundaries before completion. In the eel-machine example below, the yellow streak extending from the motor support onto the dark base is removed while the brass motor retains its color. Use --no-filter to disable it; see details and its relation to refinement.

  Same input geometry, camera, reference materials, and seed 42; both results are shown before --refine. The close-ups highlight the motor/base boundary.

• Refine fine detail. For very small, intricate text and textures, add --refine. After export, it further refines the visible texture and aligns it with the input image. Refinement adds about two minutes on an RTX 3090, so it is off by default. In this example, the wiring table on the industrial disconnect switch packs a specification table, circuit symbols, and fine caution print into one label:

  python scripts/run_example.py --input assets/industrial_disconnect_switch.png \
    --output outputs/wiring_table.glb --refine
  

• Start from a clean input. Use a sharp image of one object that is fully in frame and fills most of it: the image is reduced to 1024 pixels on its longest side before cropping to the object, so a small object in a large frame loses detail. Prefer an RGBA image with a clean foreground alpha to automatic background removal. Only pixels with alpha of at least 254 serve as texture observations, so soft or noisy edges leave more to completion.

• Check the alignment report. Each run prints an Observation: silhouette IoU line that compares the geometry with the image foreground, with a warning below 0.9. Mismatched regions take their texture from completion rather than the image. Add --geometry-scale-search to calibrate the mesh scale, or try another --seed to resample geometry and completion.

• Handle extra geometry. Pixal3D geometry is sometimes misaligned with the image or carries extra pieces, which then receive texture the image never showed. Image-to-3D runs remove disconnected pieces that project mostly outside the image foreground before completion (--no-remove-floaters keeps them; texturing.py applies it with --remove-floaters). It keeps everything the foreground covers, so it does not remove pieces hidden behind the object or extra geometry attached to it. For those, try another , or clean the mesh yourself and texture it with .

Make It Yours

Single-view inference observes only what the reference image shows; everything else comes from completion. Dual-view texturing adds a second, generated observation of the back so that the unseen side also follows an image. It works in five stages, each a separate command in dual-view texturing:

1. Front inputs. The image-to-3D frontend produces the mesh, camera, and reference-view material maps, recording which models produced them.
2. Back normal pack. The mesh is rendered from a back camera chosen around the opposite view, as a normal map and silhouette mask that share the same rasterization.
3. Back image. An image generator paints a back view that follows the normal pack, and a visual review labels it. acceptable and needs_review may continue after all hard checks pass; needs_regeneration remains blocked. Review labels and defects are retained in downstream records. Our implementation runs GPT-6 Astra with its built-in image generation tool through the external Codex CLI; this is the only stage outside this repository.
4. Back materials. The accepted image is cut to the rendered silhouette, and the same material adapter predicts its albedo and metallic/roughness maps.
5. Completion and refinement. Both views become surface observations, with the front taking priority where they overlap, and a single completion run fills the rest. Refinement then projects each view into the texture atlas and repairs the UV gutters.

The back image is the creative part: it decides what the unseen side looks like. Stages 1, 2, 4, and 5 run locally, so the pipeline is ready for another back-view generator. As foundation image models improve, dual-view results can improve with them. See dual-view texturing for requirements and the staged commands.

Documentation

Guide	Contents
Quick start	Installation, model preparation, and the first run in detail
Local web app	Gradio interface, single-GPU settings, and remote access
Method overview	Pipeline stages and where each is implemented
Training overview	Data preparation and training workflow
End-to-end inference	All infer.py options
Material frontend	Foreground, camera, and reference-view material maps
Geometry	Pixal3D geometry generation and optional scale search
Texturing	texturing.py inputs and options
Dual-view texturing	Front/back observation fusion with a generated back view; back-view generation uses GPT-6 Astra through the external Codex CLI
Model weights	Model layouts and external dependencies
GPU compatibility

Inference Speed

Most inference time on modest hardware goes to reading weights and moving them between CPU and GPU, not to model compute. These settings help:

• Install FlashAttention. FlashAttention-2, or FlashAttention-3 on Hopper, is faster than the PyTorch SDPA fallback and is selected automatically once installed (commands).

• Keep weights on an SSD. The geometry and Qwen stages read tens of gigabytes of weights per run. On a hard disk, loading dominates both stages; an SSD cuts their load time by more than half.

• Use a GPU with at least 48 GB. GPUs with up to 24 GiB enable CPU offload automatically, which moves the Qwen model block by block during inference. Larger GPUs keep models resident, and the Qwen stage becomes much faster.

• Use two GPUs. The geometry and Qwen material stages are independent. --parallel-frontend runs them concurrently on the first two visible GPUs; CUDA_VISIBLE_DEVICES selects which ones. Both stages then hold their models in CPU memory at the same time, so check host RAM when offload is enabled.

• Store geometry weights in their runtime precision. The geometry flow checkpoints store float32 for blocks that run in bfloat16. Writing cast copies once halves the bytes read on every run and gives identical results:

  python scripts/convert_geometry_weights.py
  

  The copies (about 8 GB) are saved beside the originals and used automatically.

• Geometry scale search is optional. By default, geometry follows Pixal3D with a fixed mesh scale. --geometry-scale-search enables a bounded scale calibration that adds one sampling pass per probe (up to three).

• Pre-tuned sparse-convolution kernels apply only to H800. On H800 with PyTorch 2.6 (CUDA 12.4), Triton 3.2, and FlexGEMM 1.0, a measured kernel configuration is loaded. Other GPUs autotune these kernels on first use.

Acknowledgments

Our implementation builds on TRELLIS.2 and Pixal3D. We also thank the authors of Qwen-Image, FireRed-Image-Edit, MoGe, NAF, CuMesh, FlexGEMM, and nvdiffrast for making their work available.

License

Original SUPRA-Tex source code and the 3D completion weights are released under the MIT License. The repository also includes third-party code under MIT, Apache-2.0, and the DINOv3 License; THIRD_PARTY_NOTICES.md lists each component and its terms. Built with Qwen: the material adapter uses the Qwen Research License for non-commercial research and evaluation. External models retain their respective licenses.

Citation

If you find this work useful for your research, please cite:

@article{yang2026supratex,
  title   = {{SUPRA-Tex}: 3D Generation with Super-Aligned Texture},
  author  = {Yang, Chen and Fang, Jiemin and Meng, Fanpeng and Huang, Zihao
             and Pang, Jichen and Wu, Guanjun and Bao, Zhikuan and Tian, Qi},
  journal = {arXiv preprint arXiv:2610.22352},
  year    = {2026},
  url     = {https://arxiv.org/abs/2610.22352}
}