Image Galaxy Convergence Converter

/**
 * Overlays a procedurally generated galaxy/starfield pattern onto an existing image.
 *
 * @param {Image} originalImg The original javascript Image object.
 * @param {number} [starCount=2000] The number of stars to generate.
 * @param {number} [nebulaCount=10] The number of nebula gas clouds to generate.
 * @param {string} [blendMode='lighter'] The canvas globalCompositeOperation to use for blending. 'lighter', 'screen', and 'color-dodge' often produce visually appealing results.
 * @returns {HTMLCanvasElement} A new canvas element with the galaxy effect applied.
 */
function processImage(originalImg, starCount = 2000, nebulaCount = 10, blendMode = 'lighter') {
    // Create a new canvas element
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    // Set canvas dimensions to match the original image
    canvas.width = originalImg.naturalWidth;
    canvas.height = originalImg.naturalHeight;
    const w = canvas.width;
    const h = canvas.height;

    // 1. Draw the original image onto the canvas. This will be the base layer.
    ctx.drawImage(originalImg, 0, 0, w, h);

    // 2. Set the blend mode for the subsequent drawing operations.
    // We validate the blendMode against a list of valid options to prevent errors.
    const validModes = [
        '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 (validModes.includes(blendMode)) {
        ctx.globalCompositeOperation = blendMode;
    } else {
        ctx.globalCompositeOperation = 'lighter'; // Default to a safe, cool-looking option
    }

    // Helper function to generate a random number within a range
    const random = (min, max) => Math.random() * (max - min) + min;

    // 3. Generate and draw nebulae (cosmic gas clouds)
    for (let i = 0; i < nebulaCount; i++) {
        // Position the nebula randomly on the canvas
        const x = random(-w * 0.2, w * 1.2);
        const y = random(-h * 0.2, h * 1.2);
        const radius = random(w * 0.2, w * 0.7);

        // Create a radial gradient for a soft, cloudy effect
        const gradient = ctx.createRadialGradient(x, y, 0, x, y, radius);

        // Use random HSL colors for a cosmic look (blues, purples, pinks)
        const hue = random(200, 300);
        const saturation = random(50, 100);
        const lightness = random(40, 60);
        const alpha = random(0.1, 0.45); // Make them translucent

        // The center of the nebula is brighter
        gradient.addColorStop(0, `hsla(${hue}, ${saturation}%, ${lightness}%, ${alpha})`);
        // The outer edge fades to complete transparency
        gradient.addColorStop(1, `hsla(${hue}, ${saturation}%, ${lightness}%, 0)`);

        ctx.fillStyle = gradient;
        ctx.beginPath();
        ctx.arc(x, y, radius, 0, Math.PI * 2);
        ctx.fill();
    }

    // 4. Generate and draw stars
    ctx.fillStyle = `rgba(255, 255, 255, 1)`; // Stars will be white
    for (let i = 0; i < starCount; i++) {
        const x = random(0, w);
        const y = random(0, h);
        const radius = random(0.5, 2.5);
        const alpha = random(0.4, 1);

        ctx.globalAlpha = alpha; // Set individual star brightness
        ctx.beginPath();
        ctx.arc(x, y, radius, 0, Math.PI * 2);
        ctx.fill();
    }

    // 5. Reset global settings to their defaults for good practice
    ctx.globalAlpha = 1.0;
    ctx.globalCompositeOperation = 'source-over';

    // The canvas now contains the converged image and is ready to be returned
    return canvas;
}