[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-76542":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":14,"stars7d":17,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":22,"hasPages":22,"topics":24,"createdAt":10,"pushedAt":10,"updatedAt":32,"readmeContent":33,"aiSummary":34,"trendingCount":16,"starSnapshotCount":16,"syncStatus":35,"lastSyncTime":36,"discoverSource":37},76542,"Pixal3D-ComfyUI","Saganaki22\u002FPixal3D-ComfyUI","Saganaki22","Pixal3D image-to-3D nodes for ComfyUI - local TencentARC Pixal3D generation with textured GLB export + Windows support","https:\u002F\u002Fldyang694.github.io\u002Fprojects\u002Fpixal3d\u002F",null,"Python",157,16,1,3,0,7,125,5,59.19,"Other",false,"main",[25,26,27,28,29,30,31],"3d","3d-model","comfyui","comfyui-nodes","image-to-3d","imageto3d","trellis2","2026-06-12 04:01:21","# Pixal3D-ComfyUI\n\nComfyUI custom nodes for [TencentARC\u002FPixal3D](https:\u002F\u002Fgithub.com\u002FTencentARC\u002FPixal3D): image-to-3D generation, textured GLB export, FlashAttention 2\u002F3 selection, manual camera control, and ComfyUI model unload support.\n\n[Compatibility](docs\u002Fcompatibility_matrix.md) | [Windows Wheels](docs\u002Fwindows_wheels.md) | [Build NATTEN On Windows](docs\u002FBuild_Natten_windows.md) | [Troubleshooting](docs\u002Ftroubleshooting.md) | [Chinese README](README_ZH.md)\n\n![Pixal3D preview](https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F45d596b4-9070-44d2-8e4f-1019169d3daa)\n\n## Quick Start\n\nComfyUI Manager:\n\n1. Open **ComfyUI Manager**.\n2. Search for **Pixal3D** by **Saganaki22**.\n3. Install the normal\u002Fstable entry. Do **not** install the Nightly node.\n4. Restart ComfyUI, then run **Pixal3D Environment Check**.\n\nManual install:\n\n```bat\ncd ComfyUI\\custom_nodes\ngit clone https:\u002F\u002Fgithub.com\u002FSaganaki22\u002FPixal3D-ComfyUI.git\ncd Pixal3D-ComfyUI\npython -m pip install -r requirements.txt\npython install.py --check\n```\n\nRestart ComfyUI, then run **Pixal3D Environment Check** before loading the model.\n\n`requirements.txt` installs only safe Python packages. It deliberately does not install Torch, FlashAttention, Triton, Pixal3D CUDA kernels, or renderer kernels because those wheels must match your exact Python, PyTorch, CUDA, OS, and GPU.\n\n## Required Pieces\n\nA working generation environment needs these imports inside the same Python that launches ComfyUI:\n\n| Piece | Required import or file | Notes |\n|---|---|---|\n| PyTorch CUDA | `torch.cuda.is_available() == True` | CPU-only is not supported |\n| Attention | `flash_attn` or `flash_attn_interface` | FlashAttention 2 or 3 |\n| Sparse GEMM | `flex_gemm_ap` or `flex_gemm` | Pixal3D CUDA kernel |\n| Mesh ops | `cumesh_vb` or `cumesh` | Pixal3D CUDA kernel |\n| Voxel\u002Fexport ops | `o_voxel_vb_ap` or `o_voxel` | Pixal3D CUDA kernel |\n| DRTK | `drtk` | UV\u002Fexport helper |\n| Pixal3D model | `ComfyUI\u002Fmodels\u002FPixal3D\u002FTencentARC_Pixal3D\u002Fpipeline.json` | Download manually or use `download_if_missing=true` |\n| DINOv3 helper | `ComfyUI\u002Fmodels\u002FPixal3D\u002Fcamenduru_dinov3-vitl16-pretrain-lvd1689m\u002F` | Needed by the image encoder |\n| MoGe | `ComfyUI\u002Fmodels\u002Fgeometry_estimation\u002Fmoge_2_vitl_normal_fp16.safetensors` | Only needed for `camera_mode=moge` |\n| RMBG-2.0 | `ComfyUI\u002Fmodels\u002FPixal3D\u002Fbriaai_RMBG-2.0\u002F` | Gated model; only needed for `background_mode=auto_remove` |\n| NATTEN\u002Flibnatten | `natten.HAS_LIBNATTEN == True` | Only needed for strict NAF |\n\nIf Environment Check says a CUDA package is missing, install a wheel that exactly matches your stack. Do not let pip replace a working Torch install while testing random wheels; use `--no-deps` for manual CUDA wheels.\n\n## Windows Wheel Order\n\nOn Windows, install wheels in this order:\n\n1. PyTorch with CUDA for your GPU\u002Fdriver.\n2. Required Pixal3D CUDA wheels: `flex_gemm_ap`, `cumesh_vb`, `o_voxel_vb_ap`, and `drtk`.\n3. One attention wheel: FlashAttention 2 (`flash_attn`) or FlashAttention 3 (`flash_attn_interface`).\n4. Optional strict NAF wheel: NATTEN with CUDA `libnatten`.\n\nThe required Pixal3D CUDA wheels are separate from NATTEN. A working NATTEN install does not mean `flex_gemm`, `cumesh`, `o_voxel`, or `drtk` are installed.\n\nFor Python 3.12, PyTorch 2.10, CUDA 13.0 on Blackwell sm120, install the required Pixal3D CUDA wheels plus the prebuilt NATTEN\u002Flibnatten wheel with:\n\n```bat\nvenv\\Scripts\\python.exe -m pip install --no-deps ^\n  \"https:\u002F\u002Fgithub.com\u002FPozzettiAndrea\u002Fcuda-wheels\u002Freleases\u002Fdownload\u002Fflex_gemm_ap-latest\u002Fflex_gemm_ap-1.0.0%2Bcu130torch2.10-cp312-cp312-win_amd64.whl\" ^\n  \"https:\u002F\u002Fgithub.com\u002FPozzettiAndrea\u002Fcuda-wheels\u002Freleases\u002Fdownload\u002Fcumesh_vb-latest\u002Fcumesh_vb-1.0%2Bcu130torch2.10-cp312-cp312-win_amd64.whl\" ^\n  \"https:\u002F\u002Fgithub.com\u002FPozzettiAndrea\u002Fcuda-wheels\u002Freleases\u002Fdownload\u002Fo_voxel_vb_ap-latest\u002Fo_voxel_vb_ap-0.0.1%2Bcu130torch2.10-cp312-cp312-win_amd64.whl\" ^\n  \"https:\u002F\u002Fgithub.com\u002FPozzettiAndrea\u002Fcuda-wheels\u002Freleases\u002Fdownload\u002Fdrtk-latest\u002Fdrtk-0.1.0%2Bcu130torch2.10-cp312-cp312-win_amd64.whl\" ^\n  \"https:\u002F\u002Fhuggingface.co\u002Fdrbaph\u002FNATTEN-0.21.6-torch2100cu130-cp312-cp312-win_amd64\u002Fresolve\u002Fmain\u002Fnatten-0.21.6+torch2100cu130-cp312-cp312-win_amd64.whl\"\n```\n\nIf your Python, PyTorch, CUDA, or GPU architecture does not match that NATTEN wheel, omit the final NATTEN URL and use `naf_mode=fallback_if_missing`, `preload_naf=false`.\n\nFor Python 3.12, PyTorch 2.8, CUDA 12.8 on Blackwell sm100\u002Fsm120, use the matching Pixal3D CUDA wheels plus the `naxneri` NATTEN\u002Flibnatten wheel:\n\n```bat\nvenv\\Scripts\\python.exe -m pip install --no-deps ^\n  \"https:\u002F\u002Fgithub.com\u002FPozzettiAndrea\u002Fcuda-wheels\u002Freleases\u002Fdownload\u002Fflex_gemm_ap-latest\u002Fflex_gemm_ap-1.0.0%2Bcu128torch2.8-cp312-cp312-win_amd64.whl\" ^\n  \"https:\u002F\u002Fgithub.com\u002FPozzettiAndrea\u002Fcuda-wheels\u002Freleases\u002Fdownload\u002Fcumesh_vb-latest\u002Fcumesh_vb-1.0%2Bcu128torch2.8-cp312-cp312-win_amd64.whl\" ^\n  \"https:\u002F\u002Fgithub.com\u002FPozzettiAndrea\u002Fcuda-wheels\u002Freleases\u002Fdownload\u002Fo_voxel_vb_ap-latest\u002Fo_voxel_vb_ap-0.0.1%2Bcu128torch2.8-cp312-cp312-win_amd64.whl\" ^\n  \"https:\u002F\u002Fgithub.com\u002FPozzettiAndrea\u002Fcuda-wheels\u002Freleases\u002Fdownload\u002Fdrtk-latest\u002Fdrtk-0.1.0%2Bcu128torch2.8-cp312-cp312-win_amd64.whl\" ^\n  \"https:\u002F\u002Fhuggingface.co\u002Fnaxneri\u002Fnatten-0.21.6-blackwell-cu128-cp312-cp312-win_amd64\u002Fresolve\u002Fmain\u002Fnatten-0.21.6-blackwell-cu128-cp312-cp312-win_amd64.whl\"\n```\n\nFor PyTorch 2.9 or another CUDA 12.8 stack, change the four Pozzetti URLs to wheels built for that exact Torch version. Keep the NATTEN URL only when it matches your Python, CUDA, and GPU.\n\nMore detail: [Windows wheel guide](docs\u002Fwindows_wheels.md).\n\n## Windows NATTEN \u002F NAF\n\nPixal3D uses **NAF** as a feature refinement step for the shape and texture stages. NAF uses NATTEN. Strict upstream NAF only works when NATTEN includes CUDA `libnatten`:\n\n```bat\npython -c \"import natten; print(natten.__version__, natten.HAS_LIBNATTEN)\"\n```\n\nIf that prints `False`, you have normal NATTEN without CUDA libnatten. The node can still run, but you must use:\n\n```text\nPixal3D Model Loader naf_mode=fallback_if_missing\nPixal3D Model Loader preload_naf=false\n```\n\nFallback mode avoids loading NAF and keeps the expected tensor shape by using DINO projection features. It is usually slower and may use more RAM\u002FVRAM than a proper CUDA NATTEN\u002Flibnatten build, and quality can be lower than strict upstream NAF.\n\nOn Windows, a NATTEN wheel must match all of these:\n\n```text\nPython ABI, for example cp312\nPyTorch build, for example torch2.10\nCUDA build, for example cu130\nGPU architecture, for example sm120\nOS tag, win_amd64\n```\n\nIf you cannot find a matching Windows wheel, use fallback mode or build NATTEN from source.\n\nKnown community Windows NATTEN wheels:\n\n| Python | PyTorch | CUDA | GPU | Wheel |\n|---|---|---|---|---|\n| 3.12 | 2.10 | 13.0 | Blackwell sm120 | [drbaph\u002FNATTEN-0.21.6-torch2100cu130-cp312-cp312-win_amd64](https:\u002F\u002Fhuggingface.co\u002Fdrbaph\u002FNATTEN-0.21.6-torch2100cu130-cp312-cp312-win_amd64) |\n| 3.12 | 2.8+ | 12.8 | Blackwell sm100\u002Fsm120 | [naxneri\u002Fnatten-0.21.6-blackwell-cu128-cp312-cp312-win_amd64](https:\u002F\u002Fhuggingface.co\u002Fnaxneri\u002Fnatten-0.21.6-blackwell-cu128-cp312-cp312-win_amd64) |\n\nMore detail: [Windows wheel guide](docs\u002Fwindows_wheels.md) and [Build NATTEN on Windows](docs\u002FBuild_Natten_windows.md).\n\n## Manual Model Downloads\n\nIf `download_if_missing=false`, download the model files yourself and place them in these folders. Download the full snapshots, not single random files.\n\n| Model | Download link | Local folder | Needed when |\n|---|---|---|---|\n| Pixal3D | [TencentARC\u002FPixal3D](https:\u002F\u002Fhuggingface.co\u002FTencentARC\u002FPixal3D) | `ComfyUI\u002Fmodels\u002FPixal3D\u002FTencentARC_Pixal3D\u002F` | Always |\n| DINOv3 helper | [camenduru\u002Fdinov3-vitl16-pretrain-lvd1689m](https:\u002F\u002Fhuggingface.co\u002Fcamenduru\u002Fdinov3-vitl16-pretrain-lvd1689m) | `ComfyUI\u002Fmodels\u002FPixal3D\u002Fcamenduru_dinov3-vitl16-pretrain-lvd1689m\u002F` | Always |\n| MoGe | [Comfy-Org\u002FMoGe](https:\u002F\u002Fhuggingface.co\u002FComfy-Org\u002FMoGe) | `ComfyUI\u002Fmodels\u002Fgeometry_estimation\u002F` | `camera_mode=moge` |\n| RMBG-2.0 | [briaai\u002FRMBG-2.0](https:\u002F\u002Fhuggingface.co\u002Fbriaai\u002FRMBG-2.0) | `ComfyUI\u002Fmodels\u002FPixal3D\u002Fbriaai_RMBG-2.0\u002F` | `background_mode=auto_remove` |\n| NAF upsampler | [valeoai\u002FNAF](https:\u002F\u002Fgithub.com\u002Fvaleoai\u002FNAF) | `ComfyUI\u002Fmodels\u002FPixal3D\u002Ftorch_hub\u002F` cache | Strict NAF only |\n\nRMBG-2.0 is gated on Hugging Face. Accept the model terms and log in before downloading it. If you do not want RMBG, use a transparent PNG\u002FWebP and set `background_mode=keep_alpha`, or use `background_mode=none`.\n\nExpected model layout:\n\n```text\nComfyUI\u002Fmodels\u002F\n├── Pixal3D\u002F\n│   ├── TencentARC_Pixal3D\u002F\n│   │   ├── pipeline.json\n│   │   └── ckpts\u002F\n│   │       ├── *.json\n│   │       └── *.safetensors\n│   ├── camenduru_dinov3-vitl16-pretrain-lvd1689m\u002F\n│   │   ├── config.json\n│   │   ├── model.safetensors\n│   │   └── preprocessor_config.json\n│   └── briaai_RMBG-2.0\u002F\n│       ├── config.json\n│       ├── BiRefNet_config.py\n│       ├── birefnet.py\n│       ├── model.safetensors\n│       └── preprocessor_config.json\n└── geometry_estimation\u002F\n    ├── moge_1_vitl_fp16.safetensors\n    └── moge_2_vitl_normal_fp16.safetensors\n```\n\nMoGe files from `Comfy-Org\u002FMoGe` are stored directly in `ComfyUI\u002Fmodels\u002Fgeometry_estimation\u002F`, not in a nested `Comfy-Org\u002FMoGe` folder. `hf_endpoint` can be changed to a Hugging Face mirror if needed.\n\n## Recommended Loader Settings\n\nGeneral Windows baseline:\n\n| Node | Setting |\n|---|---|\n| Pixal3D Model Loader | `attention_backend=auto` |\n| Pixal3D Model Loader | `vram_mode=dynamic_vram` |\n| Pixal3D Model Loader | `naf_mode=fallback_if_missing` unless `natten.HAS_LIBNATTEN=True` |\n| Pixal3D Model Loader | `preload_naf=false` unless strict NAF works |\n| Pixal3D Image To 3D | `pipeline_type=1024_cascade` for lower VRAM, `1536_cascade` for quality |\n| Pixal3D Export GLB | `decimation_target=1000000`, `texture_size=4096` |\n\nLowest-VRAM\u002Fmanual path:\n\n| Node | Setting |\n|---|---|\n| Pixal3D Model Loader | `vram_mode=native_low_vram` |\n| Pixal3D Model Loader | `load_moge=false` |\n| Pixal3D Model Loader | `load_rembg=false` |\n| Pixal3D Image To 3D | `camera_mode=manual` |\n| Pixal3D Image To 3D | `background_mode=keep_alpha` with transparent PNG\u002FWebP |\n| Pixal3D Camera Control | Connect `manual_fov` to `Pixal3D Image To 3D.manual_fov` |\n\n`native_low_vram` moves Pixal3D stages between CPU and GPU as needed. It can reduce VRAM pressure, but it is slower and needs a lot of system RAM, often 20-40 GB.\n\n## Nodes\n\n| Node | Purpose |\n|---|---|\n| Pixal3D Environment Check | Prints installed\u002Fmissing dependencies |\n| Pixal3D Model Loader | Loads Pixal3D and helper models |\n| Pixal3D Camera Control | Manual FOV, distance, and mesh scale with Scene\u002FPOV preview |\n| Pixal3D Image To 3D | Runs image-to-3D generation |\n| Pixal3D Export GLB | Exports the result to textured `.glb` |\n| Pixal3D Unload Model | Clears the Pixal3D pipeline cache and releases the model handle |\n\nBasic workflow:\n\n```text\nLoad Image -> Pixal3D Image To 3D image\nPixal3D Model Loader -> Pixal3D Image To 3D model\nPixal3D Image To 3D -> Pixal3D Export GLB\nPixal3D Export GLB glb_path -> Preview 3D & Animation model_file\n```\n\nConnect `Pixal3D Image To 3D rembg_image` to `Preview Image` to inspect the image Pixal3D used after background preprocessing.\n\nManual camera workflow:\n\n\u003Ctable>\n  \u003Ctr>\n    \u003Ctd align=\"center\">\n      \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fe14fa7a7-e354-44a8-8221-c402bb74e844\" width=\"350\"\u002F>\n    \u003C\u002Ftd>\n    \u003Ctd align=\"center\">\n      \u003Cimg src=\"https:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fe6bf6c7b-e236-4773-a465-db9a0078d33f\" width=\"350\"\u002F>\n    \u003C\u002Ftd>\n  \u003C\u002Ftr>\n\u003C\u002Ftable>\n\n\n```text\nLoad Image -> Pixal3D Camera Control image\nPixal3D Camera Control manual_fov -> Pixal3D Image To 3D manual_fov\nPixal3D Image To 3D camera_mode=manual\n```\n\n## Troubleshooting Shortcuts\n\n| Symptom | Fix |\n|---|---|\n| `No module named flash_attn` | Install a matching FlashAttention 2 wheel, or FlashAttention 3 with `flash_attn_interface` |\n| `flex_gemm`, `cumesh`, `o_voxel`, or `drtk` missing | Install matching Pixal3D CUDA wheels for your Python\u002FPyTorch\u002FCUDA\u002FOS |\n| `natten.HAS_LIBNATTEN=False` | Use `naf_mode=fallback_if_missing`, `preload_naf=false`, or install\u002Fbuild CUDA NATTEN |\n| RMBG download fails | Accept gated model terms, log in, set `HF_TOKEN`, or use transparent input with `keep_alpha` |\n| MoGe missing | Download Comfy-Org\u002FMoGe files to `ComfyUI\u002Fmodels\u002Fgeometry_estimation\u002F` or use manual camera mode |\n| GLB looks fragmented | Try `remesh=true`; keep `decimation_target=1000000` or higher |\n| RAM stays high after unload | Use Pixal3D Unload Model; restart ComfyUI to return all reserved Python\u002FPyTorch memory to the OS |\n\nSee [Troubleshooting](docs\u002Ftroubleshooting.md) for longer explanations.\n\n## Useful Links\n\n- [Windows wheel guide](docs\u002Fwindows_wheels.md)\n- [Build NATTEN on Windows](docs\u002FBuild_Natten_windows.md)\n- [Linux\u002FWSL CUDA guide](docs\u002Flinux_wsl_cuda.md)\n- [Portable\u002Fstandalone install](docs\u002Fportable_standalone_install.md)\n- [Compatibility matrix](docs\u002Fcompatibility_matrix.md)\n- [Related repositories](docs\u002Frelated_repos.md)\n\n## Acknowledgements\n\nThis nodepack builds on [TencentARC\u002FPixal3D](https:\u002F\u002Fgithub.com\u002FTencentARC\u002FPixal3D), [Trellis.2](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FTRELLIS.2), [Trellis](https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002FTRELLIS), and [Direct3D-S2](https:\u002F\u002Fgithub.com\u002FDreamTechAI\u002FDirect3D-S2).\n\nIf Pixal3D is useful in your work, please cite the upstream project:\n\n```bibtex\n@article{li2026pixal3d,\n    title={Pixal3D: Pixel-Aligned 3D Generation from Images},\n    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},\n    journal={arXiv preprint arXiv:2605.10922},\n    year={2026}\n}\n```\n","Pixal3D-ComfyUI 是一个为 ComfyUI 提供图像转3D功能的扩展节点，支持腾讯ARC的Pixal3D模型，并能够导出带纹理的GLB格式文件。该项目的核心功能包括图像到3D模型的转换、FlashAttention 2\u002F3的选择性使用以及手动控制相机视角等，同时提供了对Windows系统的支持。技术上，它依赖于Python语言实现，并需要特定版本的PyTorch CUDA库及其他相关CUDA内核来确保运行效率与兼容性。适用于那些希望在本地环境下利用图像生成高质量3D模型，并进行后续编辑或渲染的专业人士和爱好者。",2,"2026-06-11 03:55:03","CREATED_QUERY"]