Image To ASCII Converter

/**
 * Converts an image into an ASCII art representation.
 *
 * @param {HTMLImageElement} originalImg The source image object.
 * @param {string} characterRamp Optional. A preset name ('SIMPLE', 'DETAILED', 'BLOCKS') or a custom string of characters ordered from lightest/sparsest to darkest/densest.
 * @param {number} outputWidth Optional. The desired width of the ASCII art in characters.
 * @param {number} fontSize Optional. The font size in pixels for the output text.
 * @param {number} invert Optional. Use 0 for a standard "positive" image (dark characters for dark areas). Use 1 for an inverted "negative" image (light characters for dark areas).
 * @returns {HTMLPreElement} A styled <pre> element containing the generated ASCII art.
 */
function processImage(originalImg, characterRamp = 'SIMPLE', outputWidth = 120, fontSize = 8, invert = 0) {

    // Define preset character ramps, ordered from visually lightest to darkest.
    // The user can also provide their own custom ramp string.
    const ramps = {
        'SIMPLE': ' .:-=+*#%@',
        'DETAILED': ' `\'^",:;Il!i~+_-?][}{1)(|\\/tfjrxnuvczXYUJCLQ0OZmwqpdbkhao*#MW&8%B@$',
        'BLOCKS': ' ▂▃▄▅▆▇█'
    };

    const ramp = ramps.hasOwnProperty(characterRamp) ? ramps[characterRamp] : characterRamp;

    // Create a canvas to work with the image data.
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d', {
        // willReadFrequently is a performance hint for the browser.
        willReadFrequently: true
    });

    // Calculate the height of the downsampled image to maintain the aspect ratio.
    // Monospace characters are typically taller than they are wide.
    // This correction factor squishes the height to make the final output look more proportional.
    const fontAspectRatioCorrection = 0.45;
    const aspectRatio = originalImg.height / originalImg.width;
    const outputHeight = Math.floor(outputWidth * aspectRatio * fontAspectRatioCorrection);

    // Set canvas dimensions to the downsampled size.
    canvas.width = outputWidth;
    canvas.height = outputHeight;

    // Draw the original image onto the canvas, effectively downsampling it.
    ctx.drawImage(originalImg, 0, 0, outputWidth, outputHeight);

    // Get the pixel data from the downsampled image.
    const imageData = ctx.getImageData(0, 0, outputWidth, outputHeight);
    const data = imageData.data;

    let asciiString = "";
    // Iterate over each pixel of the downsampled image.
    for (let y = 0; y < outputHeight; y++) {
        for (let x = 0; x < outputWidth; x++) {
            const i = (y * outputWidth + x) * 4;
            const r = data[i];
            const g = data[i + 1];
            const b = data[i + 2];
            
            // Calculate the brightness of the pixel (a simple average).
            const brightness = (r + g + b) / 3;

            // Determine which value to map to the character ramp.
            // For a standard ("positive") image, high brightness (white) should map to a light character,
            // so we use (255 - brightness). For an inverted ("negative") image, we use brightness directly.
            const mappedValue = (invert === 1) ? brightness : (255 - brightness);

            // Find the corresponding character in the ramp.
            const rampIndex = Math.floor((mappedValue / 255) * (ramp.length - 1));
            const char = ramp[rampIndex];

            asciiString += char;
        }
        asciiString += '\n'; // Add a newline at the end of each row.
    }

    // Create the final output element. A <pre> tag is used to respect whitespace and newlines.
    const preElement = document.createElement('pre');
    preElement.textContent = asciiString;
    
    // Apply styling to ensure the ASCII art displays correctly.
    preElement.style.fontFamily = 'monospace';
    preElement.style.fontSize = `${fontSize}px`;
    preElement.style.lineHeight = '1.0'; // Use a tight line height for a cohesive image.
    preElement.style.margin = '0';
    preElement.style.display = 'inline-block'; // Makes the element behave more like an image block.
    
    return preElement;
}