Image Alphabet Translator

/**
 * Translates an image into ASCII art.
 * @param {HTMLImageElement} originalImg The original image element to process.
 * @param {string} characterRamp A string of characters to use for mapping brightness, from darkest to lightest.
 * @param {number} outputWidth The desired width of the output ASCII art in characters. Height is calculated automatically to preserve aspect ratio.
 * @param {number} invertColors A flag to invert the brightness mapping (0 = normal, 1 = inverted).
 * @returns {HTMLPreElement} A <pre> element containing the generated ASCII art.
 */
function processImage(originalImg, characterRamp = '@%#*+=-:. ', outputWidth = 100, invertColors = 0) {
    // 1. Create a canvas and get its 2D rendering context.
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d', { willReadFrequently: true });

    // 2. Calculate the dimensions for the output.
    // We adjust the height to compensate for the fact that characters in monospace fonts
    // are typically taller than they are wide. A factor of 0.45-0.5 is common.
    const aspectRatioCorrection = 0.45;
    const originalWidth = originalImg.width;
    const originalHeight = originalImg.height;

    const canvasWidth = parseInt(outputWidth, 10) || 100;
    const canvasHeight = Math.round(canvasWidth * (originalHeight / originalWidth) * aspectRatioCorrection);
    
    canvas.width = canvasWidth;
    canvas.height = canvasHeight;

    // 3. Draw the original image onto the canvas, effectively downsampling it.
    ctx.drawImage(originalImg, 0, 0, canvas.width, canvas.height);

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

    let asciiString = '';
    
    // Reverse the character ramp if the invert option is selected.
    const ramp = invertColors == 1 ? characterRamp.split('').reverse().join('') : characterRamp;
    const rampLength = ramp.length;

    // 5. Iterate through each pixel of the downsampled image.
    for (let y = 0; y < canvas.height; y++) {
        for (let x = 0; x < canvas.width; x++) {
            // Get the RGBA components for the current pixel.
            const offset = (y * canvas.width + x) * 4;
            const r = data[offset];
            const g = data[offset + 1];
            const b = data[offset + 2];
            // The alpha component (data[offset + 3]) is ignored.

            // Calculate the grayscale value (brightness) using a standard formula.
            const gray = 0.299 * r + 0.587 * g + 0.114 * b;
            
            // Map the grayscale value (0-255) to an index in our character ramp.
            const charIndex = Math.floor((gray / 255) * (rampLength - 1));
            const char = ramp.charAt(charIndex);
            
            asciiString += char;
        }
        asciiString += '\n'; // Add a newline at the end of each row.
    }

    // 6. Create the final output element. A <pre> tag is ideal for preserving whitespace and using monospace fonts.
    const outputElement = document.createElement('pre');
    outputElement.textContent = asciiString;
    
    // Style the element for optimal viewing.
    outputElement.style.fontFamily = "'Courier New', Courier, monospace";
    outputElement.style.lineHeight = '0.9'; // Tighter line height for a denser look.
    outputElement.style.whiteSpace = 'pre';
    outputElement.style.margin = '0';
    outputElement.style.padding = '5px';
    outputElement.style.display = 'inline-block';
    outputElement.style.backgroundColor = '#000'; // Dark background
    outputElement.style.color = '#fff'; // Light text

    // Dynamically calculate font size to make the output fit a reasonable width (~600px).
    const calculatedFontSize = (600 / canvasWidth) * 1.5;
    outputElement.style.fontSize = `${Math.max(2, calculatedFontSize)}px`;

    // 7. Return the styled <pre> element.
    return outputElement;
}