Image To ASCII Art Translator

/**
 * Converts an image into ASCII art and renders it onto a canvas.
 *
 * This function takes an image, scales it down to a grid, and replaces
 * each grid cell with a character based on its brightness, creating an ASCII art representation.
 * The final artwork is drawn onto a new canvas element.
 *
 * @param {HTMLImageElement} originalImg The source image element to convert.
 * @param {string} [characterSet="@%#*+=-:. "] A string of characters used for rendering, ordered from darkest/densest to lightest/sparsest.
 * @param {number} [scale=0.15] A factor to determine the ASCII art's character resolution. Smaller values (e.g., 0.1) produce more characters and detail, while larger values (e.g., 0.5) produce fewer. This value is multiplied by the image dimensions to get the number of characters.
 * @param {number} [contrast=0] A value from -255 to 255 to adjust the image contrast before conversion. A value of 0 means no change. Positive values increase contrast, negative values decrease it.
 * @returns {HTMLCanvasElement} A new canvas element displaying the generated ASCII art.
 */
function processImage(originalImg, characterSet = "@%#*+=-:. ", scale = 0.15, contrast = 0) {
    // Create a temporary canvas to sample image data
    const tempCanvas = document.createElement('canvas');
    // Using { willReadFrequently: true } can optimize repeated getImageData calls
    const tempCtx = tempCanvas.getContext('2d', {
        willReadFrequently: true
    });

    // Calculate the dimensions of the character grid based on the scale parameter.
    // We use a font aspect ratio correction to prevent the output from looking vertically stretched.
    const fontAspectRatio = 0.5;
    const charGridWidth = Math.floor(originalImg.width * scale);
    const charGridHeight = Math.floor(originalImg.height * scale * fontAspectRatio);

    // Handle cases where the calculated grid is too small to process.
    if (charGridWidth === 0 || charGridHeight === 0) {
        const errorCanvas = document.createElement('canvas');
        errorCanvas.width = 250;
        errorCanvas.height = 40;
        const errorCtx = errorCanvas.getContext('2d');
        errorCtx.font = '14px sans-serif';
        errorCtx.fillStyle = 'red';
        errorCtx.fillText('Error: Output is too small.', 10, 15);
        errorCtx.fillText('Try increasing the "scale" parameter.', 10, 35);
        return errorCanvas;
    }

    tempCanvas.width = charGridWidth;
    tempCanvas.height = charGridHeight;

    // Draw the scaled-down version of the original image onto the temporary canvas.
    tempCtx.drawImage(originalImg, 0, 0, charGridWidth, charGridHeight);

    // Get the raw pixel data (RGBA values) from the temporary canvas.
    const imageData = tempCtx.getImageData(0, 0, charGridWidth, charGridHeight);
    const data = imageData.data;

    // Prepare variables for the conversion loop.
    const contrastFactor = (259 * (contrast + 259)) / (259 * (259 - contrast));
    const numChars = characterSet.length - 1;
    const asciiLines = [];

    // Iterate through each pixel of the scaled-down image data.
    for (let y = 0; y < charGridHeight; y++) {
        let currentLine = '';
        for (let x = 0; x < charGridWidth; x++) {
            const offset = (y * charGridWidth + x) * 4;
            const r = data[offset];
            const g = data[offset + 1];
            const b = data[offset + 2];

            // Convert the RGB pixel to a single grayscale value using the luminosity method.
            let gray = 0.2126 * r + 0.7152 * g + 0.0722 * b;

            // Apply contrast adjustment if a non-zero value is provided.
            if (contrast !== 0) {
                gray = contrastFactor * (gray - 128) + 128;
                // Clamp the value to ensure it stays within the 0-255 range.
                gray = Math.max(0, Math.min(255, gray));
            }

            // Map the grayscale value (0-255) to an index in the character set string.
            const charIndex = Math.round((gray / 255) * numChars);
            currentLine += characterSet[charIndex] || ' '; // Use a fallback for safety.
        }
        asciiLines.push(currentLine);
    }

    // Create the final output canvas to draw the ASCII text onto.
    const outputCanvas = document.createElement('canvas');
    const outputCtx = outputCanvas.getContext('2d');

    // --- Dynamic Sizing ---
    // To maintain readability, we'll make the output canvas have the same width
    // as the original image and calculate the font size dynamically.
    const targetWidth = originalImg.width > 0 ? originalImg.width : 500;
    
    // Calculate the required width for each character to fill the target width.
    const charRenderWidth = targetWidth / charGridWidth;

    // Estimate font size. Monospace fonts are typically taller than they are wide.
    // A width-to-height ratio of ~0.6 is common (i.e., width = 0.6 * fontSize).
    const fontSize = charRenderWidth / 0.6;
    const lineHeight = fontSize * 0.85; // A reasonable line height.

    // Set the final canvas dimensions based on the calculated sizes.
    outputCanvas.width = targetWidth;
    outputCanvas.height = Math.ceil(lineHeight * charGridHeight);

    // --- Drawing ---
    outputCtx.font = `${fontSize}px monospace`;
    outputCtx.textBaseline = 'top';

    const backgroundColor = 'white';
    const textColor = 'black';

    // Draw the background color.
    outputCtx.fillStyle = backgroundColor;
    outputCtx.fillRect(0, 0, outputCanvas.width, outputCanvas.height);

    // Draw each line of ASCII text onto the canvas.
    outputCtx.fillStyle = textColor;
    for (let i = 0; i < asciiLines.length; i++) {
        outputCtx.fillText(asciiLines[i], 0, i * lineHeight);
    }

    return outputCanvas;
}