Image Alphabet Name Translator Tool

/**
 * Translates an image into a text-based representation using characters from a specified alphabet.
 * This function effectively creates a form of "ASCII art" but can use any set of characters.
 *
 * @param {Image} originalImg The original image object to process.
 * @param {string} [alphabet='ZYXWVUTSRQPONMLKJIHGFEDCBA'] The set of characters to use, ordered from darkest representation to lightest. The default is a reversed alphabet, making 'Z' correspond to dark areas and 'A' to light areas.
 * @param {number} [characterWidth=120] The width of the output text in characters. A higher number results in more detail.
 * @param {number} [invertColors=0] Set to 1 to invert the mapping (light characters for dark areas), suitable for a dark background display.
 * @returns {HTMLElement} A <pre> element containing the text representation of the image, styled for proper display.
 */
function processImage(originalImg, alphabet = 'ZYXWVUTSRQPONMLKJIHGFEDCBA', characterWidth = 120, invertColors = 0) {
    let effectiveAlphabet = alphabet;
    if (!effectiveAlphabet || typeof effectiveAlphabet !== 'string' || effectiveAlphabet.length === 0) {
        // Fallback to a single character if the alphabet is empty or invalid
        effectiveAlphabet = '?';
    }

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

    // 2. Calculate the dimensions of the text output while maintaining aspect ratio.
    // A correction factor is used because monospace characters are typically taller than they are wide.
    const fontAspectRatio = 0.5;
    const newWidth = parseInt(characterWidth, 10) || 120;
    const newHeight = Math.floor(newWidth * (originalImg.height / originalImg.width) * fontAspectRatio);

    if (newWidth <= 0 || newHeight <= 0) {
        const p = document.createElement('p');
        p.textContent = 'Invalid dimensions. Please provide a characterWidth greater than 0.';
        return p;
    }

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

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

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

    // 5. Build the text string by mapping pixel brightness to characters
    let text = '';
    const alphabetLength = effectiveAlphabet.length;

    for (let i = 0; i < data.length; i += 4) {
        // RGB values for the current pixel
        const r = data[i];
        const g = data[i + 1];
        const b = data[i + 2];

        // Calculate the perceived brightness (grayscale value) using the Rec. 709 luma formula
        const brightness = 0.2126 * r + 0.7152 * g + 0.0722 * b;

        // Map the brightness value [0-255] to an index in the alphabet string [0, length-1]
        let charIndex = Math.floor((brightness / 256) * alphabetLength);

        // Invert the index if the user requested it
        if (invertColors == 1) {
            charIndex = (alphabetLength - 1) - charIndex;
        }

        // Add the corresponding character to our text string
        text += effectiveAlphabet[charIndex];

        // If we've reached the end of a row, add a newline character
        const pixelIndex = i / 4;
        if ((pixelIndex + 1) % newWidth === 0) {
            text += '\n';
        }
    }

    // 6. Create the output <pre> element
    const preElement = document.createElement('pre');
    preElement.textContent = text;

    // 7. Apply some basic styling for a good presentation
    preElement.style.fontFamily = 'monospace, Courier New, Courier';
    preElement.style.fontSize = '10px';
    preElement.style.lineHeight = '0.8em';
    preElement.style.letterSpacing = '0.05em';
    preElement.style.margin = '0';
    preElement.style.display = 'inline-block';
    preElement.style.backgroundColor = 'white';
    preElement.style.color = 'black';

    // 8. Return the final element
    return preElement;
}