Photo Uplifting Filter

/**
 * Applies an "uplifting" filter to an image.
 * This generally involves increasing brightness, contrast, saturation, and adding a warm tint.
 * The filter effect is achieved using the Canvas API's filter property.
 *
 * @param {HTMLImageElement|HTMLCanvasElement|SVGImageElement|HTMLVideoElement} originalImg The source image object. It's assumed this image is loaded and ready for use.
 * @param {number} brightnessLevel Controls the image brightness. 
 *                                 1.0 represents the original brightness. 
 *                                 Values greater than 1.0 increase brightness, less than 1.0 decrease it.
 *                                 Default is 1.15 (for 115% brightness).
 * @param {number} contrastLevel Controls the image contrast. 
 *                               1.0 represents the original contrast. 
 *                               Values greater than 1.0 increase contrast.
 *                               Default is 1.1 (for 110% contrast).
 * @param {number} saturationLevel Controls the image saturation. 
 *                                 1.0 represents the original saturation. 
 *                                 Values greater than 1.0 increase saturation (more vivid colors).
 *                                 0.0 results in a grayscale image.
 *                                 Default is 1.2 (for 120% saturation).
 * @param {number} warmthLevel Controls the image warmth, implemented using a sepia effect. 
 *                             0.0 means no warmth tint (no sepia). 
 *                             1.0 means full sepia. 
 *                             Small values (e.g., 0.05 to 0.2) provide a subtle warm tint.
 *                             Default is 0.08 (for an 8% sepia effect, adding slight warmth).
 * @returns {HTMLCanvasElement} A new canvas element displaying the filtered image.
 */
function processImage(originalImg, brightnessLevel = 1.15, contrastLevel = 1.1, saturationLevel = 1.2, warmthLevel = 0.08) {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    // Determine image dimensions.
    // For HTMLImageElement, naturalWidth/naturalHeight provide intrinsic dimensions once loaded.
    // For other types like HTMLCanvasElement, .width/.height are used.
    const imgWidth = originalImg.naturalWidth || originalImg.width;
    const imgHeight = originalImg.naturalHeight || originalImg.height;

    canvas.width = imgWidth;
    canvas.height = imgHeight;

    // If the image has no valid dimensions (e.g., image not loaded or is an empty image source),
    // log a warning and return an empty canvas of the same (zero) dimensions.
    if (imgWidth === 0 || imgHeight === 0) {
        if (typeof console !== 'undefined' && console.warn) {
            console.warn("processImage: Original image has zero width or height. Check if the image is loaded or valid. Returning an empty canvas.");
        }
        return canvas;
    }
    
    // Construct the filter string using CSS filter functions.
    // The filters are applied in the order they appear in this string.
    const filterString = 
        `brightness(${brightnessLevel}) ` +
        `contrast(${contrastLevel}) ` +
        `saturate(${saturationLevel}) ` +
        `sepia(${warmthLevel})`; // sepia() is used here to provide the "warmth" effect.
    
    ctx.filter = filterString;

    // Draw the original image onto the canvas.
    // The filter set on the context will be applied during this drawing operation.
    try {
        ctx.drawImage(originalImg, 0, 0, imgWidth, imgHeight);
    } catch (e) {
        // Catch potential errors during drawImage (e.g., security errors for cross-origin images).
        if (typeof console !== 'undefined' && console.error) {
            console.error("processImage: Error drawing image to canvas. The returned canvas may be blank or incomplete. Check image source and CORS policies if applicable.", e);
        }
        // Reset the filter to 'none' in case of an error to ensure the context state is clean if it were to be reused.
        // This is less critical here as a new canvas/context is created per call.
        ctx.filter = 'none'; 
        // The canvas, possibly blank or partially drawn, will still be returned.
    }
    
    // Note: It's good practice to reset ctx.filter to 'none' if the context were to be reused for other drawing operations
    // that shouldn't have this filter. However, since this function creates a new canvas and context for each call and
    // returns the canvas, this step is not strictly necessary for the function's own correct operation.
    // Example: ctx.filter = 'none';

    return canvas;
}