Pixal3D Model Loader

Every Pixal3D workflow starts here. Pixal3D Model Loader loads Tencent ARC's Pixal3D pipeline - plus its helper models (a DINOv3 image encoder, optionally MoGe for camera estimation and RMBG-2.0 for background removal) - and hands you a single model handle to feed Image To 3D. If the other nodes are where your patience gets tested, this is where the pack's reputation for being fiddly comes from: the loader is the node that actually tries to use FlashAttention and the four custom Pixal3D CUDA kernels (flex_gemm, cumesh, o_voxel, drtk), so a missing kernel shows up here as the error that finally makes you open the Environment Check.

The inputs that matter

There are eleven of them and it's a lot for a loader, so here's the honest map. Most people change maybe five.

• model_repo (default TencentARC/Pixal3D) - a Hugging Face repo id or a local folder containing pipeline.json. Default loads the stock model.
• hf_endpoint - the HF endpoint used only when downloads happen. Default https://huggingface.co; Chinese users can point it at https://hf-mirror.com.
• attention_backend - auto (default) picks FlashAttention 3 if flash_attn_interface imports, else FlashAttention 2. Explicitly forcing 2 or 3 only matters if you want to pin one.
• vram_mode - the big one. dynamic_vram (default) uses Comfy's Aimdo-aware ops. hybrid_low_vram adds native Pixal3D stage-by-stage offload - this is the recommended low-VRAM mode. native_low_vram is the older pure-native staging path. full_gpu keeps modules resident for maximum speed. If you're under 12GB, start with hybrid_low_vram.
• download_if_missing (default false) - when true, downloads the Pixal3D/helper models into ComfyUI/models/Pixal3D and native MoGe files into ComfyUI/models/geometry_estimation. The default being false is deliberate: the pack would rather you control the ~multi-GB download than surprise you with it.
• load_moge / load_rembg - helpers for auto camera and auto background removal. Both default true. Turn them off to save VRAM when you're using manual camera mode (load_moge=false) or transparent inputs with keep_alpha (load_rembg=false).
• naf_mode - fallback_if_missing (default) vs strict. NAF is Pixal3D's feature-refinement upsampler, and strict mode needs a CUDA NATTEN build with libnatten. On Windows without a matching wheel, keep fallback: it duplicates DINO features to preserve the model's expected shape, runs slower, and can be slightly lower quality - but it works.
• naf_target_size - upstream (default) or 1024/512/256/128. Only used in strict mode; lower sizes cut VRAM. Ignored by fallback.
• preload_naf (default false) - preloads the NAF upsampler during load. Only useful with naf_mode=strict and CUDA NATTEN.
• force_reload - ignore the cached handle and rebuild from disk. For when you've changed something outside the loader's knobs.

What it outputs

model - a PIXAL3D_MODEL handle, wired straight into Pixal3D Image To 3D. The loader caches handles by settings, so re-running with the same settings is cheap, and changing a setting triggers a rebuild. That cache is also why the Image To 3D tooltip tells you to re-run the loader after changing backend/VRAM/helper/NAF settings.

The install reality, briefly

This is the node that makes the pack's install warnings real. requirements.txt deliberately installs only safe Python packages - no torch, no flash-attn, no CUDA kernels - because those must match your exact Python/PyTorch/CUDA/OS/GPU. So after the normal install you still need a matching FlashAttention 2 or 3 wheel and the Pixal3D CUDA wheels (flex_gemm_ap, cumesh_vb, o_voxel_vb_ap, drtk), installed with --no-deps so pip can't replace a working torch. On Windows the README points to prebuilt wheels and stresses they must match on Python ABI, torch build, CUDA version, and OS tag.

If natten.HAS_LIBNATTEN is False (check via the Environment Check, or python -c "import natten; print(natten.HAS_LIBNATTEN)"), keep naf_mode=fallback_if_missing and preload_naf=false - do not keep reinstalling plain natten expecting strict mode to appear; it won't.

Troubleshooting

• "No module named flash_attn" or kernel import errors at load - a wheel is missing or mismatched. Run Pixal3D Environment Check and read the MISSING lines; install the matching wheel with --no-deps.
• Strict NAF OOMs on 12GB - hybrid_low_vram, drop naf_target_size to 256/128, or go back to fallback_if_missing.
• RMBG download fails - briaai/RMBG-2.0 is gated on HF; accept the terms and log in / set HF_TOKEN, or skip it with a transparent input and keep_alpha.

Install

ComfyUI Manager, search Pixal3D by Saganaki22, install the normal/stable entry (not the Nightly), restart, then run Environment Check before first load. Manual: git clone https://github.com/Saganaki22/Pixal3D-ComfyUI into ComfyUI/custom_nodes, pip install -r requirements.txt, python install.py --check, restart. Then this loader is where you tune until the pack is happy with your hardware.