Image Character Creator

function processImage(originalImg, widthInCharacters = 100, characterSet = ' .:=-+*#%@', invert = 0, fontSize = 8) {
    // Sanitize parameters to ensure they are the correct type.
    const finalWidth = parseInt(widthInCharacters) || 100;
    const finalFontSize = parseInt(fontSize) || 8;
    const is_inverted = parseInt(invert) === 1;

    // The character ramp should go from representing dark areas to light areas.
    // Low brightness in the image (dark) will map to the start of the string, high brightness (light) to the end.
    // For an inverted image (light background, dark text), we reverse the character ramp.
    const chars = is_inverted ? characterSet.split('').reverse().join('') : characterSet;
    const numChars = chars.length;

    // Handle edge case of an empty character set.
    if (numChars === 0) {
        const errorDiv = document.createElement('div');
        errorDiv.textContent = 'Error: Character set cannot be empty.';
        return errorDiv;
    }

    // This constant corrects the aspect ratio. Characters in monospace fonts are typically
    // taller than they are wide. A value of 0.5 is a good approximation for most monospace fonts.
    const fontAspectRatio = 0.5;

    const scaledWidth = finalWidth;
    const scaledHeight = Math.round(finalWidth * (originalImg.height / originalImg.width) * fontAspectRatio);

    // Handle cases where dimensions are invalid.
    if (scaledWidth <= 0 || scaledHeight <= 0) {
        const errorDiv = document.createElement('div');
        errorDiv.textContent = 'Error: Invalid image or output dimensions.';
        return errorDiv;
    }
    
    // Create a small, off-screen canvas to sample the image pixels.
    const canvas = document.createElement('canvas');
    // Using { willReadFrequently: true } can provide a performance boost when calling getImageData frequently.
    const ctx = canvas.getContext('2d', { willReadFrequently: true });

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

    // Draw the image onto the small canvas. The browser's scaling algorithm
    // will effectively average the pixels in each block for us.
    ctx.drawImage(originalImg, 0, 0, scaledWidth, scaledHeight);

    const imageData = ctx.getImageData(0, 0, scaledWidth, scaledHeight);
    const data = imageData.data;

    // Build the final character string row by row.
    let asciiArt = '';
    for (let y = 0; y < scaledHeight; y++) {
        for (let x = 0; x < scaledWidth; x++) {
            const offset = (y * scaledWidth + x) * 4;
            const r = data[offset];
            const g = data[offset + 1];
            const b = data[offset + 2];
            
            // Calculate brightness using the standard luminance formula for more perceptually
            // accurate gray scaling, which better reflects how humans see light.
            const brightness = 0.299 * r + 0.587 * g + 0.114 * b;

            // Map the brightness (which is in the range 0-255) to an index in our character set string.
            const charIndex = Math.floor((brightness / 255) * (numChars - 1));

            asciiArt += chars[charIndex];
        }
        asciiArt += '\n';
    }

    // Create a <pre> element to display the result, which preserves all whitespace and newlines.
    const preElement = document.createElement('pre');
    preElement.textContent = asciiArt;
    
    // Apply CSS styles to make the output look like proper ASCII art.
    preElement.style.fontFamily = '"Courier New", Courier, monospace';
    preElement.style.fontSize = `${finalFontSize}px`;
    preElement.style.lineHeight = '1.0'; // Tightly packed lines generally look better
    preElement.style.margin = '0';
    preElement.style.display = 'inline-block';
    preElement.style.overflow = 'hidden';
    
    // Set background and text colors based on the invert flag.
    preElement.style.backgroundColor = is_inverted ? 'white' : 'black';
    preElement.style.color = is_inverted ? 'black' : 'white';

    return preElement;
}