Image Faded Filter Application

/**
 * Applies a "faded" filter to an image.
 * The faded effect typically involves reduced contrast, desaturation,
 * and lifted black levels, giving a softer, washed-out appearance.
 *
 * @param {HTMLImageElement} originalImg - The original JavaScript Image object (HTMLImageElement).
 * It's assumed this image is loaded and has valid dimensions.
 * @returns {HTMLCanvasElement} A new canvas element with the faded filter applied.
 */
function processImage(originalImg) {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    // Determine image dimensions. Use naturalWidth/Height for intrinsic dimensions of the image.
    // Fallback to width/height if naturalWidth/Height are not available (e.g., for some image types or states).
    const width = originalImg.naturalWidth || originalImg.width || 0;
    const height = originalImg.naturalHeight || originalImg.height || 0;

    // Handle cases where image dimensions are not valid.
    if (width === 0 || height === 0) {
        console.warn("processImage (Faded Filter): Image has zero dimensions. Source src may be invalid, image not loaded, or not an image element. Returning an empty 1x1 canvas.");
        // Create a minimal 1x1 canvas to prevent errors if further processing expects a canvas.
        canvas.width = 1;
        canvas.height = 1;
        return canvas;
    }

    canvas.width = width;
    canvas.height = height;

    // Store the original filter setting of the context, if any, to restore it later.
    // For a newly created canvas context, this will typically be "none".
    let previousFilterSetting = 'none';
    if (typeof ctx.filter === 'string') {
        previousFilterSetting = ctx.filter;
    }

    // Step 1: Apply base image adjustments using the canvas filter property.
    // This step aims to reduce overall contrast and color vibrancy, common in faded aesthetics.
    const contrastValue = 0.85;   // Reduce contrast (e.g., 85% of original).
    const saturateValue = 0.80;   // Desaturate colors (e.g., 80% of original).
    const brightnessValue = 1.02; // Slightly increase brightness (e.g., 102% of original).

    // Apply the combined filter string if the context supports the filter property.
    if (typeof ctx.filter === 'string') {
        ctx.filter = `contrast(${contrastValue}) saturate(${saturateValue}) brightness(${brightnessValue})`;
    }
    
    // Draw the original image onto the canvas.
    // If ctx.filter was set, it will be applied during this drawing operation.
    ctx.drawImage(originalImg, 0, 0, width, height);
    
    // Restore the original filter setting. This is important if the context is reused.
    if (typeof ctx.filter === 'string') {
        ctx.filter = previousFilterSetting;
    }

    // Step 2: Apply an overlay to achieve the "faded" look (lifted blacks, washed-out effect).
    // This is done by drawing a semi-transparent light gray rectangle over the entire image.
    // The blending formula for 'source-over' (default) with overlay color (C_ov, A_ov) and existing pixel (C_px, A_px=1) is:
    // C_out = C_ov * A_ov + C_px * (1 - A_ov)
    // For example, with overlayAlpha = 0.12 and overlayGrayLevel = 221:
    // NewPixel = 221 * 0.12 + OldPixel * (1 - 0.12)
    // NewPixel = 26.52 + OldPixel * 0.88
    // This calculation:
    // - Lifts black levels (if OldPixel is 0, NewPixel becomes 26.52).
    // - Compresses highlights (if OldPixel is 255, NewPixel becomes 26.52 + 255 * 0.88 = 250.92).
    // - Overall, reduces contrast and gives a washed-out appearance.
    
    const overlayAlpha = 0.12; // Opacity of the overlay (12%).
    const overlayGrayLevel = 221; // A light gray color (hex #DDDDDD).
    const fadeOverlayColor = `rgba(${overlayGrayLevel}, ${overlayGrayLevel}, ${overlayGrayLevel}, ${overlayAlpha})`;

    // Ensure globalCompositeOperation is 'source-over' (which is the default).
    // This blends the fillStyle color with the existing canvas content.
    ctx.globalCompositeOperation = 'source-over';
    ctx.fillStyle = fadeOverlayColor;
    ctx.fillRect(0, 0, width, height);

    return canvas;
}