Image Glossy Metallic Effect Converter

/**
 * Converts an image to have a glossy metallic effect while preserving its original colors.
 * The effect is achieved by increasing the image's contrast and saturation, and then applying
 * a semi-transparent gradient overlay to simulate a shiny, reflective surface.
 * This function works well with images that have transparency.
 *
 * @param {HTMLImageElement} originalImg The original image object to process.
 * @returns {HTMLCanvasElement} A new canvas element displaying the image with the effect.
 */
function processImage(originalImg) {
    // 1. Create a canvas element to work on.
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

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

    // 3. Enhance the base image for a more metallic feel.
    // Increasing contrast and saturation makes the colors pop and provides a better
    // base for the lighting effect. This filter is applied to the drawing operation.
    ctx.filter = 'contrast(140%) saturate(120%)';

    // Draw the original image onto the canvas. The filter will be applied automatically.
    ctx.drawImage(originalImg, 0, 0, width, height);

    // It's good practice to reset the filter to 'none' so it doesn't affect
    // any subsequent drawing operations.
    ctx.filter = 'none';

    // 4. Create the glossy sheen gradient.
    // This linear gradient simulates light reflecting off a curved, shiny surface.
    // It consists of semi-transparent white and black stops to create highlights and shadows.
    const gradient = ctx.createLinearGradient(0, 0, 0, height);
    
    // Define the color stops for the gradient.
    gradient.addColorStop(0, 'rgba(255, 255, 255, 0.7)'); // Strong top highlight
    gradient.addColorStop(0.25, 'rgba(255, 255, 255, 0.1)'); // Fading highlight
    gradient.addColorStop(0.5, 'rgba(0, 0, 0, 0.2)');     // Subtle mid-shadow
    gradient.addColorStop(0.75, 'rgba(255, 255, 255, 0.3)'); // Lower reflection
    gradient.addColorStop(1, 'rgba(0, 0, 0, 0.6)');     // Bottom shadow

    // 5. Apply the gradient over the enhanced image using a blend mode.
    // 'soft-light' is an excellent choice as it blends the light and dark areas of the
    // gradient with the image in a non-destructive way, creating a rich, glossy look.
    ctx.globalCompositeOperation = 'soft-light';

    // Fill the entire canvas with the gradient. Due to the blend mode, this will
    // only affect the existing pixels of the drawn image. Transparent areas will remain transparent.
    ctx.fillStyle = gradient;
    ctx.fillRect(0, 0, width, height);

    // 6. Reset the composite operation to its default value.
    ctx.globalCompositeOperation = 'source-over';

    // 7. Return the final canvas, which now holds the glossy metallic image.
    return canvas;
}