Image Portrait Generator With Warm Golden Hour Lighting

/**
 * Processes an image to simulate a warm, golden hour lighting effect, creating a
 * softly lit portrait style with a cinematic and dreamy feel.
 * The effect adds a warm tint, enhances glow, softens shadows, and applies a subtle vignette.
 *
 * @param {HTMLImageElement} originalImg The original image object to process.
 * @param {number} intensity A numeric value from 0 (no effect) to 1 (full effect) controlling the strength of the warm/glow effect. Defaults to 0.4.
 * @param {number} vignetteStrength A numeric value from 0 (no vignette) to 1 (strong vignette) controlling the darkness of the corners. Defaults to 0.5.
 * @returns {HTMLCanvasElement} A canvas element displaying the processed image.
 */
function processImage(originalImg, intensity = 0.4, vignetteStrength = 0.5) {
    // Create a new canvas element to draw the processed image on.
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    // Ensure the canvas has the same dimensions as the original image.
    const w = originalImg.naturalWidth;
    const h = originalImg.naturalHeight;
    canvas.width = w;
    canvas.height = h;
    
    // Fallback for environments where canvas context might not be available.
    if (!ctx) {
        console.error("Canvas 2D context is not supported.");
        // As a fallback, draw original image and return.
        const fallbackCanvas = document.createElement('canvas');
        fallbackCanvas.width = w;
        fallbackCanvas.height = h;
        fallbackCanvas.getContext('2d').drawImage(originalImg, 0, 0, w, h);
        return fallbackCanvas;
    }

    // Clamp the input parameters to the valid range of [0, 1].
    const clampedIntensity = Math.max(0, Math.min(1, intensity));
    const clampedVignette = Math.max(0, Math.min(1, vignetteStrength));

    // Clear the canvas to ensure a clean slate.
    ctx.clearRect(0, 0, w, h);

    // Apply a chain of filters to the canvas context. These filters will affect
    // any subsequent drawing operations.
    // - sepia: Adds a warm, yellowish-brown tint, foundational for the golden hour look.
    // - saturate: Boosts the color vibrancy, making the warm tones pop.
    // - contrast: Slightly reduced to create softer shadows and a more dreamy feel.
    // - brightness: Slightly increased to simulate a natural glow from the light source.
    const filterString = [
        `sepia(${clampedIntensity * 0.5})`,
        `saturate(${1 + clampedIntensity * 0.4})`,
        `contrast(${1 - clampedIntensity * 0.2})`,
        `brightness(${1 + clampedIntensity * 0.1})`
    ].join(' ');

    ctx.filter = filterString;

    // Draw the original image onto the canvas. The filters will be applied automatically.
    ctx.drawImage(originalImg, 0, 0, w, h);

    // Reset the filter to 'none' so that the subsequent vignette drawing is not affected.
    ctx.filter = 'none';

    // If vignette strength is greater than zero, draw the vignette effect.
    if (clampedVignette > 0) {
        const centerX = w / 2;
        const centerY = h / 2;
        // Calculate the outer radius to ensure the gradient covers the entire canvas, including corners.
        const outerRadius = Math.sqrt(centerX * centerX + centerY * centerY);

        // Create a radial gradient that is transparent in the center and dark at the edges.
        const gradient = ctx.createRadialGradient(centerX, centerY, 0, centerX, centerY, outerRadius);

        // The gradient starts transparently to keep the center of the image clear.
        // It transitions to a warm, dark brown at the edges instead of pure black for a more natural feel.
        gradient.addColorStop(0.3, 'rgba(40, 20, 0, 0)');
        gradient.addColorStop(1, `rgba(40, 20, 0, ${clampedVignette * 0.9})`);

        // Use 'soft-light' blending mode for a more subtle and natural integration of the vignette.
        ctx.globalCompositeOperation = 'soft-light';
        ctx.fillStyle = gradient;
        ctx.fillRect(0, 0, w, h);

        // Reset the composite operation back to the default for any future drawing.
        ctx.globalCompositeOperation = 'source-over';
    }

    // Return the final canvas element with the "golden hour" portrait effect.
    return canvas;
}