Add Model Card

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+logo.png filter=lfs diff=lfs merge=lfs -text
+teaser.png filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,132 @@
+---
+license: apache-2.0
+library_name: alchemy3d
+tags:
+  - 3d
+  - 3d-editing
+  - asset-editing
+  - image-to-3d
+  - diffusion
+pipeline_tag: image-to-3d
+---
+
+<h1 align="center">
+  <img src="logo.png" alt="Alchemy3D" width="88" height="88" valign="middle" />
+  Alchemy3D
+</h1>
+<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** (this repo) | 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) |
+
+- **Alchemy3D / Turbo / Flux** share the same image-conditioned editing API (`Pipeline.from_pretrained(...)`); swap the model ID to switch variants.
+- **Alchemy3D-Instruct** uses `Alchemy3DInstructPipeline` with a text `instruction` string.
+- **Alchemy3D-Segment** uses `Alchemy3DSegmentPipeline` and returns part meshes / labels.
+
+## Quick Start
+
+Install and run from the [official repository](https://github.com/libd1/Alchemy3D). Drop-in alternatives for the same image-conditioned API: `libadi/Alchemy3D-Turbo`, `libadi/Alchemy3D-Flux` (or the ModelScope IDs above).
+
+```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")
+```
+
+Instruction editing and part segmentation use dedicated pipelines — see [`example-instruct.py`](https://github.com/libd1/Alchemy3D/blob/main/example-instruct.py) and [`example_segment.py`](https://github.com/libd1/Alchemy3D/blob/main/example_segment.py).
+
+> **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.).