Image Reverse Graduated ND Filter Effect Tool

async function processImage(originalImg, strength = 0.5, horizonPosition = 0.5, gradientHeight = 0.3) {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    // Use naturalWidth/Height for HTMLImageElement for intrinsic size, fallback to width/height for other image sources
    const imgWidth = originalImg.naturalWidth || originalImg.width;
    const imgHeight = originalImg.naturalHeight || originalImg.height;

    canvas.width = imgWidth;
    canvas.height = imgHeight;

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

    // Clamp parameters to ensure they are within expected ranges [0, 1]
    strength = Math.max(0, Math.min(1, strength));
    horizonPosition = Math.max(0, Math.min(1, horizonPosition));
    gradientHeight = Math.max(0, Math.min(1, gradientHeight));

    // Calculate absolute pixel values for gradient geometry
    
    // maxStrengthY is the Y-coordinate where the darkening effect is strongest.
    // This corresponds to the "horizon line" for the filter effect.
    // At this line, the gradient reaches its full `strength` alpha.
    const maxStrengthY = imgHeight * horizonPosition;
    
    // gradientEffectiveHeight is the actual height in pixels of the gradient transition area.
    // This is the distance over which the filter effect fades from transparent to full strength.
    const gradientEffectiveHeight = imgHeight * gradientHeight;

    // If gradientEffectiveHeight is zero or negative (e.g., if gradientHeight parameter is 0),
    // the fillRect operation below will have zero or negative height.
    // According to canvas specs, this means nothing will be drawn, which is the correct behavior
    // for a gradient defined over a zero-height region. No special handling is needed.
    
    // gradientTopY is the Y-coordinate where the gradient effect begins.
    // At this line, the filter effect is fully transparent (alpha = 0).
    // The gradient progresses from transparent at gradientTopY to `strength` alpha at maxStrengthY.
    const gradientTopY = maxStrengthY - gradientEffectiveHeight;

    // Create a linear gradient object.
    // The gradient is vertical. Its coordinates are specified in the canvas's coordinate space.
    // It starts at (any X-coordinate, gradientTopY) and ends at (any X-coordinate, maxStrengthY).
    const grad = ctx.createLinearGradient(0, gradientTopY, 0, maxStrengthY);

    // Add color stops to define the gradient's color and alpha transition.
    // Stop 0: At the beginning of the gradient (y = gradientTopY), the overlay color is fully transparent black.
    grad.addColorStop(0, 'rgba(0,0,0,0)');
    // Stop 1: At the end of the gradient (y = maxStrengthY), the overlay color is black with an alpha value equal to `strength`.
    grad.addColorStop(1, `rgba(0,0,0,${strength})`);

    // Set the canvas fill style to the created gradient.
    ctx.fillStyle = grad;
    
    // Apply the gradient effect by filling a rectangle.
    // This rectangle starts at X=0, Y=gradientTopY.
    // Its width is the full image width.
    // Its height is `gradientEffectiveHeight`, so it covers the region from `gradientTopY` to `maxStrengthY`.
    // The Canvas API correctly handles cases where part of this rectangle (e.g., if gradientTopY is negative)
    // is outside the canvas boundaries; only the visible portion will be rendered.
    // The default `globalCompositeOperation` is 'source-over', which means the semi-transparent
    // gradient color will be drawn on top of the original image, achieving the desired blending.
    ctx.fillRect(0, gradientTopY, imgWidth, gradientEffectiveHeight);

    return canvas;
}