tencentarc--pixal3d/README.md

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

Pixal3D：从图像生成像素对齐的 3D（Pixel-Aligned 3D Generation from Images）

SIGGRAPH 2026

Dong-Yang Li¹ · Wang Zhao²* · Yuxin Chen² · Wenbo Hu² · Meng-Hao Guo¹ · Fang-Lue Zhang³ · Ying Shan² · Shi-Min Hu¹✉

¹清华大学 (BNRist)    ²腾讯 ARC 实验室    ³惠灵顿维多利亚大学

*项目负责人    ✉通讯作者

Pixal3D 可从单张图像生成高保真 3D 资产。与此前通过注意力机制松散注入图像特征的方法不同，Pixal3D 通过反投影（back-projection）将像素特征显式提升到 3D 空间，建立直接的像素到 3D 对应关系。这使得其能够达到接近重建级别的保真度，并具备精细的几何与 PBR 纹理。

---

✨ 动态

• 2026 年 5 月：发布训练代码与数据准备工具包。🔧
• 2026 年 5 月：发布基于 Trellis.2 骨干网络的改进版本。💪
• 2026 年 5 月：发布推理代码与在线演示。🤗
• 2026 年 4 月：论文被 SIGGRAPH 2026 接收！🎉

📌 分支

分支	说明
main	最新版本——基于 Trellis.2 骨干网络的改进实现，性能更优。
paper	论文版本——基于 Direct3D-S2, 的原始实现，对应我们 SIGGRAPH 2026 论文中报告的结果。

若要复现我们论文中的结果，请切换到 paper 分支。

🎮 在线体验

您无需安装任何软件，即可通过我们的 Hugging Face Gradio 演示在浏览器中直接体验 Pixal3D：

👉 启动演示

🚀 快速开始

安装

步骤 1：按 TRELLIS.2 安装指南配置

请先按照 TRELLIS.2 的安装指南配置基础环境。

步骤 2：安装额外依赖

pip install -r requirements.txt

步骤 3：安装 natten

NATTEN_CUDA_ARCH="xx" NATTEN_N_WORKERS=xx pip install natten==0.21.0 --no-build-isolation

请将 xx 替换为您机器适用的 CUDA 架构与编译并行 worker 数量。

步骤 4：安装 utils3d

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 网格：

python inference.py --image assets/images/0_img.png --output ./output.glb

低显存模式（通过按需加载模型降低峰值显存占用）：

python inference.py --image assets/images/0_img.png --output ./output.glb --low_vram

默认流水线分辨率为 1536（标准模式）或 1024（低显存模式）。可通过 --resolution 覆盖：

# 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 后端：

ATTN_BACKEND=sdpa python inference.py --image assets/images/0_img.png --output ./output.glb --low_vram

Web 演示

我们提供了 Pixal3D 的 Gradio Web 演示，支持以交互方式从图像生成 3D 网格。

python app.py 

Web 演示同样支持低显存模式。前端默认分辨率在低显存模式下会自动切换为 1024（否则为 1536），也可在 UI 中手动修改。

python app.py --low_vram
# or via environment variable:
LOW_VRAM=1 python app.py

🔧 训练

我们提供完整的训练代码库，用于从零复现 Pixal3D。

数据准备

请按照数据工具包说明，准备视角对齐的 O-Voxel 数据与渲染条件图像：

📂 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，逐步微调至更高分辨率。

快速开始

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，使其指向上一个检查点。

阶段 1：稀疏结构（32 → 64）

# 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）

# 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）

# 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 — ComfyUI 集成，包含适用于 Windows、WSL 等环境的部署指南。

🤗 致谢

本项目大量借鉴了 Trellis.2 与 Direct3D-S2.。我们衷心感谢作者在可扩展 3D 生成（scalable 3D generation）方面的杰出工作，其为我们的代码库与模型架构奠定了基础。

我们也感谢以下仓库的杰出贡献：

• Direct3D-S2
• Trellis
• Trellis.2

📄 引用

若您觉得本工作有帮助，欢迎引用：

@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 发布。本项目中包含的第三方组件仍按其各自原始条款授权；完整依赖列表及其许可证请参阅 NOTICE。