Image Alphabetical Similar Picture Finder

/**
 * Creates a text-based representation of an image by mapping pixel brightness to characters.
 * This function effectively "paints" a similar picture using letters of the alphabet or a custom character set.
 *
 * @param {Image} originalImg The original JavaScript Image object to process.
 * @param {string} [characterSet='ABCDEFGHIJKLMNOPQRSTUVWXYZ'] A string of characters to use for the output. Darker pixels map to earlier characters in the string, brighter pixels map to later characters.
 * @param {number} [fontSize=8] The font size (and thus the resolution block size) for the characters in the output image. Smaller numbers yield higher detail.
 * @param {string} [backgroundColor='white'] The background color of the output canvas.
 * @param {string} [textColor='black'] The color of the characters drawn on the canvas.
 * @returns {HTMLCanvasElement} A new canvas element containing the alphabetical representation of the original image.
 */
function processImage(originalImg, characterSet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', fontSize = 8, backgroundColor = 'white', textColor = 'black') {
    // Sanitize parameters to prevent errors like infinite loops or index out of bounds.
    const safeFontSize = Math.floor(Math.max(1, fontSize));
    const safeCharacterSet = (!characterSet || characterSet.length === 0) ? ' ' : characterSet;
    const charMapLength = safeCharacterSet.length;

    // Create an in-memory canvas to draw the image onto, allowing us to access its pixel data.
    const srcCanvas = document.createElement('canvas');
    srcCanvas.width = originalImg.width;
    srcCanvas.height = originalImg.height;
    // The willReadFrequently hint can optimize performance for repeated getImageData calls.
    const srcCtx = srcCanvas.getContext('2d', {
        willReadFrequently: true
    });
    srcCtx.drawImage(originalImg, 0, 0);

    // Get the raw pixel data (in a [R, G, B, A, R, G, B, A, ...] format) for the entire image.
    const imageData = srcCtx.getImageData(0, 0, srcCanvas.width, srcCanvas.height);
    const data = imageData.data;

    // Create the destination canvas which will hold the final "alphabetical" image.
    const destCanvas = document.createElement('canvas');
    destCanvas.width = srcCanvas.width;
    destCanvas.height = srcCanvas.height;
    const destCtx = destCanvas.getContext('2d');

    // Set up the visual style of the output canvas.
    destCtx.fillStyle = backgroundColor;
    destCtx.fillRect(0, 0, destCanvas.width, destCanvas.height);
    destCtx.fillStyle = textColor;
    destCtx.font = `${safeFontSize}px "Courier New", monospace`; // Use a monospace font for grid alignment.
    destCtx.textAlign = 'center';
    destCtx.textBaseline = 'middle';

    // Iterate through the original image in grid-like blocks.
    // The size of each block is determined by the font size.
    for (let y = 0; y < destCanvas.height; y += safeFontSize) {
        for (let x = 0; x < destCanvas.width; x += safeFontSize) {

            let totalBrightness = 0;
            let pixelCount = 0;

            // Calculate the average brightness for the current block of pixels.
            for (let blockY = y; blockY < y + safeFontSize && blockY < destCanvas.height; blockY++) {
                for (let blockX = x; blockX < x + safeFontSize && blockX < destCanvas.width; blockX++) {
                    // Get the index for the current pixel's red component in the data array.
                    const i = (blockY * destCanvas.width + blockX) * 4;
                    const r = data[i];
                    const g = data[i + 1];
                    const b = data[i + 2];

                    // Use the luminance formula (perceived brightness) for a more accurate grayscale value.
                    const brightness = 0.299 * r + 0.587 * g + 0.114 * b;
                    totalBrightness += brightness;
                    pixelCount++;
                }
            }

            if (pixelCount === 0) continue;

            const avgBrightness = totalBrightness / pixelCount;

            // Map the average brightness (a value from 0 to 255) to a character in the character set.
            const charIndex = Math.round((avgBrightness / 255) * (charMapLength - 1));
            const charToDraw = safeCharacterSet[charIndex];

            // Draw the chosen character onto the destination canvas, centered within its block.
            if (charToDraw) {
                destCtx.fillText(charToDraw, x + safeFontSize / 2, y + safeFontSize / 2);
            }
        }
    }

    return destCanvas;
}