Image Color Overlay Filter

function processImage(originalImg, color = "red", opacity = 0.5) {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    // Use naturalWidth/Height for intrinsic dimensions, fallback to width/height.
    // This is important for ensuring the canvas matches the image's actual size.
    const imgWidth = originalImg.naturalWidth || originalImg.width;
    const imgHeight = originalImg.naturalHeight || originalImg.height;

    // Handle cases where the image might not be loaded yet or is a 0x0 image.
    // A 0x0 canvas is not very useful, and drawing a 0x0 image can cause errors or undesired behavior.
    if (imgWidth === 0 || imgHeight === 0) {
        // Log a warning to aid debugging, as this usually indicates an issue like an unloaded image.
        console.warn("Image provided to processImage has zero width or height. Ensure the image is loaded and valid. Returning a 0x0 canvas.");
        canvas.width = 0;
        canvas.height = 0;
        return canvas;
    }

    // Set canvas dimensions to match the image.
    canvas.width = imgWidth;
    canvas.height = imgHeight;

    // Draw the original image onto the canvas.
    // This image serves as the 'destination' in the compositing operation that follows.
    ctx.drawImage(originalImg, 0, 0, canvas.width, canvas.height);

    // Prepare for drawing the color overlay.
    // Clamp the opacity value to the valid range [0, 1], as context.globalAlpha expects this.
    const actualOpacity = Math.max(0, Math.min(1, opacity));
    
    // Set the fill style for the overlay. The 'color' parameter is a string
    // that can represent any valid CSS color, including those with an alpha
    // component (e.g., "rgba(255,0,0,0.5)" or "#FF000080").
    ctx.fillStyle = color;
    
    // Set the globalAlpha for the context. When new shapes are drawn (like the fillRect below),
    // their color's alpha component (if any, from ctx.fillStyle) is multiplied by this globalAlpha value.
    // For example, if ctx.fillStyle is set to "rgba(0,0,255,0.8)" (blue with 80% alpha)
    // and actualOpacity (derived from the opacity parameter) is 0.5,
    // the effective alpha of the overlay rectangle will be 0.8 * 0.5 = 0.4.
    // If ctx.fillStyle is "blue" (alpha of 1.0), effective alpha will be 1.0 * 0.5 = 0.5.
    ctx.globalAlpha = actualOpacity;

    // Draw the overlay rectangle.
    // The default globalCompositeOperation is 'source-over'. This means the
    // rectangle (source) is drawn over the existing canvas content (destination,
    // which currently is the originalImg). This blending behavior is equivalent to
    // the "Normal" blend mode commonly found in image editing software.
    // If the original image has transparent areas, these areas will also be
    // overlaid with the semi-transparent color, as per standard 'source-over' compositing.
    ctx.fillRect(0, 0, canvas.width, canvas.height);

    // Reset globalAlpha to its default value of 1.0.
    // This is good practice to avoid side effects if the context were to be used
    // for further drawing operations after this function, although not strictly
    // necessary in this specific function as the context is local and the canvas is returned.
    ctx.globalAlpha = 1.0;

    // Return the canvas element. This element contains the image with the color overlay
    // and can be appended to the DOM or used as a source for other image/canvas operations.
    return canvas;
}