ComfyUI-UltraShape1

A ComfyUI plugin based on UltraShape 1.0 for image-guided 3D mesh refinement.

Features

• Mesh Refinement: Refine coarse 3D meshes using image guidance
• High-Quality Output: Generate detailed meshes with sharp edges
• Multiple Export Formats: Export to GLB, OBJ, PLY, STL formats
• Flexible Input: Load meshes via file upload, path string, or output from other nodes
• Configurable Resolution: Adjust output resolution based on available VRAM
• Low VRAM Mode: Offload model components to CPU when not in use
• Chunk Processing: Reduce memory usage during refinement with configurable chunk size

Installation

1. Install Dependencies

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

2. Download Model Weights

Place model weights in ComfyUI's models directory:

ComfyUI/
└── models/
    └── UltraShape/
        └── ultrashape_v1.pt

Download from the HuggingFace https://huggingface.co/infinith/UltraShape/tree/main.

3. Prepare Input Files

Place coarse meshes in ComfyUI's input directory:

ComfyUI/
└── input/
    └── your_coarse_mesh.glb    # or .obj, .ply, .stl

Node Documentation

UltraShape Load Model

Load UltraShape refinement model (VAE + DiT + Conditioner).

UltraShape Mesh Selector

File upload widget for selecting mesh files.

Supported formats: GLB, GLTF, OBJ, PLY, STL

UltraShape Load Coarse Mesh

Load and preprocess coarse mesh for refinement.

Mesh Path Formats:

• Absolute path: C:\path\to\mesh.glb or /path/to/mesh.glb
• Relative to input: input/mesh.glb or just mesh.glb (auto-searches in input folder)
• Relative to output: output/mesh.glb
• From UltraShape Mesh Selector: Connect the output directly

UltraShape Refine

Core refinement node - refine coarse mesh using image guidance.

VRAM Optimization Tips:

• Increase num_chunks to reduce VRAM usage during refinement
• Enable low_vram in Load Model node
• Reduce octree_resolution

VRAM Estimates for octree_resolution:

UltraShape Save GLB/OBJ

Save refined mesh to file.

Example Workflows

Basic Workflow

[Load Image] ──────────────────────────────────────────────────────────┐
                                                                       │
[UltraShape Load Model] ──┬──> [UltraShape Load Coarse Mesh] ──────────┴──> [UltraShape Refine] ──> [UltraShape Save GLB/OBJ]
                          │              ↑
                          │    [UltraShape Mesh Selector] (file upload)

With File Upload

[UltraShape Mesh Selector] ──> mesh_path ──> [UltraShape Load Coarse Mesh]

Low VRAM Workflow

1. Enable low_vram in UltraShape Load Model
2. Set num_chunks to 2-4 in UltraShape Refine
3. Reduce octree_resolution to 384 or lower

Notes

1. VRAM Requirements:

   • Model loading: ~8-12GB VRAM (less with low_vram mode)
   • Refinement (octree_resolution=384): ~8GB additional
   • Refinement (octree_resolution=512): ~16GB additional
   • Total recommended: 16GB+ for default settings, 32GB+ for high resolution

2. Input Requirements:

   • UltraShape is a refinement model, not a generation model
   • You need to provide a coarse mesh (from other 3D generation tools like Hunyuan3D, InstantMesh, etc.)
   • Reference image should match the desired output appearance

3. Optional Dependencies:

   • cubvh: CUDA-accelerated marching cubes (falls back to skimage if not installed)
   • flash_attn: Flash Attention (falls back to PyTorch SDPA if not installed)
   • pymeshlab: Mesh post-processing (optional features disabled if not installed)

4. Supported Mesh Formats:

   • Input: GLB, GLTF, OBJ, PLY, STL
   • Output: GLB, OBJ, PLY, STL

Troubleshooting

Out of Memory (OOM)

• Enable low_vram in Load Model node
• Increase num_chunks in Refine node (try 2-4)
• Reduce octree_resolution (try 384 or 256)
• Use bfloat16 or float16 dtype
• Close other GPU applications

Tensor Size Mismatch

• This can happen with very simple meshes
• The plugin automatically pads voxels to match expected size

Missing Dependencies

• cubvh: Optional, will use slower CPU marching cubes
• flash_attn: Optional, will use PyTorch SDPA
• pymeshlab: Optional, mesh post-processing will be skipped

Mesh File Not Found

• Check the path format (absolute or relative to input/output folder)
• Ensure the file exists and has a supported extension
• Try using UltraShape Mesh Selector for file upload

License

Please refer to the UltraShape 1.0 original project license.