README.md

---
license: apache-2.0
tags:
- 3d
- 3d-editing
- asset-editing
- image-to-3d
- diffusion
pipeline_tag: image-to-3d
---

<p align="center">
  <img src="logo.png" alt="Alchemy3D" width="88" height="88" style="display:inline-block; vertical-align:middle; margin:0 12px 0 0;" />
  <span style="display:inline-block; vertical-align:middle; font-size:2.4em; font-weight:700; line-height:1;">Alchemy3D</span>
</p>
<p align="center">
  <b>Scaling Versatile 3D Assets Editing with a Million-Scale Dataset</b>
</p>

<p align="center">
  Badi Li<sup>1,2,4</sup>,
  <a href="https://tianxinhuang.github.io/">Tianxin Huang</a><sup>1</sup>,
  Yu Zhou<sup>3</sup>,
  <a href="https://isee-ai.cn/~zhwshi/">Wei-Shi Zheng</a><sup>2,4</sup>,
  <a href="https://www.cs.hku.hk/index.php/people/academic-staff/mayi">Yi Ma</a><sup>1,2</sup>,
  <a href="https://scholar.google.com/citations?user=fe-1v0MAAAAJ&hl=zh-CN">Shenghua Gao</a><sup>1,2†</sup>
</p>
<p align="center">
  <sup>1</sup> The University of Hong Kong &nbsp;&nbsp;
  <sup>2</sup> Shenzhen Loop Area Institute<br>
  <sup>3</sup> Shanghai Innovation Institute &nbsp;&nbsp;
  <sup>4</sup> Sun Yat-Sen University
</p>
<p align="center">
  <sup>†</sup> Corresponding author
</p>

<p align="center">
  <a href="https://libd1.github.io/Alchemy3D-Project/"><img src="https://img.shields.io/badge/Project-Page-0A7F5F.svg" alt="Project Page"></a>
  <a href="https://arxiv.org/abs/2609.34271"><img src="https://img.shields.io/badge/arXiv-Paper-b31b1b.svg" alt="arXiv"></a>
  <a href="https://arxiv.org/pdf/2609.34271"><img src="https://img.shields.io/badge/Paper-PDF-red.svg" alt="PDF"></a>
  <a href="https://github.com/libd1/Alchemy3D"><img src="https://img.shields.io/badge/Code-GitHub-black.svg" alt="GitHub"></a>
  <a href="https://huggingface.co/libadi/Alchemy3D"><img src="https://img.shields.io/badge/🤗-Model-yellow.svg" alt="Hugging Face Model"></a>
  <a href="https://modelscope.cn/models/libd55/Alchemy3D"><img src="https://img.shields.io/badge/-Model-624AFF.svg?logo=modelscope&logoColor=white&labelColor=555" alt="ModelScope Model"></a>
  <a href="https://huggingface.co/datasets/libadi/Alchemy3D-1M"><img src="https://img.shields.io/badge/🤗-Alchemy3D--1M-yellow.svg" alt="Dataset"></a>
  <a href="https://huggingface.co/datasets/libadi/GEdit3D-Bench"><img src="https://img.shields.io/badge/🤗-GEdit3D--Bench-yellow.svg" alt="Benchmark"></a>
  <a href="https://github.com/libd1/edit3dstudio"><img src="https://img.shields.io/badge/-evaluation-black.svg?logo=github&logoColor=white&labelColor=555" alt="Evaluation"></a>
</p>

<p align="center">
  <img src="teaser.png" alt="Alchemy3D teaser: addition, removal, replacement, local/global appearance, and animation." width="100%" />
</p>

**Alchemy3D** is the primary checkpoint of an open-sourced foundation model for **editing existing 3D assets** while preserving identity and structure. Given a source mesh (e.g. `.glb`) and a target reference image, it performs versatile edits including Addition, Removal, Replacement, Local/Global Appearance, and Animation.

