Image Elements Combination Tool

/**
 * Combines elements of two images by overlaying a second image onto a primary one,
 * with options for blending, opacity, positioning, and scaling.
 *
 * @param {Image} originalImg The primary javascript Image object (the base layer).
 * @param {string} secondImgSrc The source URL or data URL of the second image to overlay. Defaults to an empty string, in which case only the original image is drawn.
 * @param {string} blendMode The canvas composite operation to use for blending the second image. Common values include 'source-over', 'multiply', 'screen', 'overlay', 'lighten'. Defaults to 'source-over'.
 * @param {number} opacity The opacity of the second image, a value from 0.0 (transparent) to 1.0 (opaque). Defaults to 1.0.
 * @param {number} positionX The horizontal (x-axis) coordinate of the top-left corner of the second image. Defaults to 0.
 * @param {number} positionY The vertical (y-axis) coordinate of the top-left corner of the second image. Defaults to 0.
 * @param {number} scale A multiplier to resize the second image. For example, 0.5 makes it half size, 2.0 makes it double size. Defaults to 1.0.
 * @returns {Promise<HTMLCanvasElement>} A promise that resolves with the canvas element containing the combined images.
 */
async function processImage(originalImg, secondImgSrc = '', blendMode = 'source-over', opacity = 1.0, positionX = 0, positionY = 0, scale = 1.0) {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    // Set canvas size to match the original image
    canvas.width = originalImg.naturalWidth;
    canvas.height = originalImg.naturalHeight;

    // Draw the original image as the base layer
    ctx.drawImage(originalImg, 0, 0);

    // If no second image is provided, return the canvas with just the first image
    if (!secondImgSrc || secondImgSrc.trim() === '') {
        return canvas;
    }

    // Create a promise to handle the asynchronous loading of the second image
    const loadSecondImage = new Promise((resolve, reject) => {
        const secondImg = new Image();
        // Allow loading images from other domains to avoid a tainted canvas
        secondImg.crossOrigin = "Anonymous";
        secondImg.onload = () => resolve(secondImg);
        secondImg.onerror = (err) => reject(new Error(`Failed to load the second image from src: ${secondImgSrc}`));
        secondImg.src = secondImgSrc;
    });

    try {
        const secondImg = await loadSecondImage;

        // Save the current canvas state
        ctx.save();

        // Set the blending mode
        // A list of valid modes to prevent errors from invalid strings
        const validBlendModes = [
            'source-over', 'source-in', 'source-out', 'source-atop',
            'destination-over', 'destination-in', 'destination-out', 'destination-atop',
            'lighter', 'copy', 'xor', 'multiply', 'screen', 'overlay', 'darken',
            'lighten', 'color-dodge', 'color-burn', 'hard-light', 'soft-light',
            'difference', 'exclusion', 'hue', 'saturation', 'color', 'luminosity'
        ];

        if (validBlendModes.includes(blendMode)) {
            ctx.globalCompositeOperation = blendMode;
        } else {
            console.warn(`Invalid blend mode: "${blendMode}". Defaulting to "source-over".`);
            ctx.globalCompositeOperation = 'source-over';
        }


        // Set the opacity, clamping the value between 0 and 1
        ctx.globalAlpha = Math.max(0, Math.min(1, opacity));

        // Calculate the scaled dimensions of the second image
        const scaledWidth = secondImg.naturalWidth * scale;
        const scaledHeight = secondImg.naturalHeight * scale;

        // Draw the second image onto the canvas with the specified transformations
        ctx.drawImage(secondImg, positionX, positionY, scaledWidth, scaledHeight);

        // Restore the canvas state to its original settings
        ctx.restore();

    } catch (error) {
        console.error(error);
        // If the second image fails to load, we can return the canvas with just the original image.
        // The error is logged to the console for debugging.
    }

    return canvas;
}