Image Softly Lit Portrait Generator

/**
 * Creates a softly lit portrait effect on an image, simulating a warm, dreamy,
 * golden-hour look with a natural glow and soft focus.
 *
 * @param {HTMLImageElement} originalImg The original image element.
 * @param {number} [warmth=0.3] A value from 0 to 1 controlling the intensity of the warm, golden-hour tone.
 * @param {number} [glow=0.4] A value from 0 to 1 controlling the intensity of the soft light bloom/glow effect.
 * @param {number} [softness=0.5] A value in pixels for a subtle overall blur to create a dreamy, soft-focus feel.
 * @param {number} [vignette=0.4] A value from 0 to 1 controlling the darkness of the corners to draw focus to the subject.
 * @returns {HTMLCanvasElement} A new canvas element with the softly lit portrait effect applied.
 */
function processImage(originalImg, warmth = 0.3, glow = 0.4, softness = 0.5, vignette = 0.4) {
    // 1. Setup Canvas
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');
    const w = originalImg.naturalWidth;
    const h = originalImg.naturalHeight;
    canvas.width = w;
    canvas.height = h;

    // 2. Initial Adjustments for Warmth, Softness, and Tone
    // We apply a chain of CSS-like filters to the canvas context. This provides an efficient
    // base for our effect. sepia() simulates warmth, saturate() enhances it, and 
    // brightness()/contrast() give it a cinematic pop. The 'softness' parameter applies a subtle blur.
    ctx.filter = `
        sepia(${warmth}) 
        saturate(1.2) 
        contrast(1.05) 
        brightness(1.05)
        blur(${softness}px)
    `;
    ctx.drawImage(originalImg, 0, 0, w, h);
    // Reset the filter so it doesn't affect subsequent drawing operations.
    ctx.filter = 'none';

    // 3. Create the Glow/Bloom Effect
    // This is key to the "softly lit" look. We create a blurred, high-contrast version
    // of the image (a "glow map") and layer it on top using an additive blend mode.
    if (glow > 0) {
        // Create a temporary offscreen canvas for the glow map
        const glowCanvas = document.createElement('canvas');
        glowCanvas.width = w;
        glowCanvas.height = h;
        const glowCtx = glowCanvas.getContext('2d', { willReadFrequently: true });

        // Isolate the highlights and blur them heavily.
        // A larger image needs a larger blur radius for a similar effect.
        const blurRadius = Math.max(w, h) * 0.02 * (glow + 0.5);
        glowCtx.filter = `
            contrast(1.5) 
            brightness(1.2) 
            saturate(1.5)
            blur(${blurRadius}px)
        `;
        
        // Draw the original image to the glow canvas which applies the highlight filter.
        glowCtx.drawImage(originalImg, 0, 0, w, h);
        
        // Composite the glow map back onto the main canvas.
        // 'screen' blend mode adds the light values, creating the glow.
        ctx.globalCompositeOperation = 'screen';
        ctx.globalAlpha = glow; // The 'glow' parameter controls the intensity.
        ctx.drawImage(glowCanvas, 0, 0, w, h);

        // Reset composite operations for the next step.
        ctx.globalCompositeOperation = 'source-over';
        ctx.globalAlpha = 1.0;
    }

    // 4. Apply a Vignette Effect
    // This darkens the corners, which helps to simulate depth of field and
    // draws the viewer's focus to the center of the portrait.
    if (vignette > 0) {
        const centerX = w / 2;
        const centerY = h / 2;
        const outerRadius = Math.sqrt(Math.pow(w / 2, 2) + Math.pow(h / 2, 2));
        
        // Create a radial gradient that is transparent in the center and dark at the edges.
        const gradient = ctx.createRadialGradient(
            centerX, centerY, outerRadius * 0.2, 
            centerX, centerY, outerRadius
        );
        
        gradient.addColorStop(0, 'rgba(0,0,0,0)');
        // A midway stop to control the falloff, making the transition smoother.
        gradient.addColorStop(0.6, 'rgba(0,0,0,0)');
        // The 'vignette' parameter controls how dark the edges get.
        gradient.addColorStop(1, `rgba(0,0,0,${vignette})`);
        
        ctx.fillStyle = gradient;
        ctx.fillRect(0, 0, w, h);
    }
    
    return canvas;
}