Image Airbrush Effect Creator

/**
 * Applies an airbrush effect to an image.
 * This function simulates an airbrush by scattering semi-transparent dots of color
 * sampled from the original image onto a new canvas.
 *
 * @param {Image} originalImg The original image object to process.
 * @param {string|number} brushSize The radius of the airbrush spray area. Defaults to 10.
 * @param {string|number} density The number of paint particles to spray for each sample point. Higher values create a denser look. Defaults to 25.
 * @returns {HTMLCanvasElement} A new canvas element displaying the airbrushed image.
 */
function processImage(originalImg, brushSize = 10, density = 25) {
    // Coerce parameters to numbers for calculations
    const numBrushSize = Number(brushSize);
    const numDensity = Number(density);

    // Get image dimensions
    const width = originalImg.naturalWidth;
    const height = originalImg.naturalHeight;

    // Create a destination canvas to draw the final result
    const canvas = document.createElement('canvas');
    canvas.width = width;
    canvas.height = height;
    const ctx = canvas.getContext('2d');

    // It's good practice to fill the background, especially for images with transparency
    ctx.fillStyle = 'white';
    ctx.fillRect(0, 0, width, height);

    // To efficiently sample colors, draw the original image onto a temporary hidden canvas
    const sourceCanvas = document.createElement('canvas');
    sourceCanvas.width = width;
    sourceCanvas.height = height;
    const sourceCtx = sourceCanvas.getContext('2d');
    sourceCtx.drawImage(originalImg, 0, 0);

    // Get the pixel data from the source image once for performance
    const sourceImageData = sourceCtx.getImageData(0, 0, width, height);
    const data = sourceImageData.data;

    // Define a step size for iterating over the image. This is a performance optimization.
    // A smaller step creates a higher quality result but is slower.
    const step = Math.max(1, Math.floor(numBrushSize / 3));

    // Iterate over the canvas in a grid defined by the step size
    for (let y = 0; y < height; y += step) {
        for (let x = 0; x < width; x += step) {
            // Sample the color from the center of the current grid cell
            const centerX = Math.min(width - 1, x + step / 2);
            const centerY = Math.min(height - 1, y + step / 2);
            const index = (Math.floor(centerY) * width + Math.floor(centerX)) * 4;

            const r = data[index];
            const g = data[index + 1];
            const b = data[index + 2];
            const a = data[index + 3];

            // If the sampled pixel is fully transparent, skip spraying
            if (a === 0) {
                continue;
            }

            // Set the fill style for the paint particles. A low alpha allows colors to
            // build up and blend, mimicking a real airbrush.
            ctx.fillStyle = `rgba(${r}, ${g}, ${b}, 0.08)`;

            // Spray a number of particles (defined by density) around the center point
            for (let i = 0; i < numDensity; i++) {
                // Generate a random spray point within a circle.
                // Using Math.sqrt(Math.random()) creates a uniform distribution of points
                // across the circular area of the brush, resulting in a natural falloff.
                const radius = numBrushSize * Math.sqrt(Math.random());
                const angle = Math.random() * 2 * Math.PI;

                const sprayX = centerX + radius * Math.cos(angle);
                const sprayY = centerY + radius * Math.sin(angle);

                // Draw a single 1x1 pixel particle.
                ctx.fillRect(sprayX, sprayY, 1, 1);
            }
        }
    }

    return canvas;
}