Image To Binary Text Converter With Transparency Handling

/**
 * Converts an image into a binary text representation (0s and 1s),
 * respecting the image's transparency.
 *
 * @param {HTMLImageElement} originalImg The original image element to process.
 * @param {number} [fontSize=8] The size of the font, which also determines the resolution of the output grid.
 * @param {number} [threshold=128] The brightness threshold (0-255) to decide between a '0' (lighter) or a '1' (darker).
 * @param {number} [alphaThreshold=128] The alpha channel threshold (0-255). Pixels with alpha below this value will be treated as transparent and no character will be drawn.
 * @returns {Promise<HTMLCanvasElement>} A promise that resolves with a new canvas element containing the binary text art.
 */
async function processImage(originalImg, fontSize = 8, threshold = 128, alphaThreshold = 128) {
    // Sanitize fontSize to ensure it's a positive integer, preventing infinite loops.
    const step = Math.max(1, Math.floor(fontSize));

    // 1. Create a temporary canvas to read pixel data from the image.
    const tempCanvas = document.createElement('canvas');
    const tempCtx = tempCanvas.getContext('2d', { willReadFrequently: true });
    
    const w = originalImg.naturalWidth;
    const h = originalImg.naturalHeight;
    tempCanvas.width = w;
    tempCanvas.height = h;

    tempCtx.drawImage(originalImg, 0, 0, w, h);
    const imageData = tempCtx.getImageData(0, 0, w, h);
    const data = imageData.data;

    // 2. Create the final output canvas.
    const outputCanvas = document.createElement('canvas');
    const outputCtx = outputCanvas.getContext('2d');
    outputCanvas.width = w;
    outputCanvas.height = h;

    // 3. Configure the drawing context for the output canvas.
    outputCtx.fillStyle = 'black';
    outputCtx.font = `${step}px monospace`;
    outputCtx.textAlign = 'center';
    outputCtx.textBaseline = 'middle';

    // 4. Iterate over the image data in a grid pattern defined by the step size.
    for (let y = 0; y < h; y += step) {
        for (let x = 0; x < w; x += step) {
            // Calculate the index for the top-left pixel of the current grid cell.
            const pixelIndex = (y * w + x) * 4;
            
            const r = data[pixelIndex];
            const g = data[pixelIndex + 1];
            const b = data[pixelIndex + 2];
            const a = data[pixelIndex + 3];

            // 5. Skip this cell if its alpha value is below the threshold.
            if (a < alphaThreshold) {
                continue;
            }

            // 6. Calculate the brightness (luminance) of the pixel.
            const brightness = 0.299 * r + 0.587 * g + 0.114 * b;
            
            // 7. Choose '0' for brighter pixels and '1' for darker pixels.
            const character = brightness > threshold ? '0' : '1';

            // 8. Draw the character centered within its grid cell.
            const drawX = x + step / 2;
            const drawY = y + step / 2;
            outputCtx.fillText(character, drawX, drawY);
        }
    }

    // Return the canvas with the generated binary text art.
    return outputCanvas;
}