RabbitMesh

Generate 3D meshes from images using AI with scalable fidelity - from quick previews on low-end GPUs to high-detail models. A lightweight Python program built on Tencent's Hunyuan3D-2 model with automatic background removal and mesh optimization.

Features

• Single-image to 3D mesh conversion - Generate complete 3D models from a single photograph
• Automatic background removal - Built-in preprocessing with rembg
• Customizable mesh output - Adjustable face count (from quick low-poly to detailed meshes) ready for use in 3D applications
• GPU accelerated - Fast inference with CUDA support
• Post-processing pipeline - Automatic floater removal, degenerate face cleanup, and face reduction
• Browser extension - Right-click any web image to send directly to RabbitMesh (Chrome/Edge)
• Windows context menu integration - Right-click local image files to open in RabbitMesh

Requirements

• GPU: NVIDIA GPU with CUDA support (tested on GTX 1070 with 8GB VRAM)
• Python: 3.11 or 3.12
• Storage: ~5GB for model file
• OS: Windows (tested), Linux/Mac should work with minor adjustments

Installation

Easy Install (Windows)

1. Clone the repository:

   git clone https://github.com/ovhensik/RabbitMesh.git
   cd RabbitMesh
   

2. Run install.bat - Auto-detects GPU, installs dependencies, and creates launcher

3. Download the model file:

   • Download model.fp16.safetensors (4.9 GB) from Hugging Face (click download arrow ↓)
   • Place in models/ folder

4. Launch: Double-click RabbitMesh.bat

Manual Installation

1. Clone the repository:

   git clone https://github.com/ovhensik/RabbitMesh.git
   cd RabbitMesh
   

2. Install dependencies:

   pip install -r requirements.txt
   pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121  # For GPU
   

3. Download the model:

   • Download model.fp16.safetensors from Hugging Face (click download arrow ↓)
   • Place in models/ folder

Usage

GUI (Recommended)

Launch the graphical interface:

python gui.py

Or if you used Easy Install, simply double-click RabbitMesh.bat

Open with an image pre-loaded:

python gui.py path/to/image.png

The GUI provides:

• Image file browser
• Adjustable parameters (diffusion steps, octree resolution, max faces)
• Real-time progress bar and log output
• One-click mesh generation

Command Line

Basic usage:

python generate_mesh.py input_image.png --out output.obj

The script will:

1. Load and preprocess your image (resize to 518x518 with padding)
2. Remove the background automatically
3. Generate 3D latents using the Hunyuan3D DiT model (~6-8 minutes)
4. Decode to mesh volume and extract surface
5. Post-process: remove floaters, fix degenerate faces, reduce to 10k faces
6. Save as OBJ file

Options

python generate_mesh.py <input_image> --out <output_file.obj>

• input_image: Path to your PNG/JPG image
• --out: Output OBJ file path (default: output.obj)

Environment Variables

• MODEL_FILE: Override model path (default: models/hunyuan3d-dit-v2.safetensors)

Example:

set MODEL_FILE=C:\path\to\model.safetensors
python generate_mesh.py myimage.png

Performance

On GTX 1070 (8GB VRAM):

• Diffusion sampling: ~6 minutes (20 steps)
• VAE decoding: ~1.5 minutes (FlashVDM enabled)
• Post-processing: ~30 seconds
• Total: ~8 minutes per mesh

On more powerful GPUs (RTX 3090, 4090), expect 3-5 minute generation times.

Technical Details

Optimizations Applied

• SDPA attention mode - Scaled Dot Product Attention for faster inference
• FP16 precision - Half-precision to reduce VRAM usage
• FlashVDM decoder - 33x faster volume decoding vs standard method
• Efficient scheduler - FlowMatchEulerDiscreteScheduler for quality/speed balance

Model Parameters

• Diffusion steps: 20 (configurable in code, default workflow uses 30)
• Guidance scale: 5.5
• Octree resolution: 192 (testing), 384 (production quality)
• Output faces: 10,000 (after reduction)

Image Preprocessing

• Resize to 518x518 with aspect-preserving padding
• Background removal via rembg (U2-Net model)
• Normalization to [-1, 1] range

Project Structure

RabbitMesh/
├── generate_mesh.py              # Headless CLI pipeline
├── gui.py                        # Tkinter GUI
├── native_messaging_host.py      # Browser extension bridge
├── install_context_menu.bat      # Windows context menu installer
├── uninstall_context_menu.bat    # Context menu uninstaller
├── browser-extension/            # Chrome/Edge extension
│   ├── manifest.json
│   ├── background.js
│   ├── install_browser_extension.bat   # Browser extension installer
│   ├── uninstall_browser_extension.bat # Browser extension uninstaller
│   ├── native_messaging_host.bat       # Native messaging host launcher
│   └── ...
├── comfyui-hunyuan3dwrapper/     # Hunyuan3D implementation
│   └── hy3dgen/                  # Core generation modules
├── models/                        # Place model file here
│   └── hunyuan3d-dit-v2.safetensors (download separately)
├── requirements.txt               # Python dependencies
└── README.md                      # This file

Troubleshooting

Out of Memory Errors

• Try reducing octree_resolution from 192 to 128 in the code
• Ensure no other GPU-intensive applications are running
• Check available VRAM: nvidia-smi

Slow Generation

• Verify CUDA is available: python -c "import torch; print(torch.cuda.is_available())""
• Ensure you''re using the GPU-enabled PyTorch installation
• Check that dtype=torch.float16 is being used (line ~48)

Import Errors

• Verify all dependencies are installed: pip install -r requirements.txt
• Check that you''re using Python 3.11 or 3.12
• Ensure comfyui-hunyuan3dwrapper folder is present

Credits

• Hunyuan3D-2 Model: Tencent Hunyuan3D
• Original ComfyUI Wrapper: comfyui-hunyuan3dwrapper
• Background Removal: rembg

Optional Integrations

Windows Context Menu (Right-Click on Images)

Add "Send to RabbitMesh" to your right-click menu for image files:

1. Run as Administrator:

   .\install_context_menu.bat
   

2. Right-click any PNG/JPG file → "Send to RabbitMesh" → GUI opens with the image loaded

To remove:

.\uninstall_context_menu.bat

Browser Extension (Chrome/Edge)

Right-click any image on the web → "Send to RabbitMesh" → Downloads and opens in GUI.

Installation:

1. Run as Administrator to register the native messaging host:

   .\install_browser_extension.bat
   

2. Load the extension in your browser:

   • Open chrome://extensions (or edge://extensions)
   • Enable "Developer mode"
   • Click "Load unpacked"
   • Select the browser-extension folder

3. Right-click any image on a webpage → "Send to RabbitMesh"

Note: The native messaging host assumes Python is available at C:\ComfyUI\.venv\Scripts\python.exe. Edit browser-extension\native_messaging_host.bat if your Python path differs.

To remove:

.\uninstall_browser_extension.bat

Then remove the extension from your browser.

License

This project uses code from the ComfyUI Hunyuan3D Wrapper. Please refer to the original repositories for their respective licenses.

The Hunyuan3D-2 model is provided by Tencent under their license terms.