ComfyUI Extension: ComfyUI Universal Image Loader

Authored by negaga53

Created

Updated

0 stars

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

    1. Download this repository as a ZIP file
    2. Extract to ComfyUI/custom_nodes/comfyui-imgloader/
    3. Restart ComfyUI

    Method 3: ComfyUI Manager

    Search for "Universal Image Loader" in ComfyUI Manager and install.

    šŸš€ Usage

    Basic Usage

    1. Add the node to your workflow: Add Node → image → loaders → Image Loader (Universal)
    2. 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:

    1. File Path (highest priority)
    2. 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

    1. Fork the repository
    2. Create a feature branch: git checkout -b feature/new-feature
    3. Make your changes
    4. Test with ComfyUI
    5. 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

    1. Clone the repository
    2. Install in development mode: pip install -e .
    3. Make your changes
    4. Test with ComfyUI
    5. Submit a pull request

    šŸ“ž Support

    šŸ”„ 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