ComfyUI Extension: ComfyUI-Mircify

Authored by birdneststream

Created

Updated

0 stars

ComfyUI node for converting images to IRC art blocks

Custom Nodes (0)

    README

    ComfyUI-Mircify

    A ComfyUI custom node for converting images into IRC art by processing them in pixel blocks and generating image and text outputs with optimal color selection from a 99-color IRC palette. Now supports both IRC and ANSI terminal text outputs for maximum compatibility.

    This node is used with aibird to convert text prompts to IRC art that is scrolled in the IRC client, and can also output ANSI-formatted text for terminal display.

    Limitations

    • As we have a limited color palette of 99 colors, at times some colors may not match perfect. Overall it matches good enough. I've found the perceptual_weighted followed by weighted_manhattan to be best.
    • 16 colors don't work too well, but I've added this for legacy compatibility with some IRC clients that do not support 99 colors.
    • IRC has a 512 - (ident + host) byte limit per line. If there's too many half blocks rendered, it may go over this limit and break the display of the ASCII art. Rendering the image with a solid background color can help with this, or using fullblock mode.
    • I haven't tried with many widths and heights. The current 640px x 448px is a good fit for making ASCII art that is 80 character blocks wide and 30 character blocks hight. A smaller aspect ratio would fit a lot of half blocks better.

    Workflow

    Workflow Example

    An example workflow is provided in workflows/mircify_example_workflow.json.

    At the moment this example is using qwen image (gguf), lightning 4 step lora with RES4LYF samplers. However any model that is decent at making pixel ansi style art can suffice.

    It will save the irc and ansi data to the png exif data and also to file.

    IRC Output

    Pasting the results of the created .txt file into IRC, we should be able to see the IRC art rendered in the client.

    IRC output

    ANSI Terminal Output

    The node now also generates ANSI-formatted text that can be displayed directly in terminals with 256-color support. The ANSI output uses:

    • 256-color palette: Maps IRC colors to the closest ANSI 256-color equivalents using RGB distance calculations
    • Background colors with spaces: Creates solid color blocks for consistent rendering
    • Half-block support: Uses the ▀ character with foreground/background colors for different top/bottom colors
    • Automatic color reset: Properly resets colors at the end of each line

    To view ANSI output in a terminal:

    cat output/irc_art/your_ansi_file.txt

    or display it with less -R to preserve colors:

    less -R output/irc_art/your_ansi_file.txt

    ANSI output

    Features

    • Universal Image Support: Works with any image dimensions, but remember the IRC 512 byte limit per line.
    • Color Transfer Integration: Uses KMeans clustering with multiple distance methods for accurate color mapping
    • Block Processing: Configurable block sizes (default 8x15 pixels)
    • Half Block Mode: Option for 8x7.5 pixel blocks for finer resolution
    • Dominant Color Extraction: Uses k-means clustering to find the most prominent color in each block
    • Multiple Distance Methods: Choose between weighted manhattan, manhattan, euclidean, and perceptual weighted distance calculations
    • 99-Color IRC Palette: Maps colors to extended IRC color palette
    • 16-Color Compatibility Mode: Option to use traditional 16-color IRC palette
    • Dual Text Output: Returns both IRC-formatted and ANSI-formatted text
    • ANSI Terminal Support: Generate ANSI escape sequences for terminal display with 256-color accuracy
    • Intelligent Output Generation: Only generates text outputs that are connected, optimizing performance
    • Optimized Text Output: Compressed color codes and space-efficient formatting for both IRC and ANSI
    • Text File Export: Save IRC codes directly to text files with timestamp support

    Installation

    1. Clone or download this repository to your ComfyUI custom_nodes directory:

      cd ComfyUI/custom_nodes
git clone https://github.com/birdneststream/ComfyUI-Mircify

    2. Install dependencies:

      cd ComfyUI-Mircify
