Image Blue Twilight Filter Applicator

/**
 * Applies a "Blue Twilight" cinematic filter to an image.
 * This effect is characterized by a cool, blue/cyan color cast, reduced brightness, and increased contrast,
 * similar to the visual style of the Twilight film series.
 *
 * @param {HTMLImageElement} originalImg The original Javascript Image object.
 * @param {number} blueIntensity The amount of blue to add to the image's color balance. A value between 0-255 is recommended. Default is 40.
 * @param {number} cyanIntensity The amount of cyan (green channel) to add to the color balance. A value between 0-255 is recommended. Default is 25.
 * @param {number} brightness A value to adjust the overall brightness. Negative values darken the image, positive values lighten it. Recommended range is -100 to 100. Default is -20.
 * @param {number} contrast A value to adjust the contrast. Negative values decrease contrast, positive values increase it. Recommended range is -100 to 100. Default is 25.
 * @returns {HTMLCanvasElement} A new canvas element with the filtered image.
 */
function processImage(originalImg, blueIntensity = 40, cyanIntensity = 25, brightness = -20, contrast = 25) {
    // Create a new canvas element
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

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

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

    // Get the image data from the canvas
    // This returns a flat array of RGBA values for each pixel
    const imageData = ctx.getImageData(0, 0, w, h);
    const data = imageData.data;

    // This formula creates a multiplicative factor from a -255 to 255 contrast range.
    // We adjust our -100 to 100 input to fit this formula for a nice contrast curve.
    const contrastFactor = (259 * (contrast + 255)) / (255 * (259 - contrast));

    // Helper function to ensure a color channel value stays within the 0-255 range
    const clamp = (value) => Math.max(0, Math.min(255, value));

    // Iterate through every pixel in the image
    // Each pixel is represented by 4 consecutive values in the data array: R, G, B, A
    for (let i = 0; i < data.length; i += 4) {
        let r = data[i]; // Red channel
        let g = data[i + 1]; // Green channel
        let b = data[i + 2]; // Blue channel

        // 1. Apply Brightness
        // Add the brightness value to each color channel
        r += brightness;
        g += brightness;
        b += brightness;

        // 2. Apply Contrast
        // Adjust each channel relative to the midpoint (128)
        r = (contrastFactor * (r - 128)) + 128;
        g = (contrastFactor * (g - 128)) + 128;
        b = (contrastFactor * (b - 128)) + 128;

        // 3. Apply the Twilight Color Filter
        // The characteristic look involves muting warmer tones (red) and boosting cooler tones (green/blue)
        r *= 0.9; // Slightly reduce the red channel
        g += cyanIntensity;
        b += blueIntensity;

        // 4. Write the new, clamped values back to the image data array
        data[i] = clamp(r);
        data[i + 1] = clamp(g);
        data[i + 2] = clamp(b);
    }

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

    // Return the canvas element, which can be displayed on the page
    return canvas;
}