Add configurable background scaling modes for rembg (Magic Greenscreen)

- Add backgroundMode config parameter with 5 modes:
  - scale-fill (default): Cover canvas, preserve aspect ratio, may crop
  - scale-fit: Fit inside canvas, preserve aspect ratio, may have black bars
  - crop-center: Crop from center to match canvas size
  - stretch: Stretch to exact size (may distort)
  - none: Direct copy without scaling (original behavior)
- Implement applyBackgroundWithMode() method in Rembg.php
- Add admin panel UI (select field in advanced view)
- Add config schema validation in RembgConfiguration.php
- Add English translations for UI labels and help text
- Add documentation in FAQ
- Fix memory leak: add imagedestroy() for background image

Fixes #1364

Author: flacoonb

docs/faq/index.md

@@ -543,6 +543,12 @@ Magic Greenscreen is a feature that uses AI to automatically remove backgrounds
    - Check "Remove background" to enable the feature
    - Optionally configure:
      - **Background image:** Path to a custom background image (leave empty for transparent background)
+     - **Background scaling mode:** How the background image is scaled/cropped (default: scale-fill)
+       - `scale-fill` (recommended): Covers entire canvas, preserves aspect ratio, may crop edges
+       - `scale-fit`: Fits inside canvas, preserves aspect ratio, may have black bars
+       - `crop-center`: Crops from center to exact canvas size
+       - `stretch`: Stretches to fit (may distort)
+       - `none`: Direct copy without scaling (original behavior)
      - **AI model:** Choose the AI model (default: u2net)
      - **Alpha matting:** Enable for better edge quality
      - **Alpha matting thresholds:** Fine-tune edge detection (advanced users)

lib/configsetup.inc.php

@@ -1169,6 +1169,21 @@
                 PathUtility::getAbsolutePath('private/images/background'),
             ]
         ],
