wehub-resource-sync
303 lines
13 KiB
Markdown
303 lines
13 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/TencentARC/Pixal3D) · [上游 README](https://github.com/TencentARC/Pixal3D/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<div align="center">
|
||
|
||
# Pixal3D：从图像生成像素对齐的 3D（Pixel-Aligned 3D Generation from Images）
|
||
|
||
<h3>SIGGRAPH 2026</h3>
|
||
|
||
<small>[Dong-Yang Li](https://ldyang694.github.io/)¹ · [Wang Zhao](https://thuzhaowang.github.io/)²* · [Yuxin Chen](https://orcid.org/0000-0002-7854-1072)² · [Wenbo Hu](https://wbhu.github.io/)² · [Meng-Hao Guo](https://menghaoguo.github.io/)¹ · [Fang-Lue Zhang](https://fanglue.github.io/)³ · [Ying Shan](https://www.linkedin.com/in/YingShanProfile)² · [Shi-Min Hu](https://cg.cs.tsinghua.edu.cn/shimin.htm)¹✉</small>
|
||
|
||
¹清华大学 (BNRist) ²腾讯 ARC 实验室 ³惠灵顿维多利亚大学
|
||
|
||
*项目负责人 ✉通讯作者
|
||
|
||
</div>
|
||
|
||
<div align="center">
|
||
<a href="https://ldyang694.github.io/projects/pixal3d/"><img src=https://img.shields.io/badge/Project%20Page-333399.svg?logo=googlehome height=22px></a>
|
||
<a href="https://huggingface.co/spaces/TencentARC/Pixal3D"><img src=https://img.shields.io/badge/%F0%9F%A4%97%20Demo-276cb4.svg height=22px></a>
|
||
<a href="https://huggingface.co/TencentARC/Pixal3D"><img src=https://img.shields.io/badge/%F0%9F%A4%97%20Models-d96902.svg height=22px></a>
|
||
<a href="https://arxiv.org/abs/2605.10922"><img src=https://img.shields.io/badge/Arxiv-b5212f.svg?logo=arxiv height=22px></a>
|
||
<a href="LICENSE"><img src=https://img.shields.io/badge/License-MIT-yellow.svg height=22px></a>
|
||
</div>
|
||
|
||
<div align="center">
|
||
<img src="assets/teaser.png" alt="Pixal3D 预览图"/>
|
||
</div>
|
||
|
||
**Pixal3D** 可从单张图像生成高保真 3D 资产。与此前通过注意力机制松散注入图像特征的方法不同，Pixal3D 通过反投影（back-projection）将像素特征显式提升到 3D 空间，建立直接的像素到 3D 对应关系。这使得其能够达到接近重建级别的保真度，并具备精细的几何与 PBR 纹理。
|
||
|
||
---
|
||
|
||
## ✨ 动态
|
||
|
||
- **2026 年 5 月**：发布训练代码与数据准备工具包。🔧
|
||
- **2026 年 5 月**：发布基于 [Trellis.2](https://github.com/microsoft/TRELLIS.2) 骨干网络的改进版本。💪
|
||
- **2026 年 5 月**：发布推理代码与在线演示。🤗
|
||
- **2026 年 4 月**：论文被 SIGGRAPH 2026 接收！🎉
|
||
|
||
## 📌 分支
|
||
|
||
| 分支 | 说明 |
|
||
|--------|-------------|
|
||
| `main` | **最新版本**——基于 [Trellis.2](https://github.com/microsoft/TRELLIS.2) 骨干网络的改进实现，性能更优。 |
|
||
| `paper` | **论文版本**——基于 [Direct3D-S2](https://github.com/DreamTechAI/Direct3D-S2), 的原始实现，对应我们 SIGGRAPH 2026 论文中报告的结果。 |
|
||
|
||
> 若要复现我们论文中的结果，请切换到 `paper` 分支。
|
||
|
||
## 🎮 在线体验
|
||
|
||
您无需安装任何软件，即可通过我们的 Hugging Face Gradio 演示在浏览器中直接体验 Pixal3D：
|
||
|
||
👉 [**启动演示**](https://huggingface.co/spaces/TencentARC/Pixal3D)
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 安装
|
||
|
||
#### 步骤 1：按 TRELLIS.2 安装指南配置
|
||
|
||
请先按照 [TRELLIS.2](https://github.com/microsoft/TRELLIS.2) 的安装指南配置基础环境。
|
||
|
||
#### 步骤 2：安装额外依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
#### 步骤 3：安装 natten
|
||
|
||
```bash
|
||
NATTEN_CUDA_ARCH="xx" NATTEN_N_WORKERS=xx pip install natten==0.21.0 --no-build-isolation
|
||
```
|
||
|
||
请将 `xx` 替换为您机器适用的 CUDA 架构与编译并行 worker 数量。
|
||
|
||
#### 步骤 4：安装 utils3d
|
||
|
||
```bash
|
||
pip install https://github.com/LDYang694/Storages/releases/download/20260430/utils3d-0.0.2-py3-none-any.whl
|
||
```
|
||
|
||
> **注意**：`requirements-hfdemo.txt` 适用于 Hugging Face Spaces 演示（H 系列 GPU 架构），可能与其他架构不兼容。
|
||
|
||
### 使用方法
|
||
|
||
#### 推理
|
||
|
||
从单张图像生成 GLB 网格：
|
||
|
||
```bash
|
||
python inference.py --image assets/images/0_img.png --output ./output.glb
|
||
```
|
||
|
||
**低显存模式**（通过按需加载模型降低峰值显存占用）：
|
||
|
||
```bash
|
||
python inference.py --image assets/images/0_img.png --output ./output.glb --low_vram
|
||
```
|
||
|
||
默认流水线分辨率为 **1536**（标准模式）或 **1024**（低显存模式）。可通过 `--resolution` 覆盖：
|
||
|
||
```bash
|
||
# Force 1536 even in low-VRAM mode
|
||
python inference.py --image assets/images/0_img.png --output ./output.glb --low_vram --resolution 1536
|
||
|
||
# Force 1024 in standard mode
|
||
python inference.py --image assets/images/0_img.png --output ./output.glb --resolution 1024
|
||
```
|
||
|
||
**提示**：若未安装 `flash_attn`，可改用 PyTorch 内置的 SDPA 后端：
|
||
> ```bash
|
||
> ATTN_BACKEND=sdpa python inference.py --image assets/images/0_img.png --output ./output.glb --low_vram
|
||
> ```
|
||
|
||
### Web 演示
|
||
|
||
我们提供了 Pixal3D 的 Gradio Web 演示，支持以交互方式从图像生成 3D 网格。
|
||
|
||
```bash
|
||
python app.py
|
||
```
|
||
|
||
Web 演示同样支持低显存模式。前端默认分辨率在低显存模式下会自动切换为 1024（否则为 1536），也可在 UI 中手动修改。
|
||
|
||
```bash
|
||
python app.py --low_vram
|
||
# or via environment variable:
|
||
LOW_VRAM=1 python app.py
|
||
```
|
||
## 🔧 训练
|
||
|
||
我们提供完整的训练代码库，用于从零复现 Pixal3D。
|
||
|
||
### 数据准备
|
||
|
||
请按照数据工具包说明，准备视角对齐的 O-Voxel 数据与渲染条件图像：
|
||
|
||
> 📂 **[data_toolkit/README.md](data_toolkit/README.md)**
|
||
|
||
### 概览
|
||
|
||
Pixal3D 采用三阶段级联训练，每一阶段逐步提高分辨率：
|
||
|
||
| 阶段 | 模型 | 分辨率 | 配置前缀 |
|
||
|-------|-------|-------------|---------------|
|
||
| 1 | Sparse Structure | 32 → 64 | `ss_flow_img_dit_*_proj_finetune` |
|
||
| 2 | Shape | 256 → 512 → 1024 | `slat_flow_img2shape_*_proj_finetune` |
|
||
| 3 | Texture | 256 → 512 → 1024 | `slat_flow_imgshape2tex_*_proj_finetune` |
|
||
|
||
所有阶段均使用 **像素对齐投影条件（pixel-aligned projection conditioning）** 与 **视角对齐潜变量（view-aligned latents）**（默认 2 个视角）。在每个阶段内，从最低分辨率开始，通过在配置中设置 `finetune_ckpt`，逐步微调至更高分辨率。
|
||
|
||
### 快速开始
|
||
|
||
```sh
|
||
python train.py \
|
||
--config <CONFIG_JSON> \
|
||
--output_dir <OUTPUT_DIR> \
|
||
--data_dir '<DATA_DIR_JSON>'
|
||
```
|
||
|
||
`--data_dir` 是描述数据集布局的 JSON 字符串。不同阶段需要不同的键：
|
||
|
||
| 阶段 | 必需键 |
|
||
|-------|---------------|
|
||
| Sparse Structure | `base`, `ss_latent`, `render_cond` |
|
||
| Shape | `base`, `shape_latent`, `render_cond` |
|
||
| Texture | `base`, `shape_latent`, `pbr_latent`, `render_cond` |
|
||
|
||
### 示例：训练全部三个阶段
|
||
|
||
以下以 ObjaverseXL 为例展示完整训练流程。每个更高分辨率步骤都需要在其配置 JSON 中更新 `finetune_ckpt`，使其指向上一个检查点。
|
||
|
||
<details>
|
||
<summary><b>阶段 1：稀疏结构（32 → 64）</b></summary>
|
||
|
||
```sh
|
||
# Resolution 32
|
||
python train.py \
|
||
--config configs/gen/ss_flow_img_dit_1_3B_32_bf16_proj_finetune.json \
|
||
--output_dir results/ss_32 \
|
||
--data_dir '{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "ss_latent": "datasets/ObjaverseXL_sketchfab/ss_latents/ss_enc_conv3d_16l8_fp16_64_view", "render_cond": "datasets/ObjaverseXL_sketchfab/renders_cond"}}'
|
||
|
||
# Resolution 64 (set finetune_ckpt → results/ss_32 checkpoint)
|
||
python train.py \
|
||
--config configs/gen/ss_flow_img_dit_1_3B_32_bf16_proj_finetune_ft64.json \
|
||
--output_dir results/ss_ft64 \
|
||
--data_dir '{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "ss_latent": "datasets/ObjaverseXL_sketchfab/ss_latents/ss_enc_conv3d_16l8_fp16_64_view", "render_cond": "datasets/ObjaverseXL_sketchfab/renders_cond"}}'
|
||
```
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>阶段 2：形状（256 → 512 → 1024）</b></summary>
|
||
|
||
```sh
|
||
# Resolution 256
|
||
python train.py \
|
||
--config configs/gen/slat_flow_img2shape_dit_1_3B_256_bf16_proj_finetune.json \
|
||
--output_dir results/shape_256 \
|
||
--data_dir '{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "shape_latent": "datasets/ObjaverseXL_sketchfab/shape_latents/shape_enc_next_dc_f16c32_fp16_256_view", "render_cond": "datasets/ObjaverseXL_sketchfab/renders_cond"}}'
|
||
|
||
# Resolution 512
|
||
python train.py \
|
||
--config configs/gen/slat_flow_img2shape_dit_1_3B_256_bf16_proj_finetune_ft512.json \
|
||
--output_dir results/shape_ft512 \
|
||
--data_dir '{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "shape_latent": "datasets/ObjaverseXL_sketchfab/shape_latents/shape_enc_next_dc_f16c32_fp16_512_view", "render_cond": "datasets/ObjaverseXL_sketchfab/renders_cond"}}'
|
||
|
||
# Resolution 1024
|
||
python train.py \
|
||
--config configs/gen/slat_flow_img2shape_dit_1_3B_512_bf16_proj_finetune_ft1024.json \
|
||
--output_dir results/shape_ft1024 \
|
||
--data_dir '{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "shape_latent": "datasets/ObjaverseXL_sketchfab/shape_latents/shape_enc_next_dc_f16c32_fp16_1024_view", "render_cond": "datasets/ObjaverseXL_sketchfab/renders_cond"}}'
|
||
```
|
||
</details>
|
||
|
||
<details>
|
||
<summary><b>阶段 3：纹理（256 → 512 → 1024）</b></summary>
|
||
|
||
```sh
|
||
# Resolution 256
|
||
python train.py \
|
||
--config configs/gen/slat_flow_imgshape2tex_dit_1_3B_256_bf16_proj_finetune.json \
|
||
--output_dir results/tex_256 \
|
||
--data_dir '{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "shape_latent": "datasets/ObjaverseXL_sketchfab/shape_latents/shape_enc_next_dc_f16c32_fp16_256_view", "pbr_latent": "datasets/ObjaverseXL_sketchfab/pbr_latents/tex_enc_next_dc_f16c32_fp16_256_view", "render_cond": "datasets/ObjaverseXL_sketchfab/renders_cond"}}'
|
||
|
||
# Resolution 512
|
||
python train.py \
|
||
--config configs/gen/slat_flow_imgshape2tex_dit_1_3B_512_bf16_proj_finetune.json \
|
||
--output_dir results/tex_512 \
|
||
--data_dir '{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "shape_latent": "datasets/ObjaverseXL_sketchfab/shape_latents/shape_enc_next_dc_f16c32_fp16_512_view", "pbr_latent": "datasets/ObjaverseXL_sketchfab/pbr_latents/tex_enc_next_dc_f16c32_fp16_512_view", "render_cond": "datasets/ObjaverseXL_sketchfab/renders_cond"}}'
|
||
|
||
# Resolution 1024
|
||
python train.py \
|
||
--config configs/gen/slat_flow_imgshape2tex_dit_1_3B_512_bf16_proj_finetune_ft1024.json \
|
||
--output_dir results/tex_ft1024 \
|
||
--data_dir '{"ObjaverseXL_sketchfab": {"base": "datasets/ObjaverseXL_sketchfab", "shape_latent": "datasets/ObjaverseXL_sketchfab/shape_latents/shape_enc_next_dc_f16c32_fp16_1024_view", "pbr_latent": "datasets/ObjaverseXL_sketchfab/pbr_latents/tex_enc_next_dc_f16c32_fp16_1024_view", "render_cond": "datasets/ObjaverseXL_sketchfab/renders_cond"}}'
|
||
```
|
||
</details>
|
||
|
||
### 其他选项
|
||
|
||
<details>
|
||
<summary><b>所有命令行参数</b></summary>
|
||
|
||
| 参数 | 说明 | 默认值 |
|
||
|----------|-------------|---------|
|
||
| `--config` | 配置文件 JSON 路径 | *必填* |
|
||
| `--output_dir` | 输出目录 | *必填* |
|
||
| `--data_dir` | 数据集 JSON 字符串 | `./data/` |
|
||
| `--load_dir` | 检查点加载目录 | `output_dir` |
|
||
| `--ckpt` | 从指定步骤恢复 | `latest` |
|
||
| `--auto_retry` | 失败重试次数 | `3` |
|
||
| `--tryrun` | 试运行 | `false` |
|
||
| `--profile` | 性能分析 | `false` |
|
||
| `--num_nodes` | 节点数量 | `1` |
|
||
| `--node_rank` | 当前节点 rank | `0` |
|
||
| `--num_gpus` | 每节点 GPU 数量 | all |
|
||
| `--master_addr` | 主节点地址 | `localhost` |
|
||
| `--master_port` | 主节点端口 | `12666` |
|
||
| `--use_wandb` | 启用 W&B 日志记录 | `false` |
|
||
| `--wandb_project` | W&B 项目 | `trellis2-training` |
|
||
| `--wandb_name` | W&B 运行名称 | `output_dir` 的 basename |
|
||
| `--wandb_id` | W&B 运行 ID（恢复） | — |
|
||
|
||
</details>
|
||
|
||
## 🌐 社区项目
|
||
|
||
我们感谢社区为 Pixal3D 构建扩展与部署指南！
|
||
|
||
- [Pixal3D-ComfyUI](https://github.com/Saganaki22/Pixal3D-ComfyUI) — ComfyUI 集成，包含适用于 Windows、WSL 等环境的部署指南。
|
||
|
||
## 🤗 致谢
|
||
|
||
本项目大量借鉴了 [Trellis.2](https://github.com/microsoft/TRELLIS.2) 与 [Direct3D-S2](https://github.com/DreamTechAI/Direct3D-S2).。我们衷心感谢作者在可扩展 3D 生成（scalable 3D generation）方面的杰出工作，其为我们的代码库与模型架构奠定了基础。
|
||
|
||
我们也感谢以下仓库的杰出贡献：
|
||
|
||
- [Direct3D-S2](https://github.com/DreamTechAI/Direct3D-S2)
|
||
- [Trellis](https://github.com/microsoft/TRELLIS)
|
||
- [Trellis.2](https://github.com/microsoft/TRELLIS.2)
|
||
|
||
## 📄 引用
|
||
|
||
若您觉得本工作有帮助，欢迎引用：
|
||
|
||
```bibtex
|
||
@article{li2026pixal3d,
|
||
title={Pixal3D: Pixel-Aligned 3D Generation from Images},
|
||
author={Li, Dong-Yang and Zhao, Wang and Chen, Yuxin and Hu, Wenbo and Guo, Meng-Hao and Zhang, Fang-Lue and Shan, Ying and Hu, Shi-Min},
|
||
journal={arXiv preprint arXiv:2605.10922},
|
||
year={2026}
|
||
}
|
||
```
|
||
|
||
## 📜 许可证
|
||
|
||
本项目基于 [MIT License](LICENSE) 发布。本项目中包含的第三方组件仍按其各自原始条款授权；完整依赖列表及其许可证请参阅 [NOTICE](NOTICE)。
|