Pixal3D: 基于图像的像素对齐3D生成

SIGGRAPH 2026

李东阳¹ · 赵旺²* · 陈雨欣² · 胡文博² · 郭孟浩¹ · 张方略³ · 单瀛² · 胡事民¹✉

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

*项目负责人 ✉通讯作者

Pixal3D 可从单张图像生成高保真3D资产。与以往通过注意力机制松散注入图像特征的方法不同，Pixal3D通过反向投影将像素特征明确提升至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 架构和构建工作线程数。

步骤 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

网页演示

我们为 Pixal3D 提供了 Gradio 网页演示，您可以通过它交互式地从图像生成 3D 网格。

python app.py

网页演示版还提供低显存模式。在低显存模式下，前端默认分辨率会自动切换为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	稀疏结构	32 → 64	`ss_flow_img_dit_*_proj_finetune`
2	形状	256 → 512 → 1024	`slat_flow_img2shape_*_proj_finetune`
3	纹理	256 → 512 → 1024	`slat_flow_imgshape2tex_*_proj_finetune`

所有阶段均使用像素对齐投影条件和视角对齐潜变量（默认 2 个视角）。在每个阶段内，从最低分辨率开始，通过在配置中设置 finetune_ckpt，逐步微调至更高分辨率。

快速开始

python train.py \
  --config <CONFIG_JSON> \
  --output_dir <OUTPUT_DIR> \
  --data_dir '<DATA_DIR_JSON>'

--data_dir 是一个描述数据集布局的 JSON 字符串。不同阶段需要不同的键：

阶段	必需的键
稀疏结构	`base`, `ss_latent`, `render_cond`
形状	`base`, `shape_latent`, `render_cond`
纹理	`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`	当前节点序号	`0`
`--num_gpus`	每节点 GPU 数量	全部
`--master_addr`	主节点地址	`localhost`
`--master_port`	主节点端口	`12666`
`--use_wandb`	启用 W&B 日志	`false`
`--wandb_project`	W&B 项目名称	`trellis2-training`
`--wandb_name`	W&B 运行名称	`output_dir` 的基本名称
`--wandb_id`	W&B 运行 ID（用于恢复）	—

🌐 社区项目

感谢社区为 Pixal3D 开发扩展和部署指南！

Pixal3D-ComfyUI — ComfyUI 集成，包含 Windows、WSL 等系统的部署指南。

🤗 致谢

本项目主要基于 Trellis.2 和 Direct3D-S2 构建。我们衷心感谢这些作者在可扩展 3D 生成方面的杰出工作，它们构成了我们代码库和模型架构的基础。

我们也感谢以下仓库的重要贡献：

📄 引用

如果您觉得本工作有帮助，请考虑引用：

@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 许可协议发布。本项目中包含的第三方组件仍受其各自原始条款的许可约束；有关依赖项及其许可的完整列表，请参见 NOTICE。