> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/TencentARC/Pixal3D) · [上游 README](https://github.com/TencentARC/Pixal3D/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
# Pixal3D：从图像生成像素对齐的 3D（Pixel-Aligned 3D Generation from Images）

SIGGRAPH 2026

[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)¹✉ ¹清华大学 (BNRist)    ²腾讯 ARC 实验室    ³惠灵顿维多利亚大学 *项目负责人    ✉通讯作者
Pixal3D 预览图
**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 \ --output_dir \ --data_dir '' ``` `--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`，使其指向上一个检查点。
阶段 1：稀疏结构（32 → 64） ```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"}}' ```
阶段 2：形状（256 → 512 → 1024） ```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"}}' ```
阶段 3：纹理（256 → 512 → 1024） ```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"}}' ```
### 其他选项
所有命令行参数 | 参数 | 说明 | 默认值 | |----------|-------------|---------| | `--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（恢复） | — |
## 🌐 社区项目 我们感谢社区为 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)。