The ComfyUI nodes refine a reference image + coarse mesh of the same object using the official Hi3D model. Their inputs, outputs and canvas workflow remain geometry-only. The standalone workbench also generates geometry from one image, offers multiple geometry/PBR engines, and compares saved results under shared lighting. See validated scope.

Models · Canvas workflow · Validation · Upstream Hi3D

v0.6.0: Idol Gaussian generation, asset processing and single-character animation are available in the standalone workbench. Real generation, offline runtime/model checks, upload/process/download tasks and EXE lifecycle checks have passed. Browser checks cover the million-splat viewer, mesh/PBR stages, downloads/export and one complete four-second Idol character clip. Release notes · Scope and quality limits · Browser evidence.

The workbench adds Hunyuan3D-2mv multi-view modeling: use a front reference with optional left, back and right images, including three-view inputs. Its checkpoint downloads separately. Subsequent refinement and existing PBR stages use the front reference. Usage and model details.

The workbench integrates Idol image-to-splat and colored mesh generation, retaining PLY/SPZ/KSPLAT with a separate Gaussian preview, orbit video, official mesh conversion and downstream PBR/asset processing. See operation and real validation. Gaussian appearance and extracted mesh geometry remain separate outputs.

flowchart LR
  A[Hi3D Model Loader] --> D[Hi3D Refine]
  B[Upload Image] --> D
  C[Upload Mesh] --> D
  D --> E[SaveGLB]

Downloads and automatic updates

GitHub Releases contain code only: source, ComfyUI nodes, program updates and the small Windows launcher. They include no model weights, Python interpreter or runtime. T8star will provide the complete package with Python and models separately and announce its download location. Its bundle-manifest.json identifies the included components.

GitHub Releases · Update instructions

v0.6 runtime change: older v0.5.x complete bundles need the matching v0.6 full runtime bundle. The updater rejects an incompatible code overlay instead of replacing Python packages. Model weights can be retained in a shared model directory.

From v0.4.1, standalone bundles check and download code updates while idle, verify them, and install on the next launch. Models, Python, configuration and history are preserved. Disable automatic downloads in Models and environment → Program updates, or close the app and run Update-Workbench.cmd. Old v0.4.0 bundles need one manual code overlay first. A runtime-incompatible release requests a new complete bundle instead of replacing Python dependencies. Git source checkouts update through Git.

Launch and close the Windows bundle

Complete model coverage (v0.6.0): five geometry choices and four texture entries, including Idol, Hunyuan3D-2mv, UltraTex INT8 ConvRot Base 9B and FP8 Base 9B. Core plus all geometry/PBR components total about 87.98GB; the separately managed asset-studio components add 34.91GB. Models → Complete all engines prepares the geometry/PBR dependencies; asset operations prepare their own components. A complete package records its exact contents in bundle-manifest.json. Selective downloads and per-engine sizes.

Builders must use --include-models --include-pipeline --all-engines with tools/build_release.py. The INT8 checkpoint is tsolful's pinned community quantization of Base 9B, not distilled/KV Klein; its original FLUX non-commercial license remains applicable. This project does not re-quantize it. INT8 is not guaranteed to use less VRAM or run faster than FP8 on every GPU.

Double-click Hi3D-Workbench.exe or Start-Workbench.cmd and keep its console open to view logs. Stop with Ctrl+C, the console window's X, the webpage's Close workbench button, or Stop-Workbench.cmd. Closing only the browser leaves the service running. The EXE owns the server and its inference subprocesses, so closing it also releases its workers. Startup errors remain visible. A second launch reuses the same directory's service; it never stops another bundle sharing the port.

v0.4.7 launcher fix: existing bundles need both the code update and the matching launcher ZIP to restore Python logs. Startup displays the model directory, URL and confirmed readiness; slow initialization keeps reporting its status.

The separate Hi3D-Workbench-launcher-<version>.zip contains a small Windows launcher and start/stop scripts, not Python or models. Apply the matching code update first, then extract the launcher beside Start-Workbench.cmd. A missing launcher can also be built by scripts/Build-Launcher.ps1 using Windows' .NET Framework 4 compiler. Launcher source is included; the executable is unsigned. New complete bundles include it already. Community links are available in the workbench sidebar and footer.

Progress and acceleration

v0.5.1 adds bounded asynchronous TRELLIS.2 weight uploads using 32 MiB of host staging buffers, plus next-stage file read-ahead during preparation/UV work. Weights, precision and the independent Hi3D-only ComfyUI scope are unchanged. Measurements and limits.

The workbench console and webpage show the active phase, its elapsed time, real counters/steps, time since meaningful progress, and the explicitly reported CPU/CUDA device. UV packing and file/model loading may use the CPU or disk; low GPU usage during those phases does not mean inference fell back to CPU.

