Image Paper Texture Generator

/**
 * Applies a customizable paper-like texture to an image.
 * This effect is created by generating a layer of noise, optionally blurring it,
 * and then blending it over the original image to simulate the grain of paper.
 *
 * @param {HTMLImageElement} originalImg The original javascript Image object.
 * @param {number} [textureIntensity=0.4] The opacity of the texture layer. A value between 0 (transparent) and 1 (opaque).
 * @param {number} [noiseAmount=80] The "graininess" of the texture. Higher values (up to 255) create more contrast in the noise.
 * @param {number} [blurAmount=0.5] The blur radius in pixels applied to the noise texture. 0 means no blur. Higher values create a softer texture.
 * @param {string} [blendMode='overlay'] The composite operation for blending the texture. Common options include 'overlay', 'soft-light', 'multiply', and 'screen'.
 * @returns {HTMLCanvasElement} A new canvas element with the paper texture applied.
 */
function processImage(originalImg, textureIntensity = 0.4, noiseAmount = 80, blurAmount = 0.5, blendMode = 'overlay') {
    // 1. Sanitize and validate parameters, providing fallbacks for invalid inputs.
    let intensity = Number(textureIntensity);
    if (isNaN(intensity) || intensity < 0 || intensity > 1) {
        intensity = 0.4; // Fallback to default
    }

    let noise = Number(noiseAmount);
    if (isNaN(noise) || noise < 0 || noise > 255) {
        noise = 80; // Fallback to default
    }

    let blur = Number(blurAmount);
    if (isNaN(blur) || blur < 0) {
        blur = 0.5; // Fallback to default
    }

    const validBlendModes = [
        'source-over', 'source-in', 'source-out', 'source-atop', 'destination-over', 'destination-in',
        'destination-out', 'destination-atop', 'lighter', 'copy', 'xor', 'multiply', 'screen',
        'overlay', 'darken', 'lighten', 'color-dodge', 'color-burn', 'hard-light', 'soft-light',
        'difference', 'exclusion', 'hue', 'saturation', 'color', 'luminosity'
    ];
    const finalBlendMode = validBlendModes.includes(blendMode) ? blendMode : 'overlay';

    // 2. Get image dimensions and set up canvases
    const width = originalImg.naturalWidth || originalImg.width;
    const height = originalImg.naturalHeight || originalImg.height;

    // The main canvas for the final output
    const canvas = document.createElement('canvas');
    canvas.width = width;
    canvas.height = height;
    const ctx = canvas.getContext('2d');

    // A temporary canvas to create the texture on
    const textureCanvas = document.createElement('canvas');
    textureCanvas.width = width;
    textureCanvas.height = height;
    const textureCtx = textureCanvas.getContext('2d');

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

    // 4. Generate the noise texture
    const imageData = textureCtx.createImageData(width, height);
    const data = imageData.data;

    // Iterate over each pixel and set a random grayscale value
    for (let i = 0; i < data.length; i += 4) {
        // Generate noise value centered around mid-gray (128)
        const randomValue = 128 + (Math.random() - 0.5) * noise;
        data[i] = randomValue;     // Red
        data[i + 1] = randomValue; // Green
        data[i + 2] = randomValue; // Blue
        data[i + 3] = 255;         // Alpha
    }

    // Put the generated noise onto the texture canvas
    textureCtx.putImageData(imageData, 0, 0);

    // 5. Optionally apply a blur to the noise to make it softer
    if (blur > 0) {
        textureCtx.filter = `blur(${blur}px)`;
        // To apply the filter, we draw the canvas onto itself.
        // The source is the canvas content *before* this draw operation.
        textureCtx.drawImage(textureCanvas, 0, 0);
        // Important: Reset the filter so it doesn't affect subsequent operations.
        textureCtx.filter = 'none';
    }

    // 6. Blend the texture layer onto the main canvas
    ctx.globalAlpha = intensity;
    ctx.globalCompositeOperation = finalBlendMode;
    ctx.drawImage(textureCanvas, 0, 0);

    // 7. Reset the context state to its default
    ctx.globalAlpha = 1.0;
    ctx.globalCompositeOperation = 'source-over';

    // 8. Return the final canvas
    return canvas;
}