Image Character Translator Using Alphabet From Photo

/**
 * Translates an image into a text-character representation using a specified alphabet.
 * Each block of pixels in the original image is converted into a single character,
 * with the character chosen from the alphabet based on the block's average brightness.
 * The character is colored with the block's average color.
 *
 * @param {Image} originalImg The source image object to process.
 * @param {string} [alphabet=' .:-=+*#%@'] A string of characters to use for the translation, ordered from darkest to brightest.
 * @param {number} [charWidth=8] The width (in pixels) of each block in the source image to be converted into a single character.
 * @param {number} [charHeight=12] The height (in pixels) of each block in the source image to be converted into a single character.
 * @param {string} [bgColor='#000000'] The background color of the output canvas.
 * @returns {HTMLCanvasElement} A new canvas element displaying the character-based representation of the image.
 */
function processImage(originalImg, alphabet = ' .:-=+*#%@', charWidth = 8, charHeight = 12, bgColor = '#000000') {
    // --- 1. Input Validation and Sanitization ---
    const finalAlphabet = (typeof alphabet === 'string' && alphabet.length > 0) ? alphabet : ' .:-=+*#%@';
    const blockWidth = Math.max(1, Math.floor(charWidth));
    const blockHeight = Math.max(1, Math.floor(charHeight));

    // --- 2. Create a temporary canvas to read image pixel data ---
    const inputCanvas = document.createElement('canvas');
    const inputCtx = inputCanvas.getContext('2d', {
        willReadFrequently: true
    });
    inputCanvas.width = originalImg.naturalWidth;
    inputCanvas.height = originalImg.naturalHeight;
    inputCtx.drawImage(originalImg, 0, 0);

    // --- 3. Calculate grid dimensions ---
    const numCols = Math.floor(inputCanvas.width / blockWidth);
    const numRows = Math.floor(inputCanvas.height / blockHeight);

    // Guard against zero-sized output if the image is smaller than a block
    if (numCols === 0 || numRows === 0) {
        const emptyCanvas = document.createElement('canvas');
        emptyCanvas.width = 1;
        emptyCanvas.height = 1;
        const ctx = emptyCanvas.getContext('2d');
        ctx.fillStyle = bgColor;
        ctx.fillRect(0, 0, 1, 1);
        return emptyCanvas;
    }

    // --- 4. Prepare the output canvas ---
    const outputCanvas = document.createElement('canvas');
    const outputCtx = outputCanvas.getContext('2d');

    // Use a monospace font for a consistent grid layout.
    // The font size is based on the block height for a direct mapping.
    const fontSize = blockHeight;
    outputCtx.font = `${fontSize}px monospace`;

    // Measure a character's width to size the canvas correctly.
    const fontCellWidth = outputCtx.measureText('W').width;

    outputCanvas.width = Math.ceil(numCols * fontCellWidth);
    outputCanvas.height = Math.ceil(numRows * fontSize);

    // --- 5. Set background and font properties for the output ---
    outputCtx.fillStyle = bgColor;
    outputCtx.fillRect(0, 0, outputCanvas.width, outputCanvas.height);

    outputCtx.font = `${fontSize}px monospace`;
    outputCtx.textBaseline = 'top';
    outputCtx.textAlign = 'left';

    // --- 6. Get the raw pixel data from the input image ---
    const imageData = inputCtx.getImageData(0, 0, inputCanvas.width, inputCanvas.height);
    const data = imageData.data;
    const alphabetLength = finalAlphabet.length;

    // --- 7. Process each block of the image ---
    for (let j = 0; j < numRows; j++) { // Current row
        for (let i = 0; i < numCols; i++) { // Current column

            const startX = i * blockWidth;
            const startY = j * blockHeight;

            let totalBrightness = 0;
            let totalR = 0;
            let totalG = 0;
            let totalB = 0;
            let pixelCount = 0;

            // Loop through all pixels within the current block
            for (let y = 0; y < blockHeight; y++) {
                for (let x = 0; x < blockWidth; x++) {
                    const px = startX + x;
                    const py = startY + y;

                    const index = (py * inputCanvas.width + px) * 4;
                    const r = data[index];
                    const g = data[index + 1];
                    const b = data[index + 2];

                    // Use a perceptually weighted formula for brightness
                    const brightness = 0.299 * r + 0.587 * g + 0.114 * b;

                    totalBrightness += brightness;
                    totalR += r;
                    totalG += g;
                    totalB += b;
                    pixelCount++;
                }
            }

            const avgBrightness = totalBrightness / pixelCount;
            const avgR = Math.floor(totalR / pixelCount);
            const avgG = Math.floor(totalG / pixelCount);
            const avgB = Math.floor(totalB / pixelCount);

            // Map the average brightness (0-255) to a character from the alphabet.
            // A slightly larger divisor prevents an out-of-bounds error for pure white.
            const charIndex = Math.floor((avgBrightness / 255.001) * alphabetLength);
            const character = finalAlphabet[charIndex];

            // Draw the selected character on the output canvas, colored with the block's average color
            outputCtx.fillStyle = `rgb(${avgR}, ${avgG}, ${avgB})`;
            outputCtx.fillText(
                character,
                i * fontCellWidth,
                j * fontSize
            );
        }
    }

    return outputCanvas;
}