pip install -r requirements.txt

    3. Restart ComfyUI

    Nodes

    IRC Art Converter

    Category: image/conversion

    Converts images into IRC art with both visual and text output.

    Inputs:

    • image: Input image (any dimensions supported)
    • block_width: Width of each block in pixels (default: 8)
    • block_height: Height of each block in pixels (default: 15)
    • half_block_mode: Enable half-height blocks (8x7.5 instead of 8x15)
    • use_16_colors: Use only first 16 IRC colors for compatibility (default: False)
    • distance_method: Color distance calculation method (weighted_manhattan/manhattan/euclidean/perceptual_weighted)

    Outputs:

    • processed_image: Visual representation of the IRC art conversion
    • irc_text: mIRC-formatted text with color codes ready for IRC clients
    • ansi_text: ANSI-formatted text with 256-color escape sequences for terminal display

    IRC Text Saver

    Category: text/output

    Saves IRC-formatted text to files for easy copying.

    Inputs:

    • irc_text: IRC text from the converter (STRING input)
    • filename: Output filename with {TIMESTAMP} placeholder support (default: "irc_art.txt")

    Outputs:

    • file_path: Absolute path to the saved file

    IRC PNG Exporter

    Category: image/output

    Exports images as PNG files with embedded IRC and ANSI metadata. Displays the image directly within the node interface for preview, with optional file saving functionality.

    Inputs:

    • image: Input image (any dimensions supported)
    • preview: Toggle between preview and save modes (default: True)
    • irc_text: IRC formatted text to embed (optional STRING input)
    • ansi_text: ANSI formatted text to embed (optional STRING input)
    • filename: Output filename when saving with {TIMESTAMP} placeholder support (default: "irc_art_{TIMESTAMP}.png")

    Outputs:

    • No output connectors - displays image directly in the node

    Features:

    • Image Preview: Shows the image with embedded metadata directly within the node interface
    • Metadata Embedding: Stores IRC/ANSI text data in PNG metadata using standard text chunks
    • Flexible Input: Works with just an image, or with optional IRC/ANSI text data
    • Two Modes:
      • Preview Mode (default): Display image with metadata info in the node
      • Save Mode: Export PNG file with embedded metadata to output/irc_art/ directory
    • Metadata Fields: Uses standard PNG text chunks (Description, Comment, Software, Author) for maximum compatibility
    • External Access: Metadata can be extracted using ExifTool, ImageMagick, or Python PIL (see META.md for details)

    Example JSON Metadata Structure:

    {
  "timestamp": "2025-08-27T14:30:45.123456",
  "generator": "ComfyUI-Mircify",
  "version": "1.0",
  "irc": "\u0003\u0003,01█████████████████████████████████████████\u000f",
  "ansi": "\u001b[38;5;15;48;5;0m█████████████████████████████████████████\u001b[0m"
}

    This JSON data is embedded in the PNG's Comment field and can be extracted using:

    exiftool -Comment your_image.png

    Usage

    1. Basic Workflow:

      • Load an image
      • Connect it to "IRC Art Converter"
      • Connect the irc_text output to "IRC Text Saver" (for IRC clients)
      • Optionally connect the ansi_text output to display in terminals
      • New: Connect processed_image, irc_text, and ansi_text to "IRC PNG Exporter" for image preview with embedded metadata
      • Run the workflow

    2. Distance Methods:

      • weighted_manhattan: Manhattan distance with perceptual weights (Green=1.0, Red=0.7, Blue=0.5) for better natural color matching
      • manhattan: Standard Manhattan distance (L1 norm) - fastest calculation
      • euclidean: Standard Euclidean distance (L2 norm) - geometric accuracy
      • perceptual_weighted: Euclidean distance with CIE luminance weights for perceived brightness matching

    3. Block Modes:

      • Full blocks (8x15): Standard IRC character block size
      • Half blocks (8x7.5): Provides finer vertical resolution

    4. Color Modes:

      • 99-color mode: Full extended IRC palette for maximum color accuracy
      • 16-color mode: Traditional IRC colors for better compatibility

    5. Text Output:

      • IRC Output: Uses optimized mIRC color text output ready to paste directly into IRC clients
      • ANSI Output: Uses ANSI 256-color escape sequences for terminal display with accurate color mapping
      • Performance Optimization: Only generates text for outputs that are actually connected to other nodes
      • Support: {TIMESTAMP} placeholder in filenames for IRC Text Saver

    Color Processing

    The node uses a two-stage approach:

    1. Color Transfer Phase: Applies KMeans clustering with configurable distance methods to map the entire image to the IRC color palette
    2. Block Processing Phase: Divides the color-corrected image into blocks using dominant color extraction and generates the final IRC art output

    IRC Color Palette

    The node uses an extended 99-color IRC palette built in. It also can support just 16 colors.

    For more information about how IRC uses colors refer to these resources:

    Requirements

    • ComfyUI
    • Python 3.8+
    • torch
    • numpy
    • scikit-learn
    • Pillow

    Credits

    • Color transfer logic adapted from ComfyUI-Color_Transfer by 45uee
    • Uses KMeans clustering with modified multiple distance methods for optimal color mapping

    License

    MIT License