Image CineScope Aspect Ratio Filter Effect Tool

/**
 * Applies a CineScope aspect ratio filter effect to an image.
 * This typically involves adding letterbox (horizontal bars) or pillarbox (vertical bars)
 * to make the image content conform to the target aspect ratio.
 * The parts of the original image that fall outside the target aspect ratio are effectively cropped
 * by only drawing the central portion that fits the new aspect ratio.
 * The output canvas will have the same dimensions as the original image.
 *
 * @param {Image} originalImg The original JavaScript Image object. Assumed to be loaded.
 * @param {number} [targetRatio=2.35] The target aspect ratio (e.g., 2.35 for CineScope). Must be a positive number.
 * @param {string} [barColor="black"] The color of the bars (letterbox/pillarbox). Any valid CSS color string.
 * @returns {HTMLCanvasElement} A new canvas element displaying the image with the CineScope effect.
 */
function processImage(originalImg, targetRatio = 2.35, barColor = "black") {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');

    // Use naturalWidth/Height for original dimensions, fallback to width/height.
    const imgWidth = originalImg.naturalWidth || originalImg.width;
    const imgHeight = originalImg.naturalHeight || originalImg.height;

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

    // Validate and sanitize parameters
    let effectiveTargetRatio = targetRatio;
    if (typeof effectiveTargetRatio !== 'number' || effectiveTargetRatio <= 0) {
        console.warn(`Invalid targetRatio provided: "${targetRatio}". Defaulting to 2.35.`);
        effectiveTargetRatio = 2.35;
    }

    let effectiveBarColor = barColor;
    if (typeof effectiveBarColor !== 'string' || effectiveBarColor.trim() === "") {
        console.warn(`Invalid barColor provided: "${barColor}". Defaulting to "black".`);
        effectiveBarColor = "black";
    }
    
    // Handle cases where the image might not be loaded or has zero dimensions
    if (imgWidth === 0 || imgHeight === 0) {
        // Fill canvas with barColor if canvas has dimensions, otherwise it's a 0x0 canvas.
        if (canvas.width > 0 && canvas.height > 0) {
            ctx.fillStyle = effectiveBarColor;
            ctx.fillRect(0, 0, canvas.width, canvas.height);
        }
        // Optionally, one could throw an error here for clearer feedback to the caller.
        // e.g., throw new Error("Image has zero dimensions or is not loaded properly.");
        return canvas;
    }

    const currentRatio = imgWidth / imgHeight;
    ctx.fillStyle = effectiveBarColor;

    // Epsilon for comparing floating-point aspect ratios accurately
    const epsilon = 0.001; 

    if (Math.abs(currentRatio - effectiveTargetRatio) < epsilon) {
        // Image already has (or is very close to) the target aspect ratio.
        // Draw the original image as is.
        ctx.drawImage(originalImg, 0, 0, imgWidth, imgHeight);
    } else if (currentRatio < effectiveTargetRatio) {
        // Image is "taller" than the target aspect ratio (e.g., 4:3 source, 2.35:1 target).
        // This requires letterboxing (bars at top and bottom).
        
        // Calculate the height of the content area based on the image's width and target aspect ratio.
        const contentHeight = imgWidth / effectiveTargetRatio;
        // Calculate the height of each black bar.
        const barHeight = (imgHeight - contentHeight) / 2;

        // Draw top bar
        ctx.fillRect(0, 0, imgWidth, barHeight);
        
        // Draw the central portion of the original image.
        // sx, sy, sWidth, sHeight define the rectangle to take from the source image.
        // dx, dy, dWidth, dHeight define where to draw it on the canvas.
        ctx.drawImage(originalImg, 
                      0,             // sx: Source x (start from left edge of original image)
                      barHeight,     // sy: Source y (crop 'barHeight' from top of original image)
                      imgWidth,      // sWidth: Source width (use full width of original image)
                      contentHeight, // sHeight: Source height (the calculated height of the visible content area)
                      0,             // dx: Destination x on canvas (draw at left edge)
                      barHeight,     // dy: Destination y on canvas (draw below the top bar)
                      imgWidth,      // dWidth: Destination width on canvas (draw at full width)
                      contentHeight  // dHeight: Destination height on canvas (draw at calculated content height)
        );
        
        // Draw bottom bar
        ctx.fillRect(0, barHeight + contentHeight, imgWidth, barHeight);

    } else { // currentRatio > effectiveTargetRatio
        // Image is "wider" than the target aspect ratio (e.g., 3:1 source, 2.35:1 target).
        // This requires pillarboxing (bars at left and right).

        // Calculate the width of the content area based on the image's height and target aspect ratio.
        const contentWidth = imgHeight * effectiveTargetRatio;
        // Calculate the width of each black bar.
        const barWidth = (imgWidth - contentWidth) / 2;

        // Draw left bar
        ctx.fillRect(0, 0, barWidth, imgHeight);

        // Draw the central portion of the original image.
        ctx.drawImage(originalImg,
                      barWidth,      // sx: Source x (crop 'barWidth' from left of original image)
                      0,             // sy: Source y (start from top edge of original image)
                      contentWidth,  // sWidth: Source width (the calculated width of the visible content area)
                      imgHeight,     // sHeight: Source height (use full height of original image)
                      barWidth,      // dx: Destination x on canvas (draw right of the left bar)
                      0,             // dy: Destination y on canvas (draw at top edge)
                      contentWidth,  // dWidth: Destination width on canvas (draw at calculated content width)
                      imgHeight      // dHeight: Destination height on canvas (draw at full height)
        );
        
        // Draw right bar
        ctx.fillRect(barWidth + contentWidth, 0, barWidth, imgHeight);
    }

    return canvas;
}