Image Rangoli Design Filter Effect Tool

/**
 * Applies a Rangoli-style (kaleidoscopic) filter effect to an image.
 *
 * @param {HTMLImageElement} originalImg The source image object. Assumed to be loaded.
 * @param {number} [numSlices=12] The number of symmetrical slices to create in the kaleidoscope.
 * @param {number} [sourceOffsetX=0] Horizontal offset from the image's center to pick the source pattern, in pixels.
 * @param {number} [sourceOffsetY=0] Vertical offset from the image's center to pick the source pattern, in pixels.
 * @param {number} [zoom=1.0] Zoom factor for the source pattern. >1 zooms in, <1 zooms out.
 * @returns {HTMLCanvasElement} A new canvas element with the Rangoli effect applied.
 */
function processImage(originalImg, numSlices = 12, sourceOffsetX = 0, sourceOffsetY = 0, zoom = 1.0) {
    // Parameter validation/sanitization
    numSlices = Math.max(1, Math.floor(numSlices)); // Ensure numSlices is at least 1
    zoom = Math.max(0.01, zoom); // Prevent zoom from being zero, negative, or excessively small

    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    // Determine image dimensions.
    // Prioritize naturalWidth/Height for HTMLImageElement, fallback to width/height for other types (e.g., HTMLCanvasElement).
    const imgWidth = originalImg.naturalWidth || originalImg.width || 0;
    const imgHeight = originalImg.naturalHeight || originalImg.height || 0;

    // If image dimensions are zero (e.g., image not loaded or invalid), return a minimal canvas.
    if (imgWidth === 0 || imgHeight === 0) {
        console.error("Image has zero dimensions. It might not be loaded or is an invalid image source.");
        canvas.width = 1; // Canvas dimensions cannot be 0.
        canvas.height = 1;
        // Optionally, fill with a color to indicate error, e.g. ctx.fillStyle = 'red'; ctx.fillRect(0,0,1,1);
        return canvas;
    }

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

    const canvasCenterX = canvas.width / 2;
    const canvasCenterY = canvas.height / 2;

    // Calculate the angle for each slice of the kaleidoscope.
    const sliceAngle = (2 * Math.PI) / numSlices;

    // Calculate the radius for the clipping path of each slice.
    // This radius must be large enough to ensure the wedge covers from the kaleidoscope's center
    // to any corner of the canvas. Math.hypot(dx, dy) calculates sqrt(dx^2 + dy^2).
    const R_clip = Math.hypot(canvasCenterX, canvasCenterY) + 1; // Add 1 pixel as a small safety margin.

    // Determine the focus point in the original image's coordinate system.
    // This point from the original image will be mapped to the center of the kaleidoscope.
    const focusX_in_original_img = imgWidth / 2 + sourceOffsetX;
    const focusY_in_original_img = imgHeight / 2 + sourceOffsetY;

    // Calculate the effective dimensions of the source image after applying the zoom factor.
    const imgEffectiveWidth = imgWidth * zoom;
    const imgEffectiveHeight = imgHeight * zoom;

    // Calculate the drawing position (top-left corner, dx, dy) for the source image.
    // The image needs to be drawn such that its (scaled) focus point 
    // (i.e., focusX_in_original_img * zoom, focusY_in_original_img * zoom)
    // aligns with the (0,0) point of the current transformed canvas space (which is the center of the kaleidoscope effect).
    // Therefore, the top-left corner of the (scaled) image is placed at (-focusX_scaled, -focusY_scaled).
    const imgDrawX = -focusX_in_original_img * zoom;
    const imgDrawY = -focusY_in_original_img * zoom;

    // Loop through each slice to construct the kaleidoscope pattern.
    for (let i = 0; i < numSlices; i++) {
        ctx.save(); // Save the current canvas state (transformations, clipping region, etc.).
        
        // Translate the canvas origin to the center of the canvas,
        // which will be the apex of the current slice and the center of the kaleidoscope.
        ctx.translate(canvasCenterX, canvasCenterY);
        
        // Rotate the coordinate system to align with the centerline of the current slice.
        // Each slice is rotated by `sliceAngle` relative to the previous one.
        ctx.rotate(i * sliceAngle);

        // For odd-numbered slices (i=1, 3, 5,...), reflect the coordinate system.
        // This creates the characteristic mirrored symmetry of a kaleidoscope.
        // The reflection is across the current X-axis (which is the centerline of the slice after rotation).
        if (i % 2 !== 0) { 
            ctx.scale(1, -1); // Flips the Y-axis.
        }

        // Define a pie-wedge shaped clipping path for the current slice.
        // The wedge is centered on the current X-axis, extending from -sliceAngle/2 to +sliceAngle/2.
        ctx.beginPath();
        ctx.moveTo(0, 0); // The apex of the wedge is at the current origin (0,0).
        // The arc forms the curved outer edge of the wedge.
        // `false` for anticlockwise argument: angle from -sliceAngle/2 to +sliceAngle/2.
        ctx.arc(0, 0, R_clip, -sliceAngle / 2, sliceAngle / 2, false); 
        ctx.closePath(); // Connects the arc ends back to (0,0), completing the wedge shape.
        ctx.clip(); // Restrict all subsequent drawing operations to within this wedge.

        // Draw the source image. It is scaled by `zoom` and positioned using `imgDrawX`, `imgDrawY`.
        // This drawing is subject to the sequence of transformations (translate, rotate, scale)
        // and the clipping path already applied to the context.
        ctx.drawImage(
            originalImg,
            imgDrawX,
            imgDrawY,
            imgEffectiveWidth,
            imgEffectiveHeight
        );

        ctx.restore(); // Restore the canvas state to how it was before this slice was drawn.
    }

    return canvas;
}