README.md

---
title: TRELLIS.2 Multi-Image Conditioning
emoji: 🧊
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.12.0
app_file: app.py
pinned: false
license: mit
short_description: Multi-view image to 3D generation
---

# TRELLIS.2 Multi-Image Conditioning Fork

This fork extends [TRELLIS.2](https://github.com/microsoft/TRELLIS.2) with multi-image conditioning and Windows support.

## What's New

- **Multi-image conditioning**: Use multiple views for better 3D reconstruction
- **Windows support**: Runs on Windows with automatic `sdpa` attention fallback

> For the interactive visualization tool, see the [viser_view branch](https://github.com/OpsiClear/Trellis2_multi_image_conditioning/tree/viser_view).

## Installation

```sh
git clone https://github.com/OpsiClear/Trellis2_multi_image_conditioning.git --recursive
cd Trellis2_multi_image_conditioning
. ./setup.sh --new-env --basic --flash-attn --nvdiffrast --nvdiffrec --cumesh --o-voxel --flexgemm
```

> On Windows, `flash-attn` is unavailable. The code automatically falls back to PyTorch's native `sdpa` backend.

## Usage

### Multi-Image Generation

```python
from trellis2.pipelines import Trellis2ImageTo3DPipeline
from PIL import Image

pipeline = Trellis2ImageTo3DPipeline.from_pretrained("microsoft/TRELLIS.2-4B")
pipeline.cuda()

# Load multiple views
images = [Image.open(f"view_{i}.png") for i in range(4)]

# Generate with multi-image conditioning
mesh = pipeline.run_multi_image(images)[0]
```

Or run the example:
```sh
python example_multi_image.py
```

### Other Examples

```sh
python example.py           # Single image generation
python app.py               # Gradio web demo
python example_texturing.py # PBR texture generation
python app_texturing.py     # Texture generation web demo
```

## Attribution

This project is a fork of [TRELLIS.2](https://github.com/microsoft/TRELLIS.2) by Microsoft Corporation, originally released under the MIT License.

For full documentation, training instructions, and model details, see the original repository.

If you use this code, please cite the original paper:

```bibtex
@article{xiang2025trellis2,
    title={Native and Compact Structured Latents for 3D Generation},
    author={Xiang, Jianfeng and Chen, Xiaoxue and Xu, Sicheng and Wang, Ruicheng and Lv, Zelong and Deng, Yu and Zhu, Hongyuan and Dong, Yue and Zhao, Hao and Yuan, Nicholas Jing and Yang, Jiaolong},
    journal={Tech report},
    year={2025}
}
```

## Third-Party Model Licenses

This project uses several third-party models with different licenses. **Some licenses prohibit commercial use.** See [MODEL_LICENSES.md](MODEL_LICENSES.md) for full details.

| Model | License | Commercial Use |
|---|---|---|
| [TRELLIS.2-4B](https://huggingface.co/microsoft/TRELLIS.2-4B) | MIT | Yes* |
| [BRIA RMBG-2.0](https://huggingface.co/briaai/RMBG-2.0) | CC BY-NC 4.0 | **No** |
| [DINOv2](https://github.com/facebookresearch/dinov2) | Apache 2.0 | Yes |
| [BiRefNet](https://github.com/ZhengPeng7/BiRefNet) | MIT | Yes |

*\* Depends on nvdiffrast/nvdiffrec (NVIDIA Source Code License, non-commercial only)*

Original license files are included in the [`licenses/`](licenses/) directory.

## License

The original TRELLIS.2 code is MIT licensed by Microsoft Corporation. New additions in this fork (multi-image conditioning) are licensed under [AGPL-3.0](LICENSE).