Image To ASCII Translator Alphabetical Identifier

/**
 * Converts an image to ASCII art using an alphabetical character set.
 * Each character can be colored based on the original image's pixels.
 *
 * @param {HTMLImageElement} originalImg The original image element to process.
 * @param {number} [maxWidth=100] The maximum width of the resulting ASCII art in characters. The height is calculated based on the image's aspect ratio.
 * @param {string} [charset='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'] The character set to use for mapping brightness levels. It's ordered from darkest to brightest.
 * @param {number} [invert=0] If set to 1, the brightness mapping is inverted (light pixels get "darker" characters and vice-versa).
 * @param {number} [useColor=1] If set to 1, each character will be colored according to the average color of the corresponding pixel area in the original image.
 * @returns {HTMLPreElement} A <pre> element containing the generated ASCII art, ready to be displayed.
 */
function processImage(originalImg, maxWidth = 100, charset = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ', invert = 0, useColor = 1) {
    // ---- 1. Parameter Normalization ----
    const numMaxWidth = Number(maxWidth);
    const numInvert = Number(invert);
    const numUseColor = Number(useColor);
    let charMap = String(charset);

    if (charMap.length === 0) {
        // Provide a fallback to prevent errors if an empty charset is given.
        charMap = '@';
    }

    // ---- 2. Canvas Setup and Image Downscaling ----
    // We create a small canvas with the same dimensions as our target character grid.
    // Drawing the original image onto this small canvas effectively averages out
    // the colors and brightness of the pixels that will be represented by a single character.

    const aspectRatio = originalImg.height / originalImg.width;
    // Monospace fonts are typically taller than they are wide (e.g., Courier has a ~1:2 width:height ratio).
    // To make the output aspect ratio look correct, we reduce the vertical sampling resolution.
    // This correction factor makes each character represent a taller block of pixels, compensating for the font's own aspect ratio.
    const fontAspectRatioCorrection = 0.5;
    
    const outputWidth = Math.floor(numMaxWidth);
    const outputHeight = Math.floor(numMaxWidth * aspectRatio * fontAspectRatioCorrection);

    const canvas = document.createElement('canvas');
    canvas.width = outputWidth > 0 ? outputWidth : 1;
    canvas.height = outputHeight > 0 ? outputHeight : 1;
    const ctx = canvas.getContext('2d', { willReadFrequently: true });
    ctx.drawImage(originalImg, 0, 0, canvas.width, canvas.height);
    
    const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height).data;

    // ---- 3. ASCII Generation ----
    const pre = document.createElement('pre');
    pre.style.fontFamily = "'Courier New', Courier, monospace";
    pre.style.fontSize = '10px';
    pre.style.lineHeight = '1.0';
    pre.style.letterSpacing = '0.5px';
    pre.style.margin = '0';
    
    // Using an array and join is often more performant for building large strings.
    const contentBuilder = [];

    for (let y = 0; y < outputHeight; y++) {
        for (let x = 0; x < outputWidth; x++) {
            const i = (y * outputWidth + x) * 4;
            const r = imageData[i];
            const g = imageData[i + 1];
            const b = imageData[i + 2];
            // imageData[i + 3] is the alpha channel, which we ignore here.

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

            // Map brightness to a character in our character set.
            const mapValue = numInvert ? (255 - brightness) : brightness;
            const charIndex = Math.floor((mapValue / 255) * (charMap.length - 1));
            const char = charMap[charIndex] || ' '; // Fallback to a space

            if (numUseColor === 1) {
                // To prevent potential HTML injection if the charset contains '<' or '>', we do a basic escape.
                const safeChar = char.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
                contentBuilder.push(`<span style="color:rgb(${r},${g},${b})">${safeChar}</span>`);
            } else {
                contentBuilder.push(char);
            }
        }
        contentBuilder.push('\n');
    }

    // ---- 4. Final Output Assembly ----
    if (numUseColor === 1) {
        pre.style.backgroundColor = '#111'; // A dark background helps colored text stand out.
        pre.innerHTML = contentBuilder.join('');
    } else {
        pre.style.backgroundColor = 'black';
        pre.style.color = 'white';
        pre.textContent = contentBuilder.join('');
    }

    return pre;
}