Image Urban Street Filter

/**
 * Applies an Urban Street filter to an image.
 * This filter typically involves increased contrast, desaturation, a cool color tint,
 * slight darkening, and optional grain.
 *
 * @param {HTMLImageElement} originalImg The original image element. Must be loaded.
 * @param {number} contrastValue Controls the contrast. 1.0 is no change. Typical range: 0.5 (less) to 2.0 (more). Default: 1.3.
 * @param {number} desaturationAmount Controls desaturation. 0.0 is original color, 1.0 is grayscale. Default: 0.6.
 * @param {number} coolStrength Strength of the cool (blue/cyan) tint. Affects blue and red channels. Default: 20.
 * @param {number} brightnessAdjust Adjusts overall brightness. Negative values darken, positive values lighten. Default: -15.
 * @param {number} grainAmount Amount of monochrome noise to add for a grainy effect. 0 for no grain. Default: 5.
 * @returns {HTMLCanvasElement} A new canvas element with the filtered image.
 */
function processImage(originalImg, contrastValue = 1.3, desaturationAmount = 0.6, coolStrength = 20, brightnessAdjust = -15, grainAmount = 5) {
    const canvas = document.createElement('canvas');
    // Using { willReadFrequently: true } can be an optimization hint for browsers
    // when using getImageData frequently, though support and effect vary.
    const ctx = canvas.getContext('2d', { willReadFrequently: true });

    // Ensure using natural dimensions of the image for the 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 the pixel data from the canvas
    // Note: This can be slow for very large images, but is standard for pixel manipulation.
    const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
    const data = imageData.data; // data is a Uint8ClampedArray: [r,g,b,a, r,g,b,a, ...]

    // Helper function to clamp values to the 0-255 range
    function clamp(value, min = 0, max = 255) {
        return Math.max(min, Math.min(max, value));
    }

    // Iterate over each pixel (each pixel consists of 4 values: R, G, B, A)
    for (let i = 0; i < data.length; i += 4) {
        let r = data[i];
        let g = data[i+1];
        let b = data[i+2];
        // Alpha channel (data[i+3]) is preserved throughout the operations

        // 1. Brightness Adjustment
        // This shifts the overall lightness before other tonal adjustments.
        r += brightnessAdjust;
        g += brightnessAdjust;
        b += brightnessAdjust;

        // 2. Desaturation
        // Calculate a grayscale value (luminance) using the brightness-adjusted colors.
        // Standard BT.601 luminance coefficients:
        const gray = 0.299 * r + 0.587 * g + 0.114 * b;
        // Lerp (linear interpolate) between the current color and its grayscale equivalent.
        r = r * (1 - desaturationAmount) + gray * desaturationAmount;
        g = g * (1 - desaturationAmount) + gray * desaturationAmount;
        b = b * (1 - desaturationAmount) + gray * desaturationAmount;
        
        // 3. Contrast Adjustment
        // Formula: NewValue = ((OldValue/255 - 0.5) * Factor + 0.5) * 255
        // This formula pivots around 128 (or 0.5 in normalized space).
        // Values may currently be outside [0,255] due to previous steps;
        // the formula handles this okay, and final clamping will fix it.
        r = ((r / 255.0 - 0.5) * contrastValue + 0.5) * 255.0;
        g = ((g / 255.0 - 0.5) * contrastValue + 0.5) * 255.0;
        b = ((b / 255.0 - 0.5) * contrastValue + 0.5) * 255.0;

        // 4. Cool Tone Tint
        // Adds to the blue channel and subtracts from the red channel.
        // Green channel is not directly affected by this tint, creating a specific cool cast.
        b += coolStrength;
        r -= coolStrength * 0.5; // Reduce red by half the amount blue is increased

        // 5. Grain Addition (optional)
        if (grainAmount > 0) {
            // Generate monochrome noise: a random value centered around 0.
            const noise = (Math.random() - 0.5) * grainAmount;
            r += noise;
            g += noise;
            b += noise;
        }

        // Final clamping for R, G, B channels to ensure they are within [0, 255]
        data[i]   = clamp(r);
        data[i+1] = clamp(g);
        data[i+2] = clamp(b);
        // data[i+3] (alpha) remains unchanged
    }

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

    return canvas;
}