Image Desert Warm Tone Filter

/**
 * Applies a "Desert Warm Tone" filter to an image.
 * This filter enhances reds and greens, and reduces blues to create a warm, arid feel.
 * The intensity of the effect can be controlled.
 *
 * @param {Image} originalImg The original JavaScript Image object. Assumed to be fully loaded.
 * @param {number} [intensity=0.7] The strength of the filter effect. Recommended range 0.0 (no effect) to 1.0 (full effect).
 *                                  Values outside this range will be clamped to [0,1].
 * @returns {HTMLCanvasElement} A new canvas element with the filter applied.
 */
function processImage(originalImg, intensity = 0.7) {
    const canvas = document.createElement('canvas');
    // Use { willReadFrequently: true } for potential performance optimization if supported by the browser.
    const ctx = canvas.getContext('2d', { willReadFrequently: true });

    // Determine image dimensions. Use naturalWidth/Height if available (intrinsic image size),
    // otherwise fallback to width/height (could be styled dimensions if originalImg is an <img> element).
    // Assumes originalImg is loaded, so dimensions should be positive.
    const imgWidth = originalImg.naturalWidth || originalImg.width;
    const imgHeight = originalImg.naturalHeight || originalImg.height;

    // If image dimensions are zero (e.g., image not loaded or is invalid),
    // set canvas to 0x0 and issue a warning.
    if (imgWidth === 0 || imgHeight === 0) {
        canvas.width = 0;
        canvas.height = 0;
        console.warn("Image Desert Warm Tone Filter: Original image has zero dimensions. Returning empty canvas.");
        return canvas;
    }

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

    // Draw the original image onto the canvas. This is the base for manipulation.
    ctx.drawImage(originalImg, 0, 0, canvas.width, canvas.height);

    // Clamp the intensity parameter to the [0, 1] range for predictable behavior.
    const effectiveIntensity = Math.max(0, Math.min(1, intensity));

    // If effectiveIntensity is 0 after clamping, no processing is needed.
    // Return the canvas, which currently holds the original image.
    if (effectiveIntensity === 0) {
        return canvas;
    }

    try {
        // Get the pixel data from the canvas. This is an ImageData object.
        const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
        const data = imageData.data; // This is a Uint8ClampedArray: [R,G,B,A, R,G,B,A, ...]

        // Define the 'full strength' multipliers that characterize the "Desert Warm Tone".
        // These values are chosen to increase warmth (reds/yellows) and simulate an arid, sun-baked look.
        const targetRedMultiplier = 1.25;   // Boost reds significantly for warmth.
        const targetGreenMultiplier = 1.12; // Boost greens moderately; with red boost, this shifts colors towards yellow/orange.
        const targetBlueMultiplier = 0.85;  // Reduce blues to decrease coolness, enhance overall warmth, and simulate a desaturated sky/shadows.

        // Calculate the actual multipliers to apply based on the effectiveIntensity.
        // This formula performs a linear interpolation between no effect (multiplier = 1) 
        // and the full target effect (multiplier = targetMultiplier).
        // actual_multiplier = 1 * (1 - effectiveIntensity) + target_multiplier * effectiveIntensity
        // This can be rewritten as: actual_multiplier = 1 + (target_multiplier - 1) * effectiveIntensity
        const actualRedMultiplier = 1 + (targetRedMultiplier - 1) * effectiveIntensity;
        const actualGreenMultiplier = 1 + (targetGreenMultiplier - 1) * effectiveIntensity;
        const actualBlueMultiplier = 1 + (targetBlueMultiplier - 1) * effectiveIntensity;

        // Iterate over each pixel in the image data. Each pixel consists of 4 consecutive values (Red, Green, Blue, Alpha).
        for (let i = 0; i < data.length; i += 4) {
            // Apply the calculated multipliers to the Red, Green, and Blue channels.
            // The Alpha channel (data[i+3]) is typically left unchanged for such filters.
            data[i]   = data[i] * actualRedMultiplier;   // Red channel
            data[i+1] = data[i+1] * actualGreenMultiplier; // Green channel
            data[i+2] = data[i+2] * actualBlueMultiplier;  // Blue channel
            
            // Note: When values are assigned to a Uint8ClampedArray (like 'data'),
            // they are automatically clamped to the valid range [0, 255] and
            // rounded to the nearest integer. Thus, explicit Math.min/max/round calls
            // for each channel assignment are not strictly necessary here.
        }

        // Put the modified image data back onto the canvas, replacing the original image.
        ctx.putImageData(imageData, 0, 0);

    } catch (e) {
        // This error can occur if the image being processed is loaded from a different origin
        // without proper CORS (Cross-Origin Resource Sharing) headers. This "taints" the canvas,
        // preventing pixel data extraction via getImageData().
        console.error("Image Desert Warm Tone Filter: Error processing image data. This might be a cross-origin issue.", e);
        // In case of an error, the canvas will still contain the original image
        // (as drawn by ctx.drawImage before this try-catch block), which serves as a safe fallback.
    }

    return canvas;
}