Image ASCII Identifier Tool

/**
 * Converts an image into an ASCII art representation.
 * The function maps the brightness of image pixels to a set of ASCII characters.
 *
 * @param {Image} originalImg The original Image object to be converted.
 * @param {number} [outputWidth=100] The desired width of the ASCII art in characters. The height is calculated automatically to maintain aspect ratio.
 * @param {string} [characterSet="@%#*+=-:. "] The set of characters to use for the art, ordered from darkest (most dense) to lightest (most sparse).
 * @returns {HTMLElement} A <pre> element containing the generated ASCII art, styled for proper display.
 */
function processImage(originalImg, outputWidth = 100, characterSet = "@%#*+=-:. ") {
    const canvas = document.createElement('canvas');
    // The 'willReadFrequently' hint can improve performance on some browsers for repeated getImageData calls.
    const ctx = canvas.getContext('2d', {
        willReadFrequently: true
    });

    // Calculate the height of the ASCII art to maintain the image's aspect ratio,
    // adjusted for the typical aspect ratio of a monospace character.
    // A common correction factor is ~0.5, as standard font characters are taller than they are wide.
    const aspectRatio = originalImg.height / originalImg.width;
    const outputHeight = Math.max(1, Math.round(outputWidth * aspectRatio * 0.5));
    outputWidth = Math.max(1, Math.round(outputWidth));

    // Set the canvas dimensions to the desired ASCII art size.
    canvas.width = outputWidth;
    canvas.height = outputHeight;

    // Draw the original image onto the small canvas.
    // This effectively downsamples the image and averages the pixels.
    // We disable image smoothing to get sharper, more distinct "pixel" blocks.
    ctx.imageSmoothingEnabled = false;
    ctx.drawImage(originalImg, 0, 0, canvas.width, canvas.height);

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

    let asciiArt = '';

    // Loop through each "pixel" of the downsampled image grid.
    for (let y = 0; y < outputHeight; y++) {
        for (let x = 0; x < outputWidth; x++) {
            const i = (y * outputWidth + 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 brightness of the pixel using the standard luminosity formula (Rec. 709).
            const brightness = (0.2126 * r + 0.7152 * g + 0.0722 * b);

            // Map the brightness (0-255) to a character in the character set.
            // Low brightness (dark pixel) maps to early characters (e.g., '@').
            // High brightness (light pixel) maps to later characters (e.g., '.').
            const charIndex = Math.min(
                characterSet.length - 1,
                Math.floor((brightness / 255) * characterSet.length)
            );

            asciiArt += characterSet[charIndex] || ' ';
        }
        asciiArt += '\n'; // Add a newline character at the end of each row.
    }

    // Create a <pre> element to display the ASCII art, which preserves whitespace and newlines.
    const pre = document.createElement('pre');
    pre.textContent = asciiArt;

    // Apply some essential styles for a good visual representation.
    pre.style.fontFamily = "'Courier New', Courier, monospace";
    // Adjust font size based on width for better readability.
    pre.style.fontSize = '10px';
    if (outputWidth > 200) {
        pre.style.fontSize = '5px';
    } else if (outputWidth > 150) {
        pre.style.fontSize = '8px';
    }
    pre.style.lineHeight = "1";
    pre.style.margin = "0";
    pre.style.whiteSpace = "pre";
    pre.style.display = "inline-block";
    pre.style.overflow = "auto";
    pre.style.border = "1px solid #ccc";
    pre.style.padding = "10px";

    return pre;
}