Image Radial Graduated Filter Effect Tool

/**
 * Applies a radial graduated filter effect to an image.
 * The effect adjusts exposure in a radial pattern, similar to a photographic lens filter.
 *
 * @param {Image} originalImg - The original JavaScript Image object (must be loaded).
 * @param {number} [centerX=0.5] - The horizontal center of the radial effect (0-1, percentage of image width).
 * @param {number} [centerY=0.5] - The vertical center of the radial effect (0-1, percentage of image height).
 * @param {number} [outerRadius=0.7] - The outer radius of the effect gradient (0-1, percentage of image diagonal).
 *                                     Beyond this radius, the effect is at its determined strength based on 'invert'.
 * @param {number} [innerRadius=0.3] - The inner radius of the effect gradient (0-1, percentage of image diagonal).
 *                                     Within this radius, the effect is at its determined strength based on 'invert'.
 *                                     The transition (feathering) occurs between innerRadius and outerRadius.
 * @param {number} [strength=-0.5] - The strength of the exposure adjustment.
 *                                   Positive values brighten, negative values darken. E.g., 1 is +1 EV stop, -1 is -1 EV stop.
 * @param {number} [invert=0] - If 0 (default), the area from center to innerRadius is least affected,
 *                              and the effect increases towards outerRadius (typical for vignette: darkening/lightening edges).
 *                              If 1, the area from center to innerRadius is most affected,
 *                              and the effect decreases towards outerRadius (typical for spotlight: highlighting/dimming center).
 * @returns {HTMLCanvasElement} A new canvas element with the radial graduated filter effect applied.
 */
function processImage(originalImg, centerX = 0.5, centerY = 0.5, outerRadius = 0.7, innerRadius = 0.3, strength = -0.5, invert = 0) {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    const w = originalImg.width;
    const h = originalImg.height;
    canvas.width = w;
    canvas.height = h;

    ctx.drawImage(originalImg, 0, 0, w, h);

    // Optimization: if strength is 0, no visible change will occur.
    if (strength === 0) {
        return canvas;
    }

    const imageData = ctx.getImageData(0, 0, w, h);
    const data = imageData.data;

    // Calculate effect center coordinates in pixels
    const actualCX_px = centerX * w;
    const actualCY_px = centerY * h;

    // Calculate radii in pixels based on image diagonal
    // Using image diagonal helps maintain effect appearance across different aspect ratios.
    const imgDiagonal = Math.hypot(w, h);
    let actualOuterR_px = outerRadius * imgDiagonal;
    let actualInnerR_px = innerRadius * imgDiagonal;

    // Ensure innerRadius_px <= outerRadius_px. If not, swap them.
    // This guarantees that falloffWidth_px is non-negative.
    if (actualInnerR_px > actualOuterR_px) {
        [actualInnerR_px, actualOuterR_px] = [actualOuterR_px, actualInnerR_px];
    }

    const falloffWidth_px = actualOuterR_px - actualInnerR_px;

    for (let i = 0; i < data.length; i += 4) {
        // Calculate current pixel's coordinates
        const currentX = (i / 4) % w;
        const currentY = Math.floor((i / 4) / w);

        // Calculate distance from the effect center to the current pixel
        const distFromCenter = Math.hypot(currentX - actualCX_px, currentY - actualCY_px);

        let effectIntensity; // This will be the factor [0,1] by which 'strength' is applied lograrithmically

        if (falloffWidth_px < 1e-6) { // Case 1: Radii are effectively equal (sharp circular edge)
            if (distFromCenter <= actualInnerR_px) { // Pixel is inside or on the boundary circle
                effectIntensity = (invert === 0) ? 0 : 1; // invert=0: no effect inside. invert=1: full effect inside.
            } else { // Pixel is outside the circle
                effectIntensity = (invert === 0) ? 1 : 0; // invert=0: full effect outside. invert=1: no effect outside.
            }
        } else { // Case 2: Normal falloff/feathering between inner and outer radii
            let gradientFactor; // Raw gradient [0,1]: 0 at innerRadius, 1 at outerRadius

            if (distFromCenter <= actualInnerR_px) {
                gradientFactor = 0; // Pixel is inside inner radius
            } else if (distFromCenter >= actualOuterR_px) {
                gradientFactor = 1; // Pixel is outside outer radius
            } else {
                // Pixel is in the transition zone (feathering area)
                gradientFactor = (distFromCenter - actualInnerR_px) / falloffWidth_px;
                // Apply smoothstep for a more aesthetically pleasing curve (S-curve)
                gradientFactor = gradientFactor * gradientFactor * (3 - 2 * gradientFactor);
            }

            // Adjust gradientFactor based on the 'invert' parameter
            effectIntensity = (invert === 0) ? gradientFactor : (1 - gradientFactor);
        }

        // Apply the exposure effect if the intensity factor indicates a change is needed
        if (effectIntensity > 1e-6) { // Check against a small epsilon to handle floating point noise and avoid Math.pow(2,0)
            const exposureMultiplier = Math.pow(2, strength * effectIntensity);
            data[i]     = Math.max(0, Math.min(255, data[i]     * exposureMultiplier)); // Red
            data[i + 1] = Math.max(0, Math.min(255, data[i + 1] * exposureMultiplier)); // Green
            data[i + 2] = Math.max(0, Math.min(255, data[i + 2] * exposureMultiplier)); // Blue
            // Alpha channel (data[i+3]) remains unchanged
        }
    }

    ctx.putImageData(imageData, 0, 0);
    return canvas;
}