Image Alphabet Table Translator

/**
 * Translates an image into a table of colored characters, effectively creating a text-based representation.
 * The tool name "Image Alphabet Table Translator" suggests using alphabet characters, but any character can be used.
 *
 * @param {HTMLImageElement} originalImg - The source image object to process.
 * @param {number} resolution - The number of characters for the width of the output table. Higher values result in more detail.
 * @param {string} character - The character to use in each cell of the table.
 * @param {string} fontColor - The CSS color of the character text. 'transparent' is effective to only show the cell's background color.
 * @param {number} fontSize - The font size of the characters in pixels. This also affects the cell size.
 * @returns {HTMLTableElement|HTMLDivElement} An HTML table element representing the image, or a div with an error message.
 */
function processImage(originalImg, resolution = 80, character = '█', fontColor = 'transparent', fontSize = 8) {
    // 1. Create a canvas to draw the image and access its pixel data.
    const canvas = document.createElement('canvas');
    // Use willReadFrequently hint for potential performance optimization by the browser.
    const ctx = canvas.getContext('2d', {
        willReadFrequently: true
    });

    const imgWidth = originalImg.naturalWidth;
    const imgHeight = originalImg.naturalHeight;

    if (imgWidth === 0 || imgHeight === 0) {
        const errorDiv = document.createElement('div');
        errorDiv.textContent = 'Error: Invalid image dimensions.';
        return errorDiv;
    }

    canvas.width = imgWidth;
    canvas.height = imgHeight;
    ctx.drawImage(originalImg, 0, 0, imgWidth, imgHeight);

    // 2. Define grid dimensions.
    const cols = parseInt(resolution, 10) || 80;

    // To preserve the original image's aspect ratio in the output table, we must
    // account for the aspect ratio of the font character itself. Most monospace fonts
    // have a width-to-height ratio of about 0.5 to 0.6. We use a correction factor
    // to calculate the number of rows needed.
    const fontAspectRatioCorrection = 1.8; // Heuristic value, works well for many monospace fonts.
    const rows = Math.round(cols * (imgHeight / imgWidth) * fontAspectRatioCorrection);

    if (rows <= 0 || cols <= 0) {
        const errorDiv = document.createElement('div');
        errorDiv.textContent = 'Error: Could not calculate table dimensions. Check resolution.';
        return errorDiv;
    }

    const blockWidth = imgWidth / cols;
    const blockHeight = imgHeight / rows;

    // 3. Create the table element that will be our output.
    const table = document.createElement('table');
    const tbody = document.createElement('tbody');
    table.appendChild(tbody);

    // Style the table for a clean, grid-like appearance.
    table.style.borderCollapse = 'collapse';
    table.style.fontFamily = 'monospace, "Courier New", Courier'; // Monospace is crucial.
    table.style.lineHeight = '0.9'; // Adjust for a tighter vertical fit.
    table.style.fontSize = `${fontSize}px`;
    table.style.color = fontColor;
    table.style.backgroundColor = 'black'; // Fallback background.

    // 4. Get pixel data once for performance.
    let imageData;
    try {
        imageData = ctx.getImageData(0, 0, imgWidth, imgHeight).data;
    } catch (e) {
        // Handle potential security errors with getImageData (CORS).
        console.error("Could not get image data. This may be due to a CORS issue.", e);
        const errorDiv = document.createElement('div');
        errorDiv.textContent = 'Error: Could not process image. The image might be from a different domain (CORS issue).';
        errorDiv.style.color = 'red';
        return errorDiv;
    }

    // 5. Loop through the grid, sample colors, and build the table rows and cells.
    for (let y = 0; y < rows; y++) {
        const tr = document.createElement('tr');
        for (let x = 0; x < cols; x++) {
            // For performance, we sample a single pixel from the center of each block
            // instead of averaging all pixels in the block.
            const sampleX = Math.min(imgWidth - 1, Math.floor((x + 0.5) * blockWidth));
            const sampleY = Math.min(imgHeight - 1, Math.floor((y + 0.5) * blockHeight));

            const pixelIndex = (sampleY * imgWidth + sampleX) * 4;
            const r = imageData[pixelIndex];
            const g = imageData[pixelIndex + 1];
            const b = imageData[pixelIndex + 2];
            // const a = imageData[pixelIndex + 3]; // Alpha is not used here but available.

            const td = document.createElement('td');
            // Use a non-breaking space if the character is empty or just a space to ensure the cell renders.
            td.textContent = (character.trim() === '') ? '\u00A0' : character;
            td.style.padding = '0';
            td.style.margin = '0';
            td.style.backgroundColor = `rgb(${r}, ${g}, ${b})`;

            tr.appendChild(td);
        }
        tbody.appendChild(tr);
    }

    return table;
}