Image Light Grunge Filter

/**
 * Applies a light grunge filter to an image by blending color adjustments, noise, and a vignette.
 *
 * @param {HTMLImageElement} originalImg The original image element to process.
 * @param {number} [intensity=0.6] A value from 0.0 to 1.0 that controls the strength of the color grading (desaturation and contrast).
 * @param {number} [noise=0.3] A value from 0.0 to 1.0 that controls the amount of grain/noise added to the image.
 * @param {number} [vignette=0.5] A value from 0.0 to 1.0 that controls the strength of the darkened corners.
 * @returns {HTMLCanvasElement} A new canvas element with the light grunge filter applied.
 */
function processImage(originalImg, intensity = 0.6, noise = 0.3, vignette = 0.5) {
    // 1. Clamp parameters to a safe range [0, 1] to ensure predictable results.
    const _intensity = Math.max(0, Math.min(1, intensity));
    const _noise = Math.max(0, Math.min(1, noise));
    const _vignette = Math.max(0, Math.min(1, vignette));

    // 2. Set up the main canvas to the same dimensions as the original image.
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');
    const w = originalImg.naturalWidth || originalImg.width;
    const h = originalImg.naturalHeight || originalImg.height;
    canvas.width = w;
    canvas.height = h;

    // 3. Apply color adjustments using the highly efficient canvas filter property.
    // As intensity increases, the image becomes more desaturated and has higher contrast.
    const saturate = 100 - (_intensity * 40); // At intensity 1.0, saturation is 60%
    const contrast = 100 + (_intensity * 30); // At intensity 1.0, contrast is 130%
    ctx.filter = `saturate(${saturate}%) contrast(${contrast}%) brightness(98%)`;
    
    // 4. Draw the original image onto the canvas, which applies the defined filter.
    ctx.drawImage(originalImg, 0, 0, w, h);

    // 5. Reset the filter to 'none' so it doesn't affect subsequent drawing operations (like noise and vignette).
    ctx.filter = 'none';

    // 6. Add a procedural noise/grain layer if the noise parameter is greater than zero.
    if (_noise > 0) {
        // Create a noise pattern on a temporary offscreen canvas for better performance.
        const noiseCanvas = document.createElement('canvas');
        noiseCanvas.width = w;
        noiseCanvas.height = h;
        const noiseCtx = noiseCanvas.getContext('2d');
        
        const noiseImageData = noiseCtx.createImageData(w, h);
        const noiseData = noiseImageData.data;

        // Fill the texture with grayscale noise. Values are centered around 128
        // because it's a neutral gray for 'soft-light' and 'overlay' blend modes.
        for (let i = 0; i < noiseData.length; i += 4) {
            const value = 128 + (Math.random() - 0.5) * 80;
            noiseData[i] = value;
            noiseData[i+1] = value;
            noiseData[i+2] = value;
            noiseData[i+3] = 255; // Full alpha for the noise pixels.
        }
        noiseCtx.putImageData(noiseImageData, 0, 0);

        // Blend the generated noise layer onto the main canvas.
        ctx.globalAlpha = _noise * 0.3; // Control the visibility of the noise.
        ctx.globalCompositeOperation = 'soft-light'; // Use a gentle blend mode suitable for texture.
        ctx.drawImage(noiseCanvas, 0, 0);

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

    // 7. Add a vignette (darkened corners) if the vignette parameter is greater than zero.
    if (_vignette > 0) {
        const centerX = w / 2;
        const centerY = h / 2;
        const outerRadius = Math.sqrt(centerX * centerX + centerY * centerY);
        // The transparent inner area shrinks as the vignette strength increases.
        const innerRadius = outerRadius * (1 - _vignette);

        // Create a radial gradient from a transparent center to dark edges.
        const gradient = ctx.createRadialGradient(centerX, centerY, innerRadius, centerX, centerY, outerRadius);
        
        gradient.addColorStop(0, 'rgba(0,0,0,0)'); // Inner part is fully transparent.
        gradient.addColorStop(1, `rgba(0,0,0,${_vignette * 0.7})`); // Edges are dark, controlled by vignette strength.

        // Draw the gradient over the entire image.
        ctx.fillStyle = gradient;
        ctx.fillRect(0, 0, w, h);
    }

    // 8. Return the final modified canvas element.
    return canvas;
}