Image Address Translator And Alphabet Tool

/**
 * Translates an image into a text-based representation (ASCII/text art).
 * This function fits the description of an "Image Translator and Alphabet tool" by
 * translating image pixels into characters from a user-defined alphabet.
 *
 * @param {Image} originalImg The original source Image object that has already been loaded.
 * @param {string} [alphabet='@%#*+=-:. '] A string of characters to use for the translation, typically ordered from densest/darkest to sparsest/lightest.
 * @param {number} [outputWidth=100] The desired width of the output text art in characters. Height is calculated to maintain aspect ratio.
 * @param {number} [invert=0] If set to 1, the brightness mapping is inverted (light pixels become dense characters, dark pixels become sparse ones). Default is 0 (off).
 * @param {number} [useColor=0] If set to 1, each character will be colored based on the original pixel color. Default is 0 (monochrome text).
 * @returns {HTMLPreElement} A <pre> element containing the generated text art, which can be directly appended to the DOM.
 */
function processImage(originalImg, alphabet = '@%#*+=-:. ', outputWidth = 100, invert = 0, useColor = 0) {
    // 1. Coerce parameters to their expected types for robustness.
    const charAlphabet = String(alphabet);
    const width = parseInt(outputWidth, 10) || 100;
    const shouldInvert = Number(invert) === 1;
    const shouldUseColor = Number(useColor) === 1;
    
    // This correction factor accounts for the fact that monospace characters
    // are typically taller than they are wide. Value may need tweaking for specific fonts.
    const characterAspectRatio = 0.45;

    // 2. Calculate output dimensions while maintaining the original aspect ratio.
    const aspectRatio = originalImg.width / originalImg.height;
    const height = Math.round(width / aspectRatio * characterAspectRatio);

    // 3. Create an off-screen canvas to sample the image at the target resolution.
    const canvas = document.createElement('canvas');
    canvas.width = width;
    canvas.height = height;
    const ctx = canvas.getContext('2d', {
        // Optimization hint for the browser since we'll be reading pixel data.
        willReadFrequently: true 
    });

    // Disable image smoothing to get sharp, distinct color blocks.
    ctx.imageSmoothingEnabled = false;

    // 4. Draw the original image onto our small canvas.
    ctx.drawImage(originalImg, 0, 0, width, height);

    // 5. Get the raw pixel data (RGBA values) from the canvas.
    const imageData = ctx.getImageData(0, 0, width, height);
    const data = imageData.data;

    // 6. Create the <pre> element which will display our final text art.
    const pre = document.createElement('pre');
    pre.style.fontFamily = '"Courier New", Courier, monospace';
    pre.style.fontSize = '10px'; // The visual size will depend on the container.
    pre.style.lineHeight = '0.9'; // Use a tight line height for a cohesive image.
    pre.style.margin = '0';
    pre.style.display = 'inline-block';
    
    // A dark background generally looks best, especially for the colored version.
    if (shouldUseColor) {
        pre.style.backgroundColor = '#111111';
    }

    // 7. Iterate through the pixel data and build the output string.
    let content = '';
    const alphabetLength = charAlphabet.length;

    for (let y = 0; y < height; y++) {
        for (let x = 0; x < width; x++) {
            const i = (y * width + x) * 4;
            const r = data[i];
            const g = data[i + 1];
            const b = data[i + 2];
            // The alpha value (data[i + 3]) is ignored.

            // Calculate the perceived brightness (luminance) of the pixel.
            const brightness = 0.299 * r + 0.587 * g + 0.114 * b;

            // Map the 0-255 brightness value to an index in our character alphabet.
            let charIndex = Math.floor((brightness / 255) * (alphabetLength - 1));

            if (shouldInvert) {
                charIndex = alphabetLength - 1 - charIndex;
            }

            const char = charAlphabet[charIndex] || ' ';
            
            if (shouldUseColor) {
                // For colored output, wrap each character in a <span> with its original color.
                // We must escape HTML-sensitive characters to prevent rendering issues.
                const safeChar = char.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
                content += `<span style="color: rgb(${r},${g},${b})">${safeChar}</span>`;
            } else {
                // For monochrome output, just append the character.
                content += char;
            }
        }
        content += '\n'; // Add a newline at the end of each row.
    }

    // 8. Set the generated content into the <pre> element.
    if (shouldUseColor) {
        pre.innerHTML = content;
    } else {
        pre.textContent = content; // Using .textContent is safer and faster for plain text.
    }

    // 9. Return the final, styled DOM element.
    return pre;
}