+        'rembg_backgroundMode' => [
+            'view' => 'advanced',
+            'type' => 'select',
+            'name' => 'rembg[backgroundMode]',
+            'placeholder' => $defaultConfig['rembg']['backgroundMode'],
+            'data-theme-field' => 'true',
+            'options' => [
+                'scale-fill' => 'Scale Fill (Cover canvas, preserve ratio)',
+                'scale-fit' => 'Scale Fit (Fit inside, black bars)',
+                'crop-center' => 'Crop Center (Cut from center)',
+                'stretch' => 'Stretch (Distort to fit)',
+                'none' => 'None (Direct copy, no scaling)',
+            ],
+            'value' => $config['rembg']['backgroundMode'],
+        ],
         'rembg_model' => [
             'view' => 'advanced',
             'type' => 'select',

resources/lang/en.json

@@ -317,6 +317,7 @@
   "magic_greenscreen:rembg_alpha_matting_erode_size": "Alpha matting erode size",
   "magic_greenscreen:rembg_alpha_matting_foreground_threshold": "Alpha matting foreground threshold",
   "magic_greenscreen:rembg_background": "Background image",
+  "magic_greenscreen:rembg_backgroundMode": "Background scaling mode",
   "magic_greenscreen:rembg_enabled": "Remove background",
   "magic_greenscreen:rembg_model": "AI model",
   "magic_greenscreen:rembg_post_processing": "Post-processing",
@@ -499,6 +500,7 @@
   "manual:magic_greenscreen:rembg_alpha_matting_erode_size": "Erode size for alpha matting.",
   "manual:magic_greenscreen:rembg_alpha_matting_foreground_threshold": "Foreground threshold for alpha matting.",
   "manual:magic_greenscreen:rembg_background": "Path to the background image that will be used to replace the removed background.",
+  "manual:magic_greenscreen:rembg_backgroundMode": "Determines how the background image is scaled or cropped. <b>Scale Fill</b> (recommended) covers the entire canvas without distortion. <b>Scale Fit</b> preserves aspect ratio (may have black bars). <b>Crop Center</b> cuts from center. <b>Stretch</b> distorts the image. <b>None</b> copies without scaling.",
   "manual:magic_greenscreen:rembg_enabled": "If enabled, the background will be removed using AI.",
   "manual:magic_greenscreen:rembg_model": "AI model to use for background removal.",
   "manual:magic_greenscreen:rembg_post_processing": "Enable post-processing to improve the result.",

src/Configuration/Section/RembgConfiguration.php

@@ -14,6 +14,10 @@ public static function getNode(): NodeDefinition
             ->children()
                 ->booleanNode('enabled')->defaultValue(false)->end()
                 ->scalarNode('background')->defaultValue('')->end()
+                ->enumNode('backgroundMode')
+                    ->values(['none', 'scale-fit', 'scale-fill', 'crop-center', 'stretch'])
+                    ->defaultValue('scale-fill')
+                    ->end()
                 ->enumNode('model')
                     ->values(['u2net', 'u2netp', 'u2net_cloth_seg', 'u2net_human_seg', 'silueta', 'isnet_general_use', 'isnet_anime'])
                     ->defaultValue('u2net')

src/Rembg.php

@@ -129,12 +129,18 @@ public static function process(
                     if ($backgroundContent === false) {
                         $logger->error('Failed to read background image file');
                     } else {
+                        $backgroundImage = imagecreatefromstring($backgroundContent);
                         $backgroundImage = imagecreatefromstring($backgroundContent);
                         if ($backgroundImage !== false) {
-                            $newImage = imagecreatetruecolor(imagesx($processedImage), imagesy($processedImage));
-                            imagecopy($newImage, $backgroundImage, 0, 0, 0, 0, imagesx($processedImage), imagesy($processedImage));
-                            imagecopy($newImage, $processedImage, 0, 0, 0, 0, imagesx($processedImage), imagesy($processedImage));
+                            $backgroundMode = $rembgConfig['backgroundMode'] ?? 'scale-fill';
+                            $newImage = self::applyBackgroundWithMode(
+                                $processedImage,
+                                $backgroundImage,
+                                $backgroundMode,
+                                $logger
+                            );
                             imagedestroy($processedImage);
+                            imagedestroy($backgroundImage);
                             $processedImage = $newImage;
                             $logger->debug('Background image applied after rembg processing');
                         }
@@ -161,4 +167,113 @@ public static function process(
             return [$imageHandler, $imageResource]; // Fallback to original image
         }
     }
+
+    /**
+     * Apply background image with different scaling/cropping modes
+     *
+     * @param \GdImage $foreground The transparent foreground image
+     * @param \GdImage $background The background image
+     * @param string $mode The mode: 'none', 'scale-fit', 'scale-fill', 'crop-center', 'stretch'
+     * @param \Photobooth\Logger\NamedLogger $logger Logger instance
+     * @return \GdImage The composited image
+     */
+    private static function applyBackgroundWithMode(
+        \GdImage $foreground,
+        \GdImage $background,
+        string $mode,
+        \Photobooth\Logger\NamedLogger $logger
+    ): \GdImage {
+        $canvasWidth = imagesx($foreground);
+        $canvasHeight = imagesy($foreground);
+        $bgWidth = imagesx($background);
+        $bgHeight = imagesy($background);
+
+        $canvas = imagecreatetruecolor($canvasWidth, $canvasHeight);
+
+        $logger->debug("Applying background with mode: {$mode} (Canvas: {$canvasWidth}x{$canvasHeight}, BG: {$bgWidth}x{$bgHeight})");
+
+        switch ($mode) {
+            case 'none':
+                // Original behavior: direct copy, no scaling
+                imagecopy($canvas, $background, 0, 0, 0, 0, $bgWidth, $bgHeight);
+                break;
+
+            case 'scale-fit':
+                // Scale background to fit inside canvas (preserve aspect ratio, may have black bars)
+                $scale = min($canvasWidth / $bgWidth, $canvasHeight / $bgHeight);
+                $scaledWidth = (int)($bgWidth * $scale);
+                $scaledHeight = (int)($bgHeight * $scale);
+                $offsetX = (int)(($canvasWidth - $scaledWidth) / 2);
+                $offsetY = (int)(($canvasHeight - $scaledHeight) / 2);
+
+                $black = imagecolorallocate($canvas, 0, 0, 0);
+                if ($black !== false) {
+                    imagefill($canvas, 0, 0, $black);
+                }
+                imagecopyresampled(
+                    $canvas,
+                    $background,
+                    $offsetX,
+                    $offsetY,
+                    0,
+                    0,
+                    $scaledWidth,
+                    $scaledHeight,
+                    $bgWidth,
+                    $bgHeight
+                );
+                break;
+
+            case 'scale-fill':
+                // Scale background to cover entire canvas (preserve aspect ratio, may crop)
+                $scale = max($canvasWidth / $bgWidth, $canvasHeight / $bgHeight);
+                $scaledWidth = (int)($bgWidth * $scale);
+                $scaledHeight = (int)($bgHeight * $scale);
+                $offsetX = (int)(($canvasWidth - $scaledWidth) / 2);
+                $offsetY = (int)(($canvasHeight - $scaledHeight) / 2);
+
+                imagecopyresampled(
+                    $canvas,
+                    $background,
+                    $offsetX,
+                    $offsetY,
+                    0,
+                    0,
+                    $scaledWidth,
+                    $scaledHeight,
+                    $bgWidth,
+                    $bgHeight
+                );
+                break;
+
+            case 'crop-center':
+                // Crop background from center to match canvas size
+                if ($bgWidth < $canvasWidth || $bgHeight < $canvasHeight) {
+                    // Background too small, scale up first
+                    $scale = max($canvasWidth / $bgWidth, $canvasHeight / $bgHeight);
+                    $scaledBg = imagecreatetruecolor((int)($bgWidth * $scale), (int)($bgHeight * $scale));
+                    imagecopyresampled($scaledBg, $background, 0, 0, 0, 0, imagesx($scaledBg), imagesy($scaledBg), $bgWidth, $bgHeight);
+                    $cropX = (int)((imagesx($scaledBg) - $canvasWidth) / 2);
+                    $cropY = (int)((imagesy($scaledBg) - $canvasHeight) / 2);
+                    imagecopy($canvas, $scaledBg, 0, 0, $cropX, $cropY, $canvasWidth, $canvasHeight);
+                    imagedestroy($scaledBg);
+                } else {
+                    $cropX = (int)(($bgWidth - $canvasWidth) / 2);
+                    $cropY = (int)(($bgHeight - $canvasHeight) / 2);
+                    imagecopy($canvas, $background, 0, 0, $cropX, $cropY, $canvasWidth, $canvasHeight);
+                }
+                break;
+
+            case 'stretch':
+            default:
+                // Stretch background to exact canvas size (may distort)
+                imagecopyresampled($canvas, $background, 0, 0, 0, 0, $canvasWidth, $canvasHeight, $bgWidth, $bgHeight);
+                break;
+        }
+
+        // Merge transparent foreground onto background
+        imagecopy($canvas, $foreground, 0, 0, 0, 0, $canvasWidth, $canvasHeight);
+
+        return $canvas;
+    }
 }