Image ASCII Translator And Viewer

/**
 * Converts an image to ASCII art text.
 * The function scales the image down to a specified character width, calculates the brightness
 * of each pixel, and maps it to a character from a given character set.
 *
 * @param {HTMLImageElement} originalImg The input Image object.
 * @param {number} [maxWidth=120] The maximum width of the ASCII output in characters.
 * @param {string} [charSet="@%#*+=-:. "] The string of characters to use for mapping brightness, from darkest to brightest.
 * @param {number} [invert=0] A flag to invert the character mapping. 0 for normal (dark pixels = dense chars), 1 for inverted.
 * @returns {HTMLPreElement} A <pre> element containing the generated ASCII art, ready to be displayed.
 */
function processImage(originalImg, maxWidth = 120, charSet = "@%#*+=-:. ", invert = 0) {
    // Ensure the character set is a non-empty string; provide a default if not.
    const validCharSet = (typeof charSet === 'string' && charSet.length > 0) ? charSet : "@%#*+=-:. ";
    
    // Reverse the character set if inversion is requested. This maps dark pixels to sparse
    // characters and light pixels to dense ones.
    const effectiveCharSet = (invert === 1) 
        ? validCharSet.split('').reverse().join('') 
        : validCharSet;

    // Create a temporary canvas to draw the image and access its pixel data.
    const canvas = document.createElement('canvas');
    // Add willReadFrequently hint for potential performance optimization by the browser.
    const ctx = canvas.getContext('2d', { willReadFrequently: true });

    // Calculate the dimensions for the ASCII art. The height is scaled proportionally
    // to the width, with a correction factor to account for the typical aspect ratio
    // of text characters (they are taller than they are wide).
    const aspectRatio = originalImg.height / originalImg.width;
    const charAspectRatioCorrection = 0.5; 
    const width = Math.round(maxWidth);
    const height = Math.round(width * aspectRatio * charAspectRatioCorrection);

    canvas.width = width;
    canvas.height = height;

    // Draw the image onto the canvas, scaling it down to the target dimensions.
    // Disabling image smoothing helps preserve sharp details which is better for ASCII conversion.
    ctx.imageSmoothingEnabled = false;
    ctx.drawImage(originalImg, 0, 0, width, height);

    // Get the raw pixel data from the canvas as a flat array of [R, G, B, A, R, G, B, A, ...].
    const imageData = ctx.getImageData(0, 0, width, height);
    const data = imageData.data;

    let asciiArt = "";
    
    // Iterate through each sampled pixel of the scaled-down image.
    for (let y = 0; y < height; y++) {
        for (let x = 0; x < width; x++) {
            // Calculate the index for the current pixel in the flat data array.
            const index = (y * width + x) * 4;
            const r = data[index];
            const g = data[index + 1];
            const b = data[index + 2];

            // Calculate the brightness of the pixel using the standard luminosity formula.
            const brightness = (0.299 * r + 0.587 * g + 0.114 * b);

            // Map the brightness value (0-255) to an index in our character set.
            const charIndex = Math.floor((brightness / 255) * (effectiveCharSet.length - 1));
            
            // Append the corresponding character to the result string.
            asciiArt += effectiveCharSet.charAt(charIndex);
        }
        // Add a newline character at the end of each row.
        asciiArt += '\n';
    }

    // Create a <pre> element to display the ASCII art. The <pre> tag respects whitespace
    // and newlines, and is typically styled with a monospaced font by default.
    const outputElement = document.createElement('pre');
    outputElement.textContent = asciiArt;

    // Apply some basic inline styles for better presentation.
    outputElement.style.fontFamily = "monospace, 'Courier New', Courier";
    outputElement.style.lineHeight = "1.0";
    outputElement.style.fontSize = "8px"; // Small font size helps to fit more detail.
    outputElement.style.margin = "0";
    outputElement.style.whiteSpace = "pre";

    return outputElement;
}