Image Alphabet Index Translator

/**
 * Converts an image into a grid of characters based on pixel brightness and a provided alphabet.
 *
 * @param {Image} originalImg The original javascript Image object to process.
 * @param {string} [alphabet=' .:-=+*#%@'] A string of characters to use for the translation, ordered from darkest to brightest representation.
 * @param {number} [size=120] The desired width of the output in characters. The height is calculated based on the image's aspect ratio.
 * @returns {HTMLElement} A <pre> element containing the character-based representation of the image.
 */
function processImage(originalImg, alphabet = ' .:-=+*#%@', size = 120) {
    // 1. Sanitize parameters
    if (!alphabet || typeof alphabet !== 'string' || alphabet.length < 2) {
        // Fallback to a default ramp if the provided alphabet is invalid
        alphabet = ' .:-=+*#%@';
    }
    const numSize = Number(size) || 120;

    // 2. Create a canvas to analyze the image
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d', {
        willReadFrequently: true
    });

    // 3. Calculate dimensions for downsampling
    // We adjust the height based on a common aspect ratio for monospace characters (approx. 0.5 height/width)
    // to prevent the output from looking stretched.
    const aspectRatio = originalImg.height / originalImg.width;
    const newWidth = Math.round(numSize);
    const newHeight = Math.round(newWidth * aspectRatio * 0.5);

    canvas.width = newWidth;
    canvas.height = newHeight;

    // 4. Draw the downsampled image onto the canvas
    ctx.drawImage(originalImg, 0, 0, newWidth, newHeight);

    // 5. Get the pixel data from the canvas
    const imageData = ctx.getImageData(0, 0, newWidth, newHeight);
    const data = imageData.data;
    const alphabetLength = alphabet.length;

    // 6. Build the character string
    let textArt = '';
    for (let y = 0; y < newHeight; y++) {
        for (let x = 0; x < newWidth; x++) {
            const i = (y * newWidth + x) * 4;
            const r = data[i];
            const g = data[i + 1];
            const b = data[i + 2];
            // a = data[i+3]; // Alpha channel, ignored for this purpose

            // Calculate the average brightness of the pixel (0-255)
            const brightness = (r + g + b) / 3;

            // Map the brightness to an index in the provided alphabet string.
            // A brightness of 0 (black) maps to the first character.
            // A brightness of 255 (white) maps to the last character.
            const charIndex = Math.floor((brightness / 255) * (alphabetLength - 1));

            textArt += alphabet.charAt(charIndex);
        }
        textArt += '\n'; // Add a newline character at the end of each row
    }

    // 7. Create a <pre> element to display the result
    const preElement = document.createElement('pre');
    preElement.textContent = textArt;

    // 8. Style the element for proper monospaced display
    preElement.style.fontFamily = 'monospace, Courier, "Courier New"';
    preElement.style.fontSize = '10px';
    preElement.style.lineHeight = '1.0';
    preElement.style.letterSpacing = '0.5px';
    preElement.style.margin = '0';
    preElement.style.padding = '1em';
    preElement.style.backgroundColor = '#f5f5f5';
    preElement.style.color = '#333';
    preElement.style.whiteSpace = 'pre';
    preElement.style.overflowX = 'auto';

    return preElement;
}