Image Painting Translator

/**
 * Translates an image into a painting-like representation by rendering it
 * with a series of randomized circular brush strokes.
 *
 * @param {Image} originalImg The original Image object to process.
 * @param {number | string} brushSize The average diameter of the brush strokes. Larger values create a more abstract, blocky painting. Default is 10.
 * @param {number | string} randomness A value between 0 and 1 that controls the irregularity of brush strokes in position and size. 0 creates a uniform grid of circles, while 1 creates maximum randomness. Default is 0.5.
 * @returns {HTMLCanvasElement} A new canvas element with the painted version of the image.
 */
function processImage(originalImg, brushSize = 10, randomness = 0.5) {
    // Sanitize parameters to ensure they are valid numbers in the expected range.
    const numBrushSize = Math.max(1, Number(brushSize) || 10);
    const numRandomness = Math.max(0, Math.min(1, Number(randomness) || 0.5));

    const width = originalImg.naturalWidth;
    const height = originalImg.naturalHeight;

    // If the image has no dimensions (e.g., it failed to load), return an empty canvas.
    if (width === 0 || height === 0) {
        const emptyCanvas = document.createElement('canvas');
        emptyCanvas.width = 1;
        emptyCanvas.height = 1;
        return emptyCanvas;
    }

    // Create a temporary, off-screen canvas to get the pixel data from the original image.
    const sourceCanvas = document.createElement('canvas');
    sourceCanvas.width = width;
    sourceCanvas.height = height;
    const sourceCtx = sourceCanvas.getContext('2d', {
        willReadFrequently: true
    });
    sourceCtx.drawImage(originalImg, 0, 0, width, height);

    // Get the raw pixel data as a single flat array of consecutive RGBA values.
    const imageData = sourceCtx.getImageData(0, 0, width, height).data;

    // Create the destination canvas where the final "painted" image will be drawn.
    const destCanvas = document.createElement('canvas');
    destCanvas.width = width;
    destCanvas.height = height;
    const destCtx = destCanvas.getContext('2d');

    // Fill the background solid white. This can be seen between strokes if they don't fully cover.
    destCtx.fillStyle = '#FFFFFF';
    destCtx.fillRect(0, 0, width, height);

    // Determine the step size for iterating over the image grid.
    // A smaller step creates more strokes and detail, but is slower.
    // A step of half the brush size ensures good overlap, creating a more cohesive look.
    const step = Math.floor(Math.max(1, numBrushSize / 2));

    // Iterate over the source image in a grid-like pattern to sample colors.
    for (let y = 0; y < height; y += step) {
        for (let x = 0; x < width; x += step) {
            // Calculate the index for the pixel data array from the (x, y) coordinates.
            // Each pixel consists of 4 values (R, G, B, A).
            const index = (y * width + x) * 4;

            const r = imageData[index];
            const g = imageData[index + 1];
            const b = imageData[index + 2];

            // Introduce randomness to the position and size of the stroke.
            const jitterX = (Math.random() - 0.5) * step * numRandomness;
            const jitterY = (Math.random() - 0.5) * step * numRandomness;
            const sizeJitter = (Math.random() - 0.5) * numBrushSize * numRandomness;

            // Calculate the final radius for this stroke, ensuring it's not zero or negative.
            const currentBrushRadius = Math.max(1, (numBrushSize + sizeJitter) / 2);

            // Set the color for the stroke.
            destCtx.fillStyle = `rgb(${r}, ${g}, ${b})`;

            // Draw the brush stroke as a circle at the calculated position.
            destCtx.beginPath();
            destCtx.arc(x + jitterX, y + jitterY, currentBrushRadius, 0, Math.PI * 2);
            destCtx.fill();
        }
    }

    // Return the completed canvas element.
    return destCanvas;
}