Image ASCII Art Translator With Alphabet Editor

/**
 * Converts an image into ASCII art text displayed in a <pre> element.
 * The function analyzes the image's brightness and maps pixel blocks to characters
 * from a user-defined alphabet, creating a text-based representation of the image.
 *
 * @param {Image} originalImg The source HTML Image object that has already been loaded.
 * @param {string} [alphabet='@#&%?*+;:-,. '] A string of characters to use for the ASCII art, sorted from visually darkest to lightest.
 * @param {number} [resolution=8] The width in pixels of each block of the original image that corresponds to one ASCII character. Smaller numbers result in higher detail and larger output.
 * @param {number} [contrast=1.0] A factor to adjust the image contrast before conversion. Values greater than 1 increase contrast, while values less than 1 decrease it.
 * @param {number} [invert=0] If set to 1, the brightness-to-character mapping is inverted, using light characters for dark areas and dark characters for light areas.
 * @returns {HTMLPreElement} A <pre> element containing the generated ASCII art, styled for correct aspect ratio and display.
 */
function processImage(originalImg, alphabet = '@#&%?*+;:-,. ', resolution = 8, contrast = 1.0, invert = 0) {
    // 1. Sanitize and coerce parameters
    const validResolution = Math.max(1, parseInt(String(resolution), 10) || 8);
    const contrastFactor = parseFloat(String(contrast));
    const shouldInvert = !!parseInt(String(invert), 10);
    const charSet = String(alphabet).length > 0 ? String(alphabet) : ' ';
    const numChars = charSet.length;

    // Approximate aspect ratio (width/height) for typical monospace fonts.
    // We sample the image in rectangular blocks to compensate for the fact that characters
    // are taller than they are wide, preventing the final ASCII art from looking stretched.
    const FONT_ASPECT_RATIO = 0.55;

    // 2. Create a temporary canvas to downscale the image for efficient analysis
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d', {
        willReadFrequently: true
    });

    // Calculate the dimensions of the ASCII art (in characters)
    const scaledWidth = Math.floor(originalImg.width / validResolution);
    const scaledHeight = Math.floor(originalImg.height / (validResolution / FONT_ASPECT_RATIO));

    // Handle cases where the image is too small for the given resolution
    if (scaledWidth === 0 || scaledHeight === 0) {
        const errorElement = document.createElement('div');
        errorElement.textContent = "Image is too small for the selected resolution to produce any output.";
        errorElement.style.color = "red";
        return errorElement;
    }

    canvas.width = scaledWidth;
    canvas.height = scaledHeight;

    // Drawing the image onto the smaller canvas effectively samples the original image,
    // averaging the colors of the corresponding pixel blocks.
    ctx.drawImage(originalImg, 0, 0, scaledWidth, scaledHeight);

    // 3. Get the raw pixel data from the downscaled image
    const imageData = ctx.getImageData(0, 0, scaledWidth, scaledHeight).data;
    let asciiArt = '';

    // 4. Iterate over the pixel data and build the ASCII string
    for (let y = 0; y < scaledHeight; y++) {
        for (let x = 0; x < scaledWidth; x++) {
            const i = (y * scaledWidth + x) * 4;
            const r = imageData[i];
            const g = imageData[i + 1];
            const b = imageData[i + 2];

            // Calculate brightness using the perceptually-weighted luminosity method
            let brightness = (0.2126 * r + 0.7152 * g + 0.0722 * b);

            // Apply contrast adjustment
            if (!isNaN(contrastFactor) && contrastFactor !== 1.0) {
                brightness = contrastFactor * (brightness - 128) + 128;
                // Clamp the brightness value back into the 0-255 range
                brightness = Math.max(0, Math.min(255, brightness));
            }

            // Map the brightness value (0-255) to an index in our character set
            // A dark pixel (brightness 0) maps to the first character (darkest).
            // A light pixel (brightness 255) maps to the last character (lightest).
            let charIndex = Math.floor((brightness / 255) * (numChars - 1));

            // Invert the mapping if the flag is set
            if (shouldInvert) {
                charIndex = (numChars - 1) - charIndex;
            }

            asciiArt += charSet.charAt(charIndex);
        }
        asciiArt += '\n';
    }

    // 5. Create and style the final <pre> element for display
    const outputElement = document.createElement('pre');
    outputElement.textContent = asciiArt;
    outputElement.style.fontFamily = "'Courier New', Courier, monospace";
    outputElement.style.fontSize = '10px';
    outputElement.style.lineHeight = '1.0em';
    outputElement.style.margin = '0';
    outputElement.style.display = 'inline-block';
    outputElement.style.whiteSpace = 'pre';
    outputElement.style.backgroundColor = 'white';
    outputElement.style.color = 'black';

    return outputElement;
}