HD Image Quality Enhancer

/**
 * Enhances the quality of an image by upscaling, increasing contrast/saturation, and applying a sharpening filter.
 *
 * @param {HTMLImageElement} originalImg The original Image object to process.
 * @param {number} [scaleFactor=2] The factor by which to increase the image dimensions (e.g., 2 means 200% size). Clamped between 1 and 4.
 * @param {number} [sharpness=0.5] The strength of the sharpening effect. A value from 0 (none) to 1 (max).
 * @param {number} [contrast=0.1] The amount to increase contrast. 0 means no change, 1 means +100%. Clamped between 0 and 1.
 * @param {number} [saturation=0.1] The amount to increase color saturation. 0 means no change, 1 means +100%. Clamped between 0 and 1.
 * @returns {HTMLCanvasElement} A new canvas element containing the enhanced image.
 */
function processImage(originalImg, scaleFactor = 2, sharpness = 0.5, contrast = 0.1, saturation = 0.1) {
    // 1. Parameter Validation & Canvas Setup
    // Ensure parameters are numbers and clamp them to reasonable ranges.
    const finalScale = Math.max(1, Math.min(4, Number(scaleFactor) || 2));
    const finalSharpness = Math.max(0, Math.min(1, Number(sharpness) || 0.5));
    const finalContrast = Math.max(0, Math.min(1, Number(contrast) || 0.1));
    const finalSaturation = Math.max(0, Math.min(1, Number(saturation) || 0.1));

    // Use natural dimensions to avoid issues with stylistically resized images.
    const newWidth = originalImg.naturalWidth * finalScale;
    const newHeight = originalImg.naturalHeight * finalScale;

    const canvas = document.createElement('canvas');
    canvas.width = newWidth;
    canvas.height = newHeight;
    const ctx = canvas.getContext('2d');

    // 2. Upscaling and Color Correction Pass
    // Enable high-quality image smoothing for the best upscaling result.
    ctx.imageSmoothingEnabled = true;
    ctx.imageSmoothingQuality = 'high';

    // Build a CSS filter string for contrast and saturation adjustments.
    let filterString = '';
    if (finalContrast > 0) {
        // A value of 1 means no effect. 1 + 0.1 = 110% contrast.
        filterString += `contrast(${1 + finalContrast}) `;
    }
    if (finalSaturation > 0) {
        // A value of 1 means no effect. 1 + 0.1 = 110% saturation.
        filterString += `saturate(${1 + finalSaturation}) `;
    }
    ctx.filter = filterString.trim();

    // Draw the original image onto the canvas, which applies the scaling and filters.
    ctx.drawImage(originalImg, 0, 0, newWidth, newHeight);
    
    // It's important to reset the filter after drawing so it doesn't affect subsequent operations.
    ctx.filter = 'none';

    // 3. Sharpening Pass (using a High-Pass Filter technique)
    if (finalSharpness > 0) {
        // This technique works by overlaying a special "high-pass" layer
        // on top of the original image using a blend mode like 'soft-light'.

        // Create a temporary canvas for the high-pass filter layer.
        const tempCanvas = document.createElement('canvas');
        tempCanvas.width = newWidth;
        tempCanvas.height = newHeight;
        const tempCtx = tempCanvas.getContext('2d');

        // Generate the high-pass layer: a blurred, inverted, grayscale version of the image.
        // The blur amount is tied to the sharpness to control the radius of the effect.
        const blurAmount = 0.5 + finalSharpness; // Blur from 0.5px to 1.5px
        tempCtx.filter = `grayscale(100%) blur(${blurAmount}px) invert(100%)`;
        
        // Draw the already scaled/colored image from the main canvas into the temp canvas
        // to apply the high-pass filter.
        tempCtx.drawImage(canvas, 0, 0);

        // Now, overlay the high-pass filter layer (from tempCanvas) onto the main canvas.
        // The 'soft-light' blend mode increases local contrast, creating a sharpening effect.
        ctx.globalCompositeOperation = 'soft-light';
        // The strength of the sharpening effect is controlled by the layer's opacity.
        ctx.globalAlpha = finalSharpness;
        ctx.drawImage(tempCanvas, 0, 0);

        // Reset the context properties to their default values for good practice.
        ctx.globalCompositeOperation = 'source-over';
        ctx.globalAlpha = 1.0;
    }

    // 4. Return the final processed canvas element.
    return canvas;
}