Image Alphabet Search Translator

/**
 * Translates an image into a grid of characters from a specified alphabet
 * based on the brightness of the image's pixels. This creates an effect
 * similar to ASCII art but using a customizable character set.
 *
 * @param {Image} originalImg The original javascript Image object to process.
 * @param {string} [alphabet='ABCDEFGHIJKLMNOPQRSTUVWXYZ'] A string of characters to use for the translation, typically sorted from lightest to darkest visual weight.
 * @param {number} [fontSize=10] The size of the character grid. Smaller numbers provide more detail.
 * @param {string} [backgroundColor='#FFFFFF'] The background color of the output canvas.
 * @param {string} [textColor='#000000'] The color of the text characters.
 * @returns {HTMLCanvasElement} A canvas element with the translated image.
 */
function processImage(originalImg, alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ', fontSize = 10, backgroundColor = '#FFFFFF', textColor = '#000000') {
    // 1. Sanitize parameters and set up constants
    const finalFontSize = Math.max(1, Number(fontSize) || 10);
    const charMap = alphabet && alphabet.length > 0 ? alphabet : 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
    const numChars = charMap.length;
    const imgWidth = originalImg.width;
    const imgHeight = originalImg.height;

    // 2. Create a temporary canvas to get pixel data from the original image
    // This is more performant than reading from the original image directly in some browsers.
    const tempCanvas = document.createElement('canvas');
    tempCanvas.width = imgWidth;
    tempCanvas.height = imgHeight;
    // Using { willReadFrequently: true } is a performance hint for the browser
    const tempCtx = tempCanvas.getContext('2d', {
        willReadFrequently: true
    });
    tempCtx.drawImage(originalImg, 0, 0);
    const imageData = tempCtx.getImageData(0, 0, imgWidth, imgHeight);
    const pixels = imageData.data;

    // 3. Create the output canvas and set its initial state
    const outputCanvas = document.createElement('canvas');
    outputCanvas.width = imgWidth;
    outputCanvas.height = imgHeight;
    const ctx = outputCanvas.getContext('2d');

    // Fill the background
    ctx.fillStyle = backgroundColor;
    ctx.fillRect(0, 0, outputCanvas.width, outputCanvas.height);

    // Set font properties. Using a monospace font is crucial for grid alignment.
    ctx.fillStyle = textColor;
    ctx.font = `${finalFontSize}px monospace`;
    ctx.textAlign = 'center';
    ctx.textBaseline = 'middle';

    // 4. Iterate over the image in a grid
    for (let gridY = 0; gridY < imgHeight; gridY += finalFontSize) {
        for (let gridX = 0; gridX < imgWidth; gridX += finalFontSize) {

            // Get the boundaries of the current pixel block
            const blockXEnd = Math.min(gridX + finalFontSize, imgWidth);
            const blockYEnd = Math.min(gridY + finalFontSize, imgHeight);

            let totalBrightness = 0;
            let pixelCount = 0;

            // 5. Calculate the average brightness of the current block
            for (let y = gridY; y < blockYEnd; y++) {
                for (let x = gridX; x < blockXEnd; x++) {
                    const i = (y * imgWidth + x) * 4; // Index for the pixel's R value
                    const r = pixels[i];
                    const g = pixels[i + 1];
                    const b = pixels[i + 2];

                    // Use the luminosity formula for a perceptually accurate grayscale brightness
                    const brightness = 0.299 * r + 0.587 * g + 0.114 * b;
                    totalBrightness += brightness;
                    pixelCount++;
                }
            }

            const avgBrightness = pixelCount > 0 ? totalBrightness / pixelCount : 0;

            // 6. Map the average brightness (0-255) to a character in the alphabet
            // We want dark areas of the image (low brightness) to map to characters at the end of the alphabet string,
            // and light areas (high brightness) to map to characters at the beginning.
            const brightnessRatio = avgBrightness / 255;
            const charIndex = Math.floor((1 - brightnessRatio) * (numChars - 1));
            const character = charMap[charIndex];

            // 7. Draw the chosen character onto the output canvas
            if (character) {
                // Center the character within its grid cell for a cleaner look
                const centerX = gridX + finalFontSize / 2;
                const centerY = gridY + finalFontSize / 2;
                ctx.fillText(character, centerX, centerY);
            }
        }
    }

    // 8. Return the final canvas element
    return outputCanvas;
}