Image Crushed Black Matte Filter Application

function processImage(
    originalImg,
    crushLevel = 0.7,     // Range: 0 (no crush) to 1 (max crush). Defines how dark the crushed blacks become.
    crushThreshold = 60,  // Range: 0-255. Pixels with component values below this are subject to crushing.
    matteLevel = 0.15,    // Range: 0 (no matte) to 1 (strong matte). Defines black lift and white compression.
    desaturationLevel = 0.1 // Range: 0 (no desaturation) to 1 (full desaturation/grayscale).
) {
    const canvas = document.createElement('canvas');
    // Using { willReadFrequently: true } can be an optimization hint for browsers
    // if this operation is performed often on the same context.
    const ctx = canvas.getContext('2d', { willReadFrequently: true });

    // Ensure originalImg has dimensions. naturalWidth/Height for HTMLImageElement, width/height for others (e.g., canvas).
    canvas.width = originalImg.naturalWidth || originalImg.width;
    canvas.height = originalImg.naturalHeight || originalImg.height;

    // Draw the original image onto the canvas
    ctx.drawImage(originalImg, 0, 0, canvas.width, canvas.height);

    // Get pixel data from the canvas
    const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
    const data = imageData.data; // This is a Uint8ClampedArray

    // --- Parameter validation and pre-calculation ---

    // Crush parameters
    crushLevel = Math.max(0, Math.min(1, crushLevel)); // Clamp between 0 and 1
    // actualCrushFactor: 1 means no change, 0 means crushed to black.
    // So, if crushLevel is high (e.g., 0.7), factor is low (0.3), meaning strong crushing.
    const actualCrushFactor = 1.0 - crushLevel;
    crushThreshold = Math.max(0, Math.min(255, crushThreshold)); // Clamp between 0 and 255

    // Matte parameters
    matteLevel = Math.max(0, Math.min(1, matteLevel)); // Clamp between 0 and 1
    const tonalAdjustmentAmount = matteLevel * 35; // Max lift/compression of 35 for r,g,b values
    
    const blackPoint = tonalAdjustmentAmount; // Blacks will be lifted to this minimum value
    const whitePoint = 255 - tonalAdjustmentAmount; // Whites will be compressed to this maximum value
    
    // Dynamic range for the matte effect. Ensure it's at least 1 to avoid division by zero or negative ranges.
    const dynamicRange = Math.max(1, whitePoint - blackPoint);

    // Desaturation parameters
    desaturationLevel = Math.max(0, Math.min(1, desaturationLevel)); // Clamp between 0 and 1
    // actualSaturationFactor: 1 means full original saturation, 0 means grayscale.
    // So, if desaturationLevel is high (e.g., 0.8), factor is low (0.2), meaning strong desaturation.
    const actualSaturationFactor = 1.0 - desaturationLevel;

    // --- Pixel manipulation loop ---
    for (let i = 0; i < data.length; i += 4) {
        let r = data[i];
        let g = data[i+1];
        let b = data[i+2];
        // Alpha (data[i+3]) is not modified

        // Step 1: Crush Blacks
        // If a color component is below the threshold, multiply it by the crush factor to make it darker.
        if (r < crushThreshold) r *= actualCrushFactor;
        if (g < crushThreshold) g *= actualCrushFactor;
        if (b < crushThreshold) b *= actualCrushFactor;
        
        // Step 2: Apply Matte Effect (Tonal Remapping)
        // This maps the current 0-255 range (after potential crushing) to a new [blackPoint, whitePoint] range.
        // Formula: newValue = newMin + (oldValue / oldMax) * (newMax - newMin)
        r = blackPoint + (r / 255) * dynamicRange;
        g = blackPoint + (g / 255) * dynamicRange;
        b = blackPoint + (b / 255) * dynamicRange;

        // Step 3: Apply Desaturation (if desaturationLevel > 0)
        if (desaturationLevel > 0) {
            // Standard luminance calculation for grayscale value
            const gray = 0.299 * r + 0.587 * g + 0.114 * b;
            // Interpolate between the color and its grayscale equivalent
            r = gray + actualSaturationFactor * (r - gray);
            g = gray + actualSaturationFactor * (g - gray);
            b = gray + actualSaturationFactor * (b - gray);
        }

        // Ensure values are clamped to 0-255 and rounded to integers
        data[i]   = Math.max(0, Math.min(255, Math.round(r)));
        data[i+1] = Math.max(0, Math.min(255, Math.round(g)));
        data[i+2] = Math.max(0, Math.min(255, Math.round(b)));
    }

    // Put the modified pixel data back onto the canvas
    ctx.putImageData(imageData, 0, 0);

    return canvas;
}