Image Letter Translator Generator

/**
 * Converts an image into a textual representation using characters, similar to ASCII art.
 *
 * @param {Image} originalImg The original javascript Image object.
 * @param {string} characterSet The set of characters to use for rendering, ordered from darkest/densest to lightest/sparsest.
 * @param {number} blockSize The size of the pixel area (in pixels) to sample for each character. Smaller is more detailed.
 * @param {number} fontSize The font size of the characters in the output canvas.
 * @param {string} fontFamily A web-safe or Google font to use for the characters. Monospace fonts work best.
 * @param {string} textColor The color of the characters.
 * @param {string} backgroundColor The background color of the output canvas.
 * @param {number} invert If 1, the character mapping is inverted (light areas get dark characters). If 0, it's normal.
 * @returns {HTMLCanvasElement} A new canvas element with the image rendered as text characters.
 */
function processImage(originalImg, characterSet = '@%#*+=-:. ', blockSize = 10, fontSize = 10, fontFamily = 'monospace', textColor = '#000000', backgroundColor = '#FFFFFF', invert = 0) {
    // 1. Create a temporary canvas to draw the original image and access its pixel data.
    const sourceCanvas = document.createElement('canvas');
    const sourceCtx = sourceCanvas.getContext('2d', { willReadFrequently: true });
    sourceCanvas.width = originalImg.width;
    sourceCanvas.height = originalImg.height;
    sourceCtx.drawImage(originalImg, 0, 0);

    // 2. Prepare the character set. If `invert` is 1, reverse the set.
    let finalCharSet = characterSet;
    if (invert === 1) {
        finalCharSet = characterSet.split('').reverse().join('');
    }

    // 3. Calculate dimensions for the output canvas.
    // We assume a monospace font aspect ratio where width is about 0.6 of height (fontSize).
    const fontAspectRatio = 0.6;
    const outputCols = Math.floor(sourceCanvas.width / blockSize);
    const outputRows = Math.floor(sourceCanvas.height / blockSize);
    const outputWidth = Math.floor(outputCols * fontSize * fontAspectRatio);
    const outputHeight = outputRows * fontSize;

    // 4. Create and configure the output canvas.
    const outputCanvas = document.createElement('canvas');
    const outputCtx = outputCanvas.getContext('2d');
    outputCanvas.width = outputWidth;
    outputCanvas.height = outputHeight;

    // Set background and text styles.
    outputCtx.fillStyle = backgroundColor;
    outputCtx.fillRect(0, 0, outputWidth, outputHeight);
    
    outputCtx.fillStyle = textColor;
    outputCtx.font = `${fontSize}px ${fontFamily}`;
    outputCtx.textAlign = 'left';
    outputCtx.textBaseline = 'top';

    // 5. Iterate over the image in blocks.
    for (let y = 0; y < outputRows; y++) {
        for (let x = 0; x < outputCols; x++) {
            // Get the pixel data for the current block from the source canvas.
            const imageData = sourceCtx.getImageData(x * blockSize, y * blockSize, blockSize, blockSize);
            const data = imageData.data;
            let totalBrightness = 0;

            // Calculate the average brightness of all pixels in the block.
            for (let i = 0; i < data.length; i += 4) {
                const r = data[i];
                const g = data[i + 1];
                const b = data[i + 2];
                // A simple average for brightness.
                const brightness = (r + g + b) / 3;
                totalBrightness += brightness;
            }
            const avgBrightness = totalBrightness / (data.length / 4);

            // 6. Map the average brightness (0-255) to a character in our set.
            const charIndex = Math.floor((avgBrightness / 255) * (finalCharSet.length - 1));
            const char = finalCharSet.charAt(charIndex);

            // 7. Draw the character onto the output canvas.
            if (char) {
                const drawX = Math.floor(x * fontSize * fontAspectRatio);
                const drawY = y * fontSize;
                outputCtx.fillText(char, drawX, drawY);
            }
        }
    }

    // 8. Return the completed canvas.
    return outputCanvas;
}