ComfyUI Extension: ComfyUI Universal Image Loader
A powerful and versatile custom node for ComfyUI that provides multiple ways to load images into your workflows.
Custom Nodes (0)
README
ComfyUI Universal Image Loader
A powerful and versatile custom node for ComfyUI that provides multiple ways to load images into your workflows.
š Features
Multiple Input Methods
- š File Path: Load images from your local file system using ComfyUI's file picker
- š Base64: Paste base64-encoded image strings directly into the node
Smart Input Handling
- Input Precedence: When multiple inputs are provided (especially via API), the node follows a clear precedence order
- Auto-clearing: When you use one input method, other inputs are automatically cleared for clarity
- Visual Feedback: Real-time preview and status indicators for loaded images
- Error Recovery: Robust error handling with informative logging
Advanced Features
- EXIF Rotation: Automatically applies correct image orientation based on EXIF data
- Alpha Channel Support: Properly extracts and processes alpha channels as masks
- Memory Management: Efficient GPU memory handling with automatic cleanup
- Format Support: Works with PNG, JPEG, GIF, WebP, BMP, and other common formats
š¦ Installation
Method 1: Git Clone (Recommended)
cd ComfyUI/custom_nodes/
git clone https://github.com/your-username/comfyui-imgloader.git
Method 2: Manual Download
- Download this repository as a ZIP file
- Extract to
ComfyUI/custom_nodes/comfyui-imgloader/
- Restart ComfyUI
Method 3: ComfyUI Manager
Search for "Universal Image Loader" in ComfyUI Manager and install.
š Usage
Basic Usage
- Add the node to your workflow:
Add Node
āimage
āloaders
āImage Loader (Universal)
- Choose your preferred input method:
- File Path: Click the file selector and choose an image
- Base64: Paste a base64 string into the text area
Input Methods Details
š File Path Input
- Uses ComfyUI's standard file picker
- Supports relative paths (resolved to
ComfyUI/input/
directory) - Validates file existence and readability
š Base64 Input
- Accepts both raw base64 strings and data URLs
- Supports format:
data:image/png;base64,iVBORw0KGgo...
- Or raw base64:
iVBORw0KGgoAAAANSUhEUgAA...
- Validates base64 format before processing
API Usage
When using the ComfyUI API, you can provide multiple inputs. The node follows this precedence order:
- File Path (highest priority)
- Base64 String (lowest priority)
Example API payload:
{
"inputs": {
"filepath": "my_image.png",
"base64": "iVBORw0KGgoAAAANSUhEUgA..."
}
}
In this case, the filepath
input would be used.
š§ Output
The node provides two outputs:
- IMAGE: Standard ComfyUI image tensor (NHWC format, float32, range 0-1)
- MASK: Alpha channel mask or fully opaque mask if no alpha is present
āļø Configuration
Environment Variables
You can set these environment variables to customize behavior:
# Enable debug logging
export COMFYUI_IMGLOADER_DEBUG=1
# Set custom input directory (overrides ComfyUI default)
export COMFYUI_IMGLOADER_INPUT_DIR="/path/to/custom/input"
Node Settings
The node automatically detects and handles:
- Image format and color space
- EXIF orientation data
- Alpha channel presence
- File path resolution
š ļø Development
Project Structure
comfyui-imgloader/
āāā __init__.py # Node registration
āāā imgloader_node.py # Main Python implementation
āāā js/
ā āāā imgloader.js # Frontend JavaScript
āāā .github/
ā āāā copilot-instructions.md
āāā .vscode/
ā āāā tasks.json
āāā README.md
Key Components
Python Backend (imgloader_node.py
)
- Image loading and processing logic
- Tensor format conversion
- Error handling and validation
- Memory management
JavaScript Frontend (js/imgloader.js
)
- UI state management
- Visual feedback
Adding Features
- Fork the repository
- Create a feature branch:
git checkout -b feature/new-feature
- Make your changes
- Test with ComfyUI
- Submit a pull request
š Troubleshooting
Common Issues
"No valid image source found"
- Ensure your image file exists and is readable
- Check that base64 strings are properly formatted
Large images causing memory issues
- The node automatically manages GPU memory
- For very large images, consider resizing before input
- Monitor ComfyUI console for memory warnings
File path not found
- Relative paths are resolved to
ComfyUI/input/
directory - Use absolute paths for files outside the input directory
- Check file permissions and accessibility
Debug Mode
Enable debug logging by setting the environment variable:
export COMFYUI_IMGLOADER_DEBUG=1
This will provide detailed information about:
- Image loading operations
- Input precedence decisions
- Error details and stack traces
- Memory usage information
š Requirements
- ComfyUI (latest version recommended)
- Python 3.8+
- PIL/Pillow
- PyTorch
- NumPy
š License
This project is licensed under the MIT License - see the LICENSE file for details.
š¤ Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Development Setup
- Clone the repository
- Install in development mode:
pip install -e .
- Make your changes
- Test with ComfyUI
- Submit a pull request
š Support
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- ComfyUI Discord: Find us in the #custom-nodes channel
š Changelog
v1.0.0
- Initial release
- File path and base64 support
- Visual feedback and preview
- Robust error handling
- Memory management
- EXIF rotation support
- Alpha channel processing
Made with ā¤ļø for the ComfyUI community