Image Alphabet Paint Creator

/**
 * Creates an "alphabet paint" version of an image.
 * This function analyzes an image block by block, calculates the average color and brightness of each block,
 * and replaces it with a character from a specified alphabet, colored with the average color.
 * The result is a text-based representation of the original image.
 *
 * @param {Image} originalImg The original JavaScript Image object to process.
 * @param {string} [alphabet=' .:-=+*#%@'] A string of characters to use for painting, ordered from sparse (for light areas) to dense (for dark areas).
 * @param {number} [fontSize=10] The size of the characters and the analysis grid. Smaller numbers yield higher detail.
 * @param {string} [fontFamily='monospace'] The font family for the characters. Monospaced fonts work best for grid alignment.
 * @param {number} [invertBrightness=0] If set to 1, the character mapping is inverted (light areas get dense characters).
 * @returns {HTMLCanvasElement} A new canvas element with the alphabet-painted image.
 */
function processImage(originalImg, alphabet = ' .:-=+*#%@', fontSize = 10, fontFamily = 'monospace', invertBrightness = 0) {
    // Ensure fontSize is a positive integer for block stepping.
    const step = Math.max(1, parseInt(fontSize, 10) || 10);

    // 1. Create a temporary canvas to read pixel data from the original image.
    // Using naturalWidth/Height is safer for images not yet loaded into the DOM.
    const sourceCanvas = document.createElement('canvas');
    const sourceCtx = sourceCanvas.getContext('2d', {
        willReadFrequently: true
    });
    sourceCanvas.width = originalImg.naturalWidth;
    sourceCanvas.height = originalImg.naturalHeight;
    sourceCtx.drawImage(originalImg, 0, 0, sourceCanvas.width, sourceCanvas.height);

    // 2. Get the raw pixel data (a single array of flat R,G,B,A values).
    const imageData = sourceCtx.getImageData(0, 0, sourceCanvas.width, sourceCanvas.height);
    const data = imageData.data;

    // 3. Create the final output canvas.
    const outputCanvas = document.createElement('canvas');
    const outputCtx = outputCanvas.getContext('2d');
    outputCanvas.width = originalImg.naturalWidth;
    outputCanvas.height = originalImg.naturalHeight;

    // Start with a clear canvas, resulting in a transparent background.
    outputCtx.clearRect(0, 0, outputCanvas.width, outputCanvas.height);

    // Set font properties that will be used for drawing the characters.
    outputCtx.font = `${step}px ${fontFamily}`;
    outputCtx.textAlign = 'center';
    outputCtx.textBaseline = 'middle';

    // 4. Loop through the image in blocks of `step x step` pixels.
    for (let y = 0; y < outputCanvas.height; y += step) {
        for (let x = 0; x < outputCanvas.width; x += step) {

            // Calculate the average color (R,G,B,A) for the current block.
            let totalR = 0,
                totalG = 0,
                totalB = 0,
                totalA = 0;
            let count = 0;

            // Iterate over each pixel within the block's boundaries.
            for (let blockY = y; blockY < y + step && blockY < outputCanvas.height; blockY++) {
                for (let blockX = x; blockX < x + step && blockX < outputCanvas.width; blockX++) {
                    const index = (blockY * outputCanvas.width + blockX) * 4;
                    totalR += data[index];
                    totalG += data[index + 1];
                    totalB += data[index + 2];
                    totalA += data[index + 3];
                    count++;
                }
            }

            if (count === 0) continue;

            const avgR = totalR / count;
            const avgG = totalG / count;
            const avgB = totalB / count;
            const avgA = totalA / count;

            // Skip drawing for fully transparent blocks to save performance.
            if (avgA < 1) continue;

            // 5. Convert the average color to a brightness value and select a character.
            // Standard luminance formula gives a value between 0 (black) and 255 (white).
            const brightness = (0.299 * avgR + 0.587 * avgG + 0.114 * avgB);

            // Normalize brightness to a 0-1 range.
            const normalizedBrightness = brightness / 255;

            let charIndex;
            // Map the brightness value to a character index in the provided alphabet string.
            if (invertBrightness === 1) {
                // Inverted: Bright areas get dense characters (higher index).
                charIndex = Math.floor(normalizedBrightness * alphabet.length);
            } else {
                // Normal: Dark areas get dense characters (higher index).
                charIndex = Math.floor((1 - normalizedBrightness) * alphabet.length);
            }

            // Clamp the index to be safely within the alphabet's bounds.
            charIndex = Math.max(0, Math.min(alphabet.length - 1, charIndex));

            const char = alphabet[charIndex];

            // 6. Draw the selected character on the output canvas with the block's average color.
            if (char) {
                outputCtx.fillStyle = `rgba(${avgR}, ${avgG}, ${avgB}, ${avgA / 255})`;
                // Render the character at the center of the block for proper alignment.
                outputCtx.fillText(char, x + step / 2, y + step / 2);
            }
        }
    }

    // 7. Return the final canvas element.
    return outputCanvas;
}