Image Text Index Tool

/**
 * Converts an image into a grid of text characters, creating a "text index" or ASCII art effect.
 * Each character in the grid represents the brightness of the corresponding area in the original image.
 * The term "index" refers to the string of characters used to map brightness levels to symbols.
 *
 * @param {Image} originalImg The original HTML Image object to process.
 * @param {string} [characters='@%#*+=-:. '] A string of characters for mapping brightness, ordered from darkest/densest to lightest/sparsest.
 * @param {number} [fontSize=10] The size of each character cell, affecting the resolution of the output.
 * @param {string} [fontColor='source'] The color of the text. Can be a standard CSS color string (e.g., '#00FF00', 'green') or the special value 'source' to use the average color from the image for each character.
 * @param {string} [backgroundColor='#000000'] The background color of the output canvas.
 * @param {string} [invert='false'] If 'true', light areas of the image get dense characters and dark areas get sparse ones.
 * @param {string} [fontName='monospace'] The font for the characters. Monospace fonts (like 'Courier New', 'Consolas', 'monospace') are recommended for proper grid alignment.
 * @returns {Promise<HTMLCanvasElement>} A promise that resolves with a canvas element containing the generated text-based image.
 */
async function processImage(originalImg, characters = '@%#*+=-:. ', fontSize = 10, fontColor = 'source', backgroundColor = '#000000', invert = 'false', fontName = 'monospace') {
    // 1. Parameter parsing and validation
    const fSize = Math.max(1, parseInt(fontSize) || 10);
    const invertBool = invert.toString().toLowerCase() === 'true';
    const useSourceColor = fontColor.toString().toLowerCase() === 'source';
    
    // Ensure we have a character set to work with, even if an empty string is passed.
    const charSet = (!characters || characters.length === 0) ? '@%#*+=-:. ' : characters;
    
    // 2. Canvas Setup
    const canvas = document.createElement('canvas');
    // Using { willReadFrequently: true } can optimize repeated getImageData calls on some browsers.
    const ctx = canvas.getContext('2d', { willReadFrequently: true });
    
    canvas.width = originalImg.naturalWidth;
    canvas.height = originalImg.naturalHeight;

    // 3. Get Pixel Data from original image
    // Use a temporary canvas to get image data without affecting the final canvas
    const tempCanvas = document.createElement('canvas');
    const tempCtx = tempCanvas.getContext('2d', { willReadFrequently: true });
    tempCanvas.width = canvas.width;
    tempCanvas.height = canvas.height;
    tempCtx.drawImage(originalImg, 0, 0);
    const imageData = tempCtx.getImageData(0, 0, tempCanvas.width, tempCanvas.height);
    const data = imageData.data;

    // 4. Prepare final canvas for drawing
    ctx.fillStyle = backgroundColor;
    ctx.fillRect(0, 0, canvas.width, canvas.height);
    
    // Attempt to load the font to ensure it's ready before drawing.
    try {
        await document.fonts.load(`${fSize}px ${fontName}`);
    } catch (e) {
        console.warn(`Font '${fontName}' could not be loaded, falling back to monospace.`, e);
        fontName = 'monospace'; // Fallback to a safe font
    }
    
    ctx.font = `${fSize}px ${fontName}`;
    ctx.textAlign = 'center';
    ctx.textBaseline = 'middle';

    // 5. Main loop to process image blocks
    for (let y = 0; y < canvas.height; y += fSize) {
        for (let x = 0; x < canvas.width; x += fSize) {
            
            // --- Calculate average color and brightness for the block ---
            let totalR = 0, totalG = 0, totalB = 0;
            let count = 0;

            for (let blockY = 0; blockY < fSize; blockY++) {
                for (let blockX = 0; blockX < fSize; blockX++) {
                    const pixelY = y + blockY;
                    const pixelX = x + blockX;

                    if (pixelX < canvas.width && pixelY < canvas.height) {
                        const index = (pixelY * canvas.width + pixelX) * 4;
                        totalR += data[index];
                        totalG += data[index + 1];
                        totalB += data[index + 2];
                        count++;
                    }
                }
            }

            if (count === 0) continue;

            const avgR = totalR / count;
            const avgG = totalG / count;
            const avgB = totalB / count;
            
            // Using the luminance formula for better perceptual brightness
            const brightness = 0.299 * avgR + 0.587 * avgG + 0.114 * avgB;

            // --- Map brightness to a character ---
            const mappedBrightness = invertBool ? 255 - brightness : brightness;
            const charIndex = Math.floor((mappedBrightness / 255) * (charSet.length - 1));
            const char = charSet.charAt(charIndex);

            // --- Set color and draw character ---
            if (useSourceColor) {
                ctx.fillStyle = `rgb(${Math.floor(avgR)}, ${Math.floor(avgG)}, ${Math.floor(avgB)})`;
            } else {
                ctx.fillStyle = fontColor;
            }
            
            if (char) {
                ctx.fillText(char, x + fSize / 2, y + fSize / 2);
            }
        }
    }

    // 6. Return the result
    return canvas;
}