TRELLIS.2 offers Auto / native FlashAttention / fused SDPA for packed sparse attention, independently of Hi3D. Auto selects native Flash only after a real CUDA packed-kernel probe; an incompatible/missing wheel reports its reason and uses SDPA. UltraTex retains its trained sparse attention. New UVs prefer CuMesh GPU clustering with CPU atlas packing, verified source-index/normal recovery and a reusable cache; the pinned community GPU algorithm and bounded CPU partitions provide reported fallbacks. A usable existing atlas is retained. Optional 100K / 300K / 1M face budgets apply only to generated TRELLIS geometry; the raw mesh remains available. Existing-model texturing never simplifies the input.

Code updates preserve existing Python environments. To add the optional Windows cp312 / Torch 2.8 cu128 Flash wheel to an older full bundle, run runtime/python.exe tools/setup_pipeline_runtime.py --runtime runtime-pipeline --attention-only from the bundle root. This verifies a fixed SHA256 and installs with no dependencies; it does not upgrade Torch. Other systems retain SDPA. The optional CPU UV packer can be added with the same command and --uv-only (Numba 0.61.2 / llvmlite 0.44.0); it keeps the existing NumPy and Torch. First use includes JIT compilation. See performance evidence and limits.

v0.5.0 performance: the default releases phase weights while retaining the inference interpreter. Bounded CPU residency and exit-after-task remain selectable. Sequential checkpoint read-ahead, original-dtype parameter assignment, validated shape/topology caching and parallel original Telea baking reduce repeated work. Optional isolated CUDA voxelization retains the official CPU fallback; GPU floating-point results are not promised bit-identical. See performance and validation.

Install/update the optional converter under Models and environment → GPU voxelization, or run runtime/python.exe tools/setup_pipeline_runtime.py --runtime runtime-pipeline --voxel-only. The pinned Windows x64 wheel requires CPython 3.12 and Torch 2.8.0+cu128, is size/SHA256 verified, and does not resolve dependencies, upgrade Torch or replace o_voxel. It does not change model readiness; CPU conversion remains available without it.

ComfyUI

Find Hi3D T8 in ComfyUI-Manager (node ID hi3d-t8, publisher t8star), or clone this repository into ComfyUI/custom_nodes/Comfyui-Hi3d-T8. Install requirements.txt with ComfyUI's Python, then restart ComfyUI.
Put core weights under ComfyUI/models/Hi3D/, containing hi3d/, dino/ and clip/. The loader supports a custom root, the hi3d entry in extra_model_paths.yaml, or an explicit download_missing option for the pinned core snapshot.
Import the new Hi3D-Refine.json canvas workflow. Upload a reference using Load Image. Use Hi3D Load Mesh to upload or drop a GLB / PLY / STL, then select it in the dropdown.
Start with 512 / 25 steps / cpu_offload / sdpa. Hi3D Refine runs inside ComfyUI; native SaveGLB saves the refined geometry to ComfyUI's output directory.

The three nodes are Hi3D Model Loader, Hi3D Load Mesh and Hi3D Refine, exchanging native MESH values and a JSON report. Pinned official source is included. No workbench service, page or interpreter is required. ComfyUI's existing Torch/CUDA is retained; only required inference dependencies are installed. The nodes reproduce Hi3D geometry refinement only.

Replace legacy bridge workflows with the new canvas file. The Hi3D Backend address node is removed; existing reference images, meshes and seeds remain usable. See standalone node instructions.

Models and edition differences

| Component | Purpose | Used by | |---|---|---| | Hi3D transformer 512 + VAE | 512 refinement | ComfyUI and workbench | | Hi3D transformer 1024 + the same VAE | 1024 and 1536 refinement; no separate 1536 checkpoint | ComfyUI and workbench | | DINOv2 Large + CLIP ViT-L/14 | Required image encoders, not extra 3D models | ComfyUI and workbench | | Hunyuan3D-2mini-Turbo / Hunyuan3D 2.1 / Hunyuan3D-2mv / TRELLIS.2 / Idol | Selectable image-to-geometry engines | Workbench only | | TRELLIS.2 PBR / Hunyuan3D-Paint 2.1 / UltraTex | Selectable mesh-conditioned PBR engines | Workbench only | | DINOv3, DINOv2 Giant, FLUX.2 Klein 9B and Qwen3 | Dependencies of the selected extension engine | Workbench only | | CPU U2Netp | Optional foreground extraction for opaque images | Workbench only | | P3-SAM / X-Part / SkinTokens / UniRig / Kimodo | Segmentation, completion, rigging and single-character motion | Workbench only |

The Hugging Face repository contains the shared Hi3D core weights and configurations plus every standalone extension component. There are no ComfyUI-specific Hi3D checkpoints. Extension models live under models/extensions, retaining pinned sources, hashes and their individual licenses. UltraTex uses an upstream-published fp8 base, not a new quantization by this project. The Registry/node download contains code and the canvas workflow only. Model files alone do not provide an inference environment.

ComfyUI defaults to ComfyUI/models/Hi3D/; the workbench uses its own models/. Both can share a custom weight root. Replace models below with the target directory:

hf download t8star/Hi3d-Comfy --local-dir models --include "manifest.json" "hi3d/*" "dino/*" "clip/*" "licenses/*"

