ComfyUI-UltraShape1

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).

| Parameter | Description | |-----------|-------------| | checkpoint | Select checkpoint file from models/UltraShape/ | | config | Config file (default: infer_dit_refine.yaml) | | dtype | Model precision: float16 / bfloat16 / float32 | | low_vram | Enable low VRAM mode - offload model components to CPU when not in use |

UltraShape Mesh Selector

File upload widget for selecting mesh files.

| Parameter | Description | |-----------|-------------| | mesh | File upload widget - click to upload mesh file |

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

UltraShape Load Coarse Mesh

Load and preprocess coarse mesh for refinement.

| Parameter | Description | |-----------|-------------| | model | Model from Load Model node | | mesh_path | Path to mesh file (supports multiple formats - see below) | | normalize_scale | Mesh normalization scale (default: 0.99) | | num_sharp_points | Number of sharp edge sample points | | num_uniform_points | Number of uniform sample points | | num_latents | Number of latent tokens (default: 768, higher = more detail) |

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.

| Parameter | Description | |-----------|-------------| | model | Model from Load Model node | | coarse_mesh | Mesh from Load Coarse Mesh node | | image | Reference image (IMAGE type) | | steps | Diffusion steps (default: 50) | | guidance_scale | Image guidance scale (default: 5.0) | | octree_resolution | Output mesh resolution (default: 384) | | mc_level | Marching cubes level (default: 0.0) | | box_v | Bounding box scale (default: 1.0) | | seed | Random seed | | remove_bg | Remove image background before processing | | num_chunks | Number of chunks for processing (default: 1, higher = less VRAM) |

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: | Resolution | Approx. VRAM | |------------|--------------| | 384 | ~8GB | | 512 | ~16GB | | 768 | ~32GB | | 1024 | ~48GB+ |

UltraShape Save GLB/OBJ

Save refined mesh to file.

| Parameter | Description | |-----------|-------------| | refined_mesh | Mesh from Refine node | | output_dir | Output subdirectory (default: ultrashape_output) | | filename_prefix | Output filename prefix | | file_format | Export format: glb / obj / ply / stl |

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.