Art Image Alphabet Translator

async function processImage(originalImg, alphabet = '@%#*+=-:. ', resolution = 150, invert = 0) {
    /**
     * Translates an image into a text-based representation using a custom character set (alphabet).
     *
     * @param {Image} originalImg - The source JavaScript Image object.
     * @param {string} [alphabet='@%#*+=-:. '] - A string of characters to use, from darkest to lightest.
     * @param {number} [resolution=150] - The number of characters for the image's longest dimension.
     * @param {number} [invert=0] - Use 1 to invert the brightness mapping (light areas get dark characters).
     */

    // Dynamically load a monospace Google Font ('Roboto Mono') to ensure consistent character width.
    // The FontFace API provides a reliable way to ensure the font is ready before we use it.
    try {
        const font = new FontFace('Roboto Mono', 'url(https://fonts.gstatic.com/s/robotomono/v23/L0x5DF4xlVMF-BfR8bXMIjhGq3-cXbKDO1QE.woff2)');
        if (!document.fonts.has(font)) {
            await font.load();
            document.fonts.add(font);
        }
    } catch (e) {
        console.warn("Could not load Google Font 'Roboto Mono'. Falling back to system monospace font.", e);
    }


    const aspectRatio = originalImg.width / originalImg.height;
    let canvasWidth, canvasHeight;

    // Calculate the dimensions of the small canvas to downsample the image to.
    // This canvas size will correspond to the number of characters in the output.
    if (aspectRatio >= 1) { // Landscape or square image
        canvasWidth = parseInt(resolution);
        // Adjust height to maintain aspect ratio, also account for character aspect ratio (approx 0.5)
        canvasHeight = Math.round((canvasWidth / aspectRatio) * 0.5);
    } else { // Portrait image
        canvasHeight = parseInt(resolution);
        // Adjust width to maintain aspect ratio
        canvasWidth = Math.round(canvasHeight * aspectRatio * 0.5);
    }

    const canvas = document.createElement('canvas');
    canvas.width = canvasWidth;
    canvas.height = canvasHeight;
    // The { willReadFrequently: true } is a performance hint for the browser.
    const ctx = canvas.getContext('2d', {
        willReadFrequently: true
    });

    // Draw the original image onto the small canvas. This performs a high-quality downsampling.
    ctx.drawImage(originalImg, 0, 0, canvasWidth, canvasHeight);

    // Get the pixel data from the downsampled canvas.
    const imageData = ctx.getImageData(0, 0, canvasWidth, canvasHeight).data;

    let resultText = '';
    const useInvert = Number(invert) === 1;

    // The provided alphabet string is from dark to light. If not inverting, we want to map
    // low brightness (dark) to the start of the string and high brightness (light) to the end.
    // If the user provides an alphabet from light to dark, they can use the invert flag.
    const alphabetChars = alphabet.split('');
    const alphabetLen = alphabetChars.length;

    // Iterate over each pixel of the downsampled image.
    for (let y = 0; y < canvasHeight; y++) {
        for (let x = 0; x < canvasWidth; x++) {
            const index = (y * canvasWidth + x) * 4;
            const r = imageData[index];
            const g = imageData[index + 1];
            const b = imageData[index + 2];

            // Calculate the brightness of the pixel (simple average).
            const brightness = (r + g + b) / 3;

            // Map the brightness value (0-255) to an index in our alphabet array.
            let charIndex;
             if (useInvert) {
                // Map light (255) to index 0 and dark (0) to the last index.
                charIndex = Math.round(( (255 - brightness) / 255) * (alphabetLen - 1));
            } else {
                // Map dark (0) to index 0 and light (255) to the last index.
                charIndex = Math.round((brightness / 255) * (alphabetLen - 1));
            }

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

    // Create a <pre> element to display the result, as it respects whitespace and newlines.
    const preElement = document.createElement('pre');
    preElement.textContent = resultText;

    // Apply styles for a good visual representation.
    preElement.style.fontFamily = "'Roboto Mono', 'Courier New', Courier, monospace";
    preElement.style.fontSize = '10px';
    preElement.style.lineHeight = '1.0';
    preElement.style.letterSpacing = '0.1ch';
    preElement.style.margin = '0';
    preElement.style.display = 'inline-block';
    // To make it responsive, you could use CSS container queries or JavaScript to adjust the font size.
    // For this self-contained function, a fixed size is more reliable.

    return preElement;
}