Image LED Effect Generator

/**
 * Applies an LED effect to an image by redrawing it with dots or squares.
 *
 * @param {Image} originalImg The original source Image object.
 * @param {number} [ledSize=5] The size (diameter or side length) of each "LED".
 * @param {string} [ledShape='circle'] The shape of the LED. Can be 'circle' or 'square'.
 * @param {number} [ledGap=2] The gap between each LED.
 * @param {string} [backgroundColor='black'] The color of the space between LEDs.
 * @returns {HTMLCanvasElement} A new canvas element with the LED effect applied.
 */
function processImage(originalImg, ledSize = 5, ledShape = 'circle', ledGap = 2, backgroundColor = 'black') {
    // Coerce parameters to their expected types and provide safe fallbacks.
    const size = Math.max(1, Number(ledSize) || 5);
    const gap = Math.max(0, Number(ledGap) || 2);
    const shape = (ledShape === 'square') ? 'square' : 'circle';

    // 1. Create the final canvas and context
    const finalCanvas = document.createElement('canvas');
    const finalCtx = finalCanvas.getContext('2d');

    // Make the final canvas the same size as the original image
    finalCanvas.width = originalImg.width;
    finalCanvas.height = originalImg.height;

    // 2. Fill the canvas with the background color
    finalCtx.fillStyle = backgroundColor;
    finalCtx.fillRect(0, 0, finalCanvas.width, finalCanvas.height);

    // 3. Create a temporary hidden canvas to sample colors from the original image
    const sampleCanvas = document.createElement('canvas');
    const sampleCtx = sampleCanvas.getContext('2d');
    sampleCanvas.width = originalImg.width;
    sampleCanvas.height = originalImg.height;
    sampleCtx.drawImage(originalImg, 0, 0, originalImg.width, originalImg.height);

    // 4. Iterate through the image in steps based on LED size and gap
    const gridSize = size + gap;

    for (let y = 0; y < originalImg.height; y += gridSize) {
        for (let x = 0; x < originalImg.width; x += gridSize) {
            // Determine the dimensions of the block to sample, ensuring it doesn't exceed image bounds.
            const sampleWidth = Math.min(size, originalImg.width - x);
            const sampleHeight = Math.min(size, originalImg.height - y);
            
            if (sampleWidth <= 0 || sampleHeight <= 0) continue;

            // Get the pixel data for the current block
            const imageData = sampleCtx.getImageData(x, y, sampleWidth, sampleHeight);
            const data = imageData.data;
            let r = 0, g = 0, b = 0;

            // Calculate the average color of the block
            const pixelCount = data.length / 4;
            if (pixelCount === 0) continue;

            for (let i = 0; i < data.length; i += 4) {
                r += data[i];
                g += data[i + 1];
                b += data[i + 2];
            }

            r = Math.floor(r / pixelCount);
            g = Math.floor(g / pixelCount);
            b = Math.floor(b / pixelCount);

            // Set the fill style to the calculated average color
            finalCtx.fillStyle = `rgb(${r}, ${g}, ${b})`;

            // 5. Draw the LED shape onto the final canvas
            if (shape === 'circle') {
                finalCtx.beginPath();
                const centerX = x + size / 2;
                const centerY = y + size / 2;
                const radius = size / 2;
                finalCtx.arc(centerX, centerY, radius, 0, Math.PI * 2);
                finalCtx.fill();
            } else { // 'square'
                finalCtx.fillRect(x, y, size, size);
            }
        }
    }

    return finalCanvas;
}