Image Low Contrast Filter

/**
 * Applies a low contrast filter to an image.
 *
 * @param {HTMLImageElement} originalImg - The original image element. It's assumed this image is loaded,
 *                                         so that naturalWidth and naturalHeight are available.
 * @param {number|string} [reductionAmount=0.5] - The amount of contrast reduction.
 *        0 means no reduction (original contrast).
 *        1 means full reduction (image becomes gray).
 *        Values outside the [0, 1] range will be clamped.
 *        If a string is provided, it will be converted to a number.
 *        Non-numeric string values (e.g., "abc") will cause the reductionAmount to default to 0.5.
 * @returns {HTMLCanvasElement} A new canvas element with the processed image.
 *                                If the original image has 0 width or height, an empty canvas of 0x0 dimensions is returned.
 */
function processImage(originalImg, reductionAmount = 0.5) {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    let numericReductionAmount = Number(reductionAmount);
    
    // If reductionAmount was not a parsable number (e.g., "abc") or if it was NaN initially.
    // Note: The default parameter `reductionAmount = 0.5` handles the case where it's not provided.
    if (isNaN(numericReductionAmount)) {
        numericReductionAmount = 0.5; // Fallback to default if parsing failed
    }

    // Clamp the numericReductionAmount to the valid range [0, 1].
    // 0 means no reduction (results in original contrast).
    // 1 means full reduction (results in a completely gray image).
    const normalizedReductionAmount = Math.max(0, Math.min(1, numericReductionAmount));

    // Convert the reduction amount to the contrast value understood by the CSS `contrast()` filter.
    // `contrast(1)` or `contrast(100%)` means original image contrast.
    // `contrast(0)` or `contrast(0%)` means a completely gray image (no contrast).
    // So, if reductionAmount is 0, contrastValueForFilter = 1 (original).
    // If reductionAmount is 1, contrastValueForFilter = 0 (gray).
    // If reductionAmount is 0.5, contrastValueForFilter = 0.5 (50% of original contrast).
    const contrastValueForFilter = 1 - normalizedReductionAmount;

    // Set canvas dimensions to the original image's natural dimensions.
    // These properties reflect the intrinsic size of the image.
    if (originalImg.naturalWidth === 0 || originalImg.naturalHeight === 0) {
        // This can happen if the image hasn't loaded, is invalid, or is genuinely a 0-dimension image.
        // Drawing a 0-width/height image can cause errors or be handled inconsistently by browsers.
        // We'll create a 0x0 canvas in this case.
        canvas.width = 0;
        canvas.height = 0;
        // Optionally, log a warning:
        // console.warn("Original image has zero width or height. Resulting canvas will be 0x0.");
    } else {
        canvas.width = originalImg.naturalWidth;
        canvas.height = originalImg.naturalHeight;
    }
    
    // Apply the contrast filter using the CanvasRenderingContext2D.filter property.
    // The value for contrast() function in filter can be a unitless number or a percentage.
    // e.g., `contrast(0.5)` is equivalent to `contrast(50%)`.
    ctx.filter = `contrast(${contrastValueForFilter})`;

    // Draw the image onto the canvas. The filter is applied during this drawing operation.
    // We only attempt to draw if the canvas has positive dimensions.
    if (canvas.width > 0 && canvas.height > 0) {
       ctx.drawImage(originalImg, 0, 0, canvas.width, canvas.height);
    }
    
    // The canvas now contains the low-contrast version of the image.
    // The filter property on the context `ctx` remains set. If this context were to be reused,
    // one might want to reset it via `ctx.filter = 'none';`. However, since a new canvas
    // and context are created each time, and the canvas element itself is returned,
    // this is generally not necessary for this function's purpose.
    
    return canvas;
}