Image Pointillism Effect Generator

/**
 * Applies a pointillism effect to an image by redrawing it with dots.
 * Pointillism is a technique of painting in which small, distinct dots of color
 * are applied in patterns to form an image.
 *
 * @param {HTMLImageElement} originalImg The original image element.
 * @param {number} dotSize The average size (diameter for circles, side length for squares) of the dots.
 * @param {number} density The spacing of the grid for placing dots. A smaller number means more dots and higher density.
 * @param {string} shape The shape of the dots. Can be 'circle' or 'square'.
 * @param {number} variation A value from 0 to 1 that controls the randomness of dot placement and size. 0 means a perfect grid, 1 means maximum randomness.
 * @returns {HTMLCanvasElement} A new canvas element with the pointillism effect applied.
 */
function processImage(originalImg, dotSize = 5, density = 10, shape = 'circle', variation = 0.5) {
    // Create a canvas and get its 2D rendering context
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    const width = originalImg.width;
    const height = originalImg.height;

    // Set canvas dimensions to match the original image
    canvas.width = width;
    canvas.height = height;

    // Draw the original image to the canvas to be able to access its pixel data
    ctx.drawImage(originalImg, 0, 0, width, height);

    // Get the image data from the canvas
    const imageData = ctx.getImageData(0, 0, width, height);
    const data = imageData.data;

    // Clear the canvas with a white background to draw the dots on
    ctx.fillStyle = '#FFFFFF';
    ctx.fillRect(0, 0, width, height);

    // Ensure density is at least 1 to avoid infinite loops
    const gridStep = Math.max(1, density);
    const halfGridStep = gridStep / 2;

    // Iterate over the image in a grid pattern defined by the density
    for (let y = 0; y < height; y += gridStep) {
        for (let x = 0; x < width; x += gridStep) {
            // Determine the coordinates to sample the color from (center of the grid cell)
            const sampleX = Math.min(width - 1, x + Math.floor(halfGridStep));
            const sampleY = Math.min(height - 1, y + Math.floor(halfGridStep));

            // Calculate the index of the pixel in the image data array
            const pixelIndex = (sampleY * width + sampleX) * 4;

            // Extract the RGBA values of the pixel
            const r = data[pixelIndex];
            const g = data[pixelIndex + 1];
            const b = data[pixelIndex + 2];
            const a = data[pixelIndex + 3] / 255;

            // Skip drawing if the sampled area is transparent
            if (a === 0) {
                continue;
            }

            // --- Apply variations ---
            // Randomize the dot's position within its grid cell based on the variation factor
            const offsetX = (Math.random() - 0.5) * gridStep * variation;
            const offsetY = (Math.random() - 0.5) * gridStep * variation;
            const dotX = x + halfGridStep + offsetX;
            const dotY = y + halfGridStep + offsetY;

            // Randomize the dot's size based on the variation factor
            const sizeVariation = (Math.random() - 0.5) * dotSize * variation;
            const currentDotSize = Math.max(1, dotSize + sizeVariation);

            // Set the fill color for the dot
            ctx.fillStyle = `rgba(${r}, ${g}, ${b}, ${a})`;

            // Draw the dot based on the selected shape
            if (shape.toLowerCase() === 'square') {
                ctx.fillRect(dotX - currentDotSize / 2, dotY - currentDotSize / 2, currentDotSize, currentDotSize);
            } else { // Default to 'circle'
                ctx.beginPath();
                ctx.arc(dotX, dotY, currentDotSize / 2, 0, Math.PI * 2);
                ctx.fill();
            }
        }
    }

    // Return the final canvas
    return canvas;
}