The model is trained on **[Alchemy3D-1M](https://huggingface.co/datasets/libadi/Alchemy3D-1M)** (1.25M unique assets, 1.38M edit pairs, 7 edit types) and builds on [TRELLIS.2](https://github.com/microsoft/TRELLIS.2) structured latents.

## Model Variants

Weights are mirrored on Hugging Face and ModelScope. If Hugging Face is unreachable, load the ModelScope IDs below — the official code falls back automatically.

| Model | Description | Hugging Face | ModelScope |
| :--- | :--- | :--- | :--- |
| **Alchemy3D** | Primary image-conditioned editing model | [libadi/Alchemy3D](https://huggingface.co/libadi/Alchemy3D) | [libd55/Alchemy3D](https://modelscope.cn/models/libd55/Alchemy3D) |
| **Alchemy3D-Turbo** | Step-distilled variant for faster inference with competitive quality | [libadi/Alchemy3D-Turbo](https://huggingface.co/libadi/Alchemy3D-Turbo) | [libd55/Alchemy3D-Turbo](https://modelscope.cn/models/libd55/Alchemy3D-Turbo) |
| **Alchemy3D-Flux** | Replaces DINOv3 with a Flux2 encoder for stronger PBR / appearance editing | [libadi/Alchemy3D-Flux](https://huggingface.co/libadi/Alchemy3D-Flux) | [libd55/Alchemy3D-Flux](https://modelscope.cn/models/libd55/Alchemy3D-Flux) |
| **Alchemy3D-Instruct** | Instruction-driven editing from natural-language text instead of a target image | [libadi/Alchemy3D-Instruct](https://huggingface.co/libadi/Alchemy3D-Instruct) | [libd55/Alchemy3D-Instruct](https://modelscope.cn/models/libd55/Alchemy3D-Instruct) |
| **Alchemy3D-Segment** | Downstream 3D part segmentation from 1–8 multi-view 2D segmentation maps | [libadi/Alchemy3D-Segment](https://huggingface.co/libadi/Alchemy3D-Segment) | [libd55/Alchemy3D-Segment](https://modelscope.cn/models/libd55/Alchemy3D-Segment) |

## Quick Start

Install and run from the [official repository](https://github.com/libd1/Alchemy3D).

```python
from alchemy3d.pipelines import Pipeline
import o_voxel

pipe = Pipeline.from_pretrained("libadi/Alchemy3D")
pipe.cuda()

output = pipe.run(
    source="./assets/examples/edits/01/source.glb",
    image="./assets/examples/edits/01/target_image.png",
    comparison_video="example.mp4",
)[0]

glb = o_voxel.postprocess.to_glb(
    vertices=output.vertices,
    faces=output.faces,
    attr_volume=output.attrs,
    coords=output.coords,
    attr_layout=output.layout,
    voxel_size=output.voxel_size,
    aabb=[[-0.5, -0.5, -0.5], [0.5, 0.5, 0.5]],
    decimation_target=1_000_000,
    texture_size=4096,
    remesh=True,
    remesh_band=1,
    remesh_project=0,
    verbose=False,
)
glb.export("example.glb")
```

> **Hardware:** NVIDIA GPU recommended; ~24GB VRAM is a practical minimum. See the [GitHub README](https://github.com/libd1/Alchemy3D) for full environment setup (`setup.sh`).

## Citation

If you use Alchemy3D, please cite:

```bibtex
@misc{li2026scalingversatile3dassets,
      title={Scaling Versatile 3D Assets Editing with a Million-Scale Dataset}, 
      author={Badi Li and Tianxin Huang and Yu Zhou and Wei-Shi Zheng and Yi Ma and Shenghua Gao},
      year={2026},
      eprint={2609.34271},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2609.34271}, 
}
```

## License

Apache License 2.0. See the [GitHub repository](https://github.com/libd1/Alchemy3D) for dependency licenses (O-Voxel / TRELLIS.2, nvdiffrast, nvdiffrec, etc.).