ComfyUI_RH_Pixal3D

ComfyUI_RH_Pixal3D

• RunningHub China
• RunningHub International

English | 简体中文

ComfyUI nodes for TencentARC Pixal3D, an image-to-3D pipeline that generates textured GLB assets from a single image.

Features

• Load the Pixal3D image-to-3D pipeline from local ComfyUI model folders.
• Generate 3D assets from an input image and optional mask.
• Save textured .glb files to the ComfyUI output directory.
• Return camera metadata for downstream preview nodes.
• Supports low-VRAM mode, which is recommended for 24 GB GPUs.

Installation

Clone this repository into ComfyUI/custom_nodes:

cd ComfyUI/custom_nodes
git clone https://github.com/RH-RunningHub/ComfyUI_RH_Pixal3D.git

Install Python dependencies in the same Python environment used by ComfyUI:

cd ComfyUI/custom_nodes/ComfyUI_RH_Pixal3D
pip install -r requirements.txt

Pixal3D also needs GPU extension wheels such as flex_gemm, o_voxel, nvdiffrast, nvdiffrec_render, and a matching NATTEN wheel. These wheels are CUDA/PyTorch specific. For the tested Torch 2.10.0 + CUDA 12.8 environment, install NATTEN with libnatten:

pip uninstall -y natten
pip install natten==0.21.6+torch2100cu128 -f https://whl.natten.org
python -c "import natten; print(natten.__version__, natten.HAS_LIBNATTEN)"

The final command should print True for HAS_LIBNATTEN. Without libnatten, NAF feature upsampling will fail or fall back to slower paths.

Required CUDA extension source repositories:

| Module | GitHub | | --- | --- | | flash_attn | Dao-AILab/flash-attention | | flex_gemm | JeffreyXiang/FlexGEMM | | o_voxel | microsoft/TRELLIS.2 o-voxel | | nvdiffrast | NVlabs/nvdiffrast | | nvdiffrec_render | NVlabs/nvdiffrec |

Install or build these required extensions for the exact Python, PyTorch, CUDA, and GPU architecture used by ComfyUI. Follow this README's installation notes; the requirements.txt file keeps these repository links as comments only to avoid accidental source builds in incompatible environments.

Model Download & Installation

The nodes never download models during execution. Put all required models under ComfyUI/models before running the workflow.

Model Directory Structure

ComfyUI/
└── models/
    ├── Pixal3D/
    │   ├── pipeline.json
    │   └── ckpts/
    ├── MoGe/
    │   └── moge-2-vitl/
    │       └── model.pt
    ├── DINOv3/
    │   └── dinov3-vitl16-pretrain-lvd1689m/
    ├── BiRefNet/
    │   └── RMBG-2.0/
    └── NAF/
        ├── hubconf.py
        ├── src/
        └── naf_release.pth

Download from Hugging Face

Run these commands from the ComfyUI directory:

mkdir -p models/Pixal3D models/MoGe/moge-2-vitl models/DINOv3/dinov3-vitl16-pretrain-lvd1689m models/BiRefNet/RMBG-2.0 models/NAF
hf download TencentARC/Pixal3D --local-dir models/Pixal3D
hf download Ruicheng/moge-2-vitl --local-dir models/MoGe/moge-2-vitl
hf download facebook/dinov3-vitl16-pretrain-lvd1689m --local-dir models/DINOv3/dinov3-vitl16-pretrain-lvd1689m
hf download briaai/RMBG-2.0 --local-dir models/BiRefNet/RMBG-2.0
git clone https://github.com/valeoai/NAF.git models/NAF
curl -L -o models/NAF/naf_release.pth https://github.com/valeoai/NAF/releases/download/model/naf_release.pth

The hf command is provided by the Hugging Face CLI.

Manual Download

| Component | Link | Destination | | --- | --- | --- | | Pixal3D | TencentARC/Pixal3D | ComfyUI/models/Pixal3D | | MoGe-2 ViT-L | Ruicheng/moge-2-vitl | ComfyUI/models/MoGe/moge-2-vitl | | DINOv3 ViT-L/16 | facebook/dinov3-vitl16-pretrain-lvd1689m | ComfyUI/models/DINOv3/dinov3-vitl16-pretrain-lvd1689m | | RMBG-2.0 | briaai/RMBG-2.0 | ComfyUI/models/BiRefNet/RMBG-2.0 | | NAF source and checkpoint | valeoai/NAF | ComfyUI/models/NAF |

Model Selection Guide

| GPU VRAM | Recommended Settings | Notes | | --- | --- | --- | | 24 GB | low_vram=true, resolution=1024 | Tested path. Model loading stays low enough for full generation. | | 48 GB or more | low_vram=false, resolution=1024 | Faster, keeps more models resident on GPU. |

Usage

Import the API workflow from examples/pixal3d_image_to_glb_api.json into ComfyUI.

The workflow references pai.jpg as a sample input. Upload your own image in ComfyUI, or place examples/pai.jpg into ComfyUI/input/pai.jpg before running the workflow unchanged.

The workflow uses:

1. LoadImage
2. RunningHub Pixal3D Load Model
3. RunningHub Pixal3D Image to 3D
4. RunningHub Pixal3D Save GLB

The included workflow uses low_vram=true and 12 sampling steps for each Pixal3D stage. This is intended as a real-quality default for a 24 GB GPU. For quick smoke tests, reduce the three sampling step fields to 1.

Node Reference

RunningHub Pixal3D Load Model

Loads Pixal3D and its auxiliary models.

• attention_backend: flash_attn or flash_attn_3.
• sparse_conv_backend: sparse convolution backend, normally flex_gemm.
• low_vram: move models between CPU and GPU during execution. Use true for 24 GB GPUs.

RunningHub Pixal3D Image to 3D

Runs Pixal3D generation.

• resolution: 1024 or 1536.
• ss_sampling_steps, shape_slat_sampling_steps, tex_slat_sampling_steps: generation quality/speed controls.
• camera_image_resolution: camera estimation image size.
• max_num_tokens: sparse token cap for high-resolution stages.

RunningHub Pixal3D Save GLB

Writes the generated asset as a .glb file.

• decimation_target: target mesh face budget.
• texture_size: texture atlas size.
• remesh: enable mesh remeshing before export.
• filename_prefix: output path prefix under ComfyUI/output.

License

This repository vendors and adapts Pixal3D code. Pixal3D's license is included in LICENSE. It restricts Pixal3D use to academic purposes and states that Pixal3D is not intended for use within the European Union.

Other dependencies remain under their respective licenses.

Links

• RunningHub China
• RunningHub International
• Pixal3D Model
• Pixal3D Demo
• MoGe
• NAF
• RMBG-2.0

Acknowledgements

This ComfyUI integration is based on TencentARC Pixal3D. It also relies on MoGe, DINOv3, RMBG/BiRefNet, NAF, TRELLIS.2 components, and related CUDA extension libraries.