Image Mystery Of The Purple Spot

/**
 * Creates a "Mystery of the Purple Spot" effect on an image.
 * This function overlays a semi-transparent tint on the image,
 * leaving a clear, circular "spotlight" area, revealing the original image underneath.
 *
 * @param {HTMLImageElement} originalImg The original image object to process.
 * @param {number} [centerX=0.5] The horizontal center of the clear spot, as a fraction of the image width (e.g., 0.5 is the middle).
 * @param {number} [centerY=0.5] The vertical center of the clear spot, as a fraction of the image height.
 * @param {number} [radius=0.25] The radius of the clear spot, as a fraction of the image's smaller dimension.
 * @param {string} [tintColor='purple'] The CSS color string for the overlay tint.
 * @param {number} [tintOpacity=0.75] The opacity of the overlay tint (0.0 to 1.0).
 * @returns {HTMLCanvasElement} A new canvas element with the effect applied.
 */
function processImage(originalImg, centerX = 0.5, centerY = 0.5, radius = 0.25, tintColor = 'purple', tintOpacity = 0.75) {
    // Create a new canvas element to draw on
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    // Get the natural dimensions of the source image
    const width = originalImg.naturalWidth;
    const height = originalImg.naturalHeight;

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

    // Sanitize and convert relative parameters to absolute pixel values
    const safeCenterX = Math.max(0, Math.min(1, Number(centerX))) * width;
    const safeCenterY = Math.max(0, Math.min(1, Number(centerY))) * height;
    const safeRadius = Math.max(0, Number(radius)) * Math.min(width, height);
    const safeOpacity = Math.max(0, Math.min(1, Number(tintOpacity)));

    // 1. Draw the original image onto the canvas
    ctx.drawImage(originalImg, 0, 0, width, height);

    // 2. Prepare to draw the tinted overlay
    ctx.fillStyle = tintColor;
    ctx.globalAlpha = safeOpacity;

    // 3. Create a path that covers the entire image *except* for the circular spot
    ctx.beginPath();

    // First, define the outer rectangle covering the whole canvas
    ctx.rect(0, 0, width, height);

    // Next, define the circular "hole". The `true` for counter-clockwise is important
    // for the 'evenodd' fill rule to correctly identify the hole.
    ctx.arc(safeCenterX, safeCenterY, safeRadius, 0, Math.PI * 2, true);

    // 4. Fill the complex path. The 'evenodd' rule ensures that only the area
    // between the outer rectangle and the inner circle is filled, creating the effect.
    ctx.fill('evenodd');

    // Reset globalAlpha to its default value to avoid affecting subsequent draws
    ctx.globalAlpha = 1.0;

    // 5. Return the canvas with the applied effect
    return canvas;
}