Pixal3D

环境要求

• 带 CUDA 的 NVIDIA GPU（natten 需匹配 CUDA 架构）
• Python 环境（项目为 Python 实现）
• 已按 TRELLIS.2 官方指南搭好基础环境
• Git，用于克隆 Pixal3D 仓库

安装与启动步骤

1. 1克隆项目仓库

   把 Pixal3D 源码拉到本地，后续命令都在仓库根目录执行；确保磁盘有足够空间。

   git clone https://github.com/TencentARC/Pixal3D.git
   cd Pixal3D

   复制

2. 2配置 TRELLIS.2 基础环境

   Pixal3D 依赖 TRELLIS.2 作为基础环境，请先按官方安装指南完成配置，再继续后续步骤。

3. 3安装额外依赖

   在已激活的 TRELLIS.2 环境中，于项目根目录安装 Pixal3D 自己的 requirements 依赖。

   pip install -r requirements.txt

   复制

4. 4安装 natten

   需把 xx 换成你机器的 CUDA 架构与编译线程数；不替换会安装失败，示例为 8.6 与 8。

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

   复制

5. 5安装 utils3d

   从官方发布的 wheel 地址安装 utils3d 0.0.2，需联网下载，装完即可用于数据处理。

   pip install https://github.com/LDYang694/Storages/releases/download/20260430/utils3d-0.0.2-py3-none-any.whl

   复制

6. 6运行训练脚本

   用 JSON 配置、输出目录和 data_dir JSON 字符串启动；data_dir 所需键随阶段不同而变化。

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

   复制

关键配置

如何确认成功

运行 train.py 后能正常解析配置、读取 data_dir 数据并开始训练且无报错，即环境搭建成功。

常见问题

注意事项

• natten 安装命令中的 xx 必须替换为实际架构与 worker 数，README 未给出固定值。
• 模型权重与在线 Demo 在 Hugging Face 的 TencentARC/Pixal3D 提供。
• README 只给出了训练入口 train.py，未提供独立推理或导出 3D 资产的命令。
• 项目页与 arXiv 论文可查阅方法细节与更多示例。