Image To Dot Art Creator

function processImage(originalImg, dotSize = 10, gap = 0, dotShape = 'circle', backgroundColor = 'transparent') {
    // Validate and sanitize parameters
    dotSize = Number(dotSize);
    gap = Number(gap);

    if (isNaN(dotSize) || dotSize <= 0) {
        console.warn("Invalid dotSize provided. Defaulting to 10.");
        dotSize = 10;
    }
    if (isNaN(gap) || gap < 0) {
        console.warn("Invalid gap provided. Defaulting to 0.");
        gap = 0;
    }
    if (dotShape !== 'circle' && dotShape !== 'square') {
        console.warn("Invalid dotShape provided. Defaulting to 'circle'.");
        dotShape = 'circle';
    }

    const imgWidth = originalImg.naturalWidth || originalImg.width;
    const imgHeight = originalImg.naturalHeight || originalImg.height;

    // Handle cases where the image might not be loaded or has no dimensions
    if (imgWidth === 0 || imgHeight === 0) {
        console.error("Image has zero width or height. Cannot process.");
        const errorCanvas = document.createElement('canvas');
        errorCanvas.width = 100; // Return a small canvas indicating error
        errorCanvas.height = 30;
        const errCtx = errorCanvas.getContext('2d');
        errCtx.fillStyle = 'red';
        errCtx.fillRect(0,0,errorCanvas.width, errorCanvas.height);
        errCtx.fillStyle = 'white';
        errCtx.font = '12px Arial';
        errCtx.textAlign = 'center';
        errCtx.textBaseline = 'middle';
        errCtx.fillText('Invalid Image', errorCanvas.width / 2, errorCanvas.height / 2);
        return errorCanvas;
    }

    // Create the destination canvas for the dot art
    const destCanvas = document.createElement('canvas');
    destCanvas.width = imgWidth;
    destCanvas.height = imgHeight;
    const destCtx = destCanvas.getContext('2d');

    // Draw the specified background color
    if (backgroundColor !== 'transparent') {
        destCtx.fillStyle = backgroundColor;
        destCtx.fillRect(0, 0, imgWidth, imgHeight);
    }

    // For sampling colors accurately, draw the original image onto an offscreen canvas
    // This helps if originalImg is an SVG or needs scaling, though here it's assumed to be a pixel image.
    const srcCanvas = document.createElement('canvas');
    srcCanvas.width = imgWidth;
    srcCanvas.height = imgHeight;
    // { willReadFrequently: true } is a performance hint for contexts where getImageData is called often.
    const srcCtx = srcCanvas.getContext('2d', { willReadFrequently: true });
    srcCtx.drawImage(originalImg, 0, 0, imgWidth, imgHeight);

    const step = dotSize + gap; // The size of each grid cell

    // Iterate over the image in a grid pattern
    for (let y = 0; y * step < imgHeight; y++) {
        for (let x = 0; x * step < imgWidth; x++) {
            const cellX = x * step; // Top-left X of the current cell
            const cellY = y * step; // Top-left Y of the current cell

            // Determine the center point of the cell for sampling color
            // and for placing the dot.
            let samplePosX = Math.floor(cellX + step / 2);
            let samplePosY = Math.floor(cellY + step / 2);

            // Clamp sample coordinates to be within the image bounds
            samplePosX = Math.max(0, Math.min(samplePosX, imgWidth - 1));
            samplePosY = Math.max(0, Math.min(samplePosY, imgHeight - 1));
            
            // Get the color of the pixel at the sample position from the source canvas
            const pixelData = srcCtx.getImageData(samplePosX, samplePosY, 1, 1).data;
            const r = pixelData[0];
            const g = pixelData[1];
            const b = pixelData[2];
            const a = pixelData[3];

            // Set the fill style for the dot using the sampled color
            destCtx.fillStyle = `rgba(${r}, ${g}, ${b}, ${a / 255})`;

            // Calculate the center coordinates for drawing the dot
            const dotCenterX = cellX + step / 2;
            const dotCenterY = cellY + step / 2;

            // Draw the dot based on the chosen shape
            if (dotShape === 'circle') {
                destCtx.beginPath();
                // arc(x, y, radius, startAngle, endAngle)
                destCtx.arc(dotCenterX, dotCenterY, dotSize / 2, 0, 2 * Math.PI);
                destCtx.fill();
            } else if (dotShape === 'square') {
                // fillRect(x, y, width, height) where (x,y) is the top-left corner
                destCtx.fillRect(dotCenterX - dotSize / 2, dotCenterY - dotSize / 2, dotSize, dotSize);
            }
        }
    }

    return destCanvas;
}