The command above downloads the core only. All core, geometry/PBR and studio model artifacts total about 122.89GB; use the model repository's selective download sets. Geometry/PBR components live under models/extensions/, asset components under models/studio/. Manifests retain pinned upstream revisions and hashes. The backend also downloads from the original repositories.

Custom model directory: choose a root in Models and environment → Model directory, such as E:/AI-Models/Hi3D, or a path relative to the workbench root. It contains hi3d/, dino/, clip/ and optional extensions/. Save applies while idle without restarting; Restore default returns to models/. Files are not moved automatically, and code updates preserve the setting. Existing core files still need Reverify all core models before the new location is ready.

<details> <summary>Actual textured example</summary>

Actual textured example

Standalone workbench example: TRELLIS.2 geometry + UltraTex PBR; no Hi3D refinement in this example.

</details>

Local workbench

The Windows edition starts with Start-Workbench.cmd and opens http://127.0.0.1:8378, independently of ComfyUI. The workbench has three entry points: image → initial mesh → optional Hi3D → PBR; reference + existing mesh → PBR; and reference + coarse mesh → Hi3D, optionally followed by PBR. Image mode defaults to initial mesh + PBR, with Hi3D optional: a paired cartoon test retained a cleaner mouth without refinement. It retains intermediate models, logs and reports. Geometry and texture engines are selected independently; install optional engines from Models. Existing self-contained GLBs retain their materials and usable single-material UVs. Saved jobs can be compared side by side with shared camera, HDR lighting and exposure. See engine choices and quality evidence. Material results export as self-contained GLB; STL/PLY contain geometry only.

The v0.5.0 full-model offline package includes two isolated runtimes, Hi3D core and all 14 extension components, including Hunyuan 2.1, Hunyuan Paint and both UltraTex FP8/INT8 ConvRot bases. Exact contents are recorded in bundle-manifest.json. Older baseline packages can complete their dependencies in Models. Unavailable engines are identified explicitly. Node and source archives contain code; source installations prepare runtimes and weights separately.

Three starting presets balance cost and detail: Light uses Mini Turbo 256 + TRELLIS PBR 512 / 2K; Balanced uses TRELLIS geometry 512 + PBR 1024 / 4K; Detail uses TRELLIS geometry 1024 + UltraTex INT8 ConvRot 1024 / 4K. UltraTex's FLUX.2 Klein 9B base has a Non-Commercial license. A larger atlas does not add detail missing from the generated texture. See engine choices and the workbench guide.

For a Windows source installation, use Python 3.10 in a separate environment:

git clone https://github.com/T8mars/Comfyui-Hi3d-T8.git
cd Comfyui-Hi3d-T8
powershell -ExecutionPolicy Bypass -File scripts/Setup.ps1 -Python C:/Python310/python.exe -DownloadModels

For the standalone image/PBR stages, also prepare the separate Python 3.12 runtime with C:/Python312/python.exe tools/setup_pipeline_runtime.py, then run .venv/Scripts/python.exe -m hi3d_workbench.pipeline_models download for the baseline models. Additional engines download independently in Models; see engine choices.

For Linux Hi3D refinement, run bash scripts/setup-linux.sh, then .venv/bin/python -m hi3d_workbench.model_cli download and .venv/bin/python -m hi3d_workbench --open. Linux setup follows the official Ampere/Hopper stack and has not been tested on this machine. The additional image/PBR runtime is currently validated on Windows. See detailed workbench guide (Chinese).

Validation and limits

Tested on Windows / RTX 5090 Laptop 24GB / 64GB RAM. Current multi-engine inference, portable-runtime checks and remaining acceptance work are in VALIDATION.md; earlier real ComfyUI 512 and standalone 512/1024/1536 refinement runs remain historical evidence. Automated tests, HTTP inference and browser checks are recorded separately. Lower-VRAM GPUs have not been validated. PyTorch tensor peaks are not total GPU memory requirements.

Windows Hi3D uses an explicitly identified SDPA compatibility adapter; workbench TRELLIS.2 can independently select a validated native FlashAttention wheel. These are not the official Linux environment. Hi3D normalizes scale and rebuilds topology; its refinement stage produces geometry only. Results are not guaranteed watertight, printable or more accurate than the input; inspect both versions before export.

The bundled TRELLIS Windows extensions require CUDA compute capability 8.6+; this excludes RTX 20-series and A100 (8.0) for that stage. Passing this architecture check is not a VRAM or device-validation guarantee.

License and attribution

Original integration code: MIT. The derived community GPU UV adapter retains GPL-3.0. UltraTex additionally uses the GPL-3.0 Comfy inference library in the isolated workbench runtime and a FLUX Non-Commercial base model; these licenses remain separate. Hi3D weights and upstream code: Hi3D Open License v1.0, with their original notices; encoder and runtime licenses remain separate. This is a community integration. See NOTICE.md. Powered by Hi3D 1.0.

T8star

Bilibili · YouTube · API · Free Gallery · Online AI Apps · ComfyUI Distribution · Hugging Face