Add support for BackgroundRemoval effect

Author: const-cloudinary

src/Transformation/Effect/ListEffectQualifier.php

@@ -0,0 +1,41 @@
+<?php
+/**
+ * This file is part of the Cloudinary PHP package.
+ *
+ * (c) Cloudinary
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Cloudinary\Transformation;
+
+
+/**
+ * Class ListEffectQualifier
+ */
+class ListEffectQualifier extends EffectQualifier
+{
+    const PROPERTIES = 'properties';
+
+    /**
+     * ListEffectQualifier constructor.
+     *
+     * @param string $effectName The name of the effect.
+     * @param mixed  ...$values  The effect values.
+     */
+    public function __construct($effectName, ...$values)
+    {
+        parent::__construct($effectName);
+
+        $this->getValue()->setSimpleValue(self::PROPERTIES, new ListExpressionQualifierMultiValue(...$values));
+    }
+
+    /**
+     * @return mixed
+     */
+    public function getPropertiesValue()
+    {
+        return parent::getValue()->getSimpleValue(self::PROPERTIES);
+    }
+}

src/Transformation/Effect/Pixel/BackgroundRemoval.php

@@ -0,0 +1,79 @@
+<?php
+/**
+ * This file is part of the Cloudinary PHP package.
+ *
+ * (c) Cloudinary
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Cloudinary\Transformation;
+
+/**
+ * Class BackgroundRemoval
+ *
+ * Uses the Cloudinary AI Background Removal add-on to make the background of an image transparent.
+ *
+ *
+ * **Learn more**: <a
+ * href="https://cloudinary.com/documentation/transformation_reference#e_background_removal" target="_blank">
+ * Background removal</a>
+ *
+ * @api
+ */
+class BackgroundRemoval extends EffectAction
+{
+    const FINE_EDGES = 'fineedges';
+    const HINTS      = 'hints';
+
+    /**
+     * RemoveBackground constructor.
+     *
+     * @param bool|null $fineEdges        Enables detailed background removal around a foreground object with fine
+     *                                    detail around its edges.
+     * @param array     $hints            A list of foreground objects to keep.
+     */
+    public function __construct($fineEdges = null, $hints = [])
+    {
+        parent::__construct(new ListEffectQualifier(PixelEffect::BACKGROUND_REMOVAL));
+
+        $this->fineEdges($fineEdges);
+        $this->hints($hints);
+    }
+
+    /**
+     * Provides better results if you know that the object has more clear-cut edges.
+     *
+     * @param bool|null $fineEdges Whether to apply fine edges mode.
+     *
+     * @return BackgroundRemoval
+     */
+    public function fineEdges($fineEdges = true)
+    {
+        $value = $fineEdges === true ? 'y' : ($fineEdges === false ? 'n' : $fineEdges);
+
+        $this->getMainQualifier()->getPropertiesValue()->setSimpleNamedValue(self::FINE_EDGES, $value);
+
+        return $this;
+    }
+
+    /**
+     * Sets a list of foreground objects to keep.
+     *
+     * @param array $foregroundObjects A list of foreground objects to keep.
+     *
+     * @return BackgroundRemoval
+     */
+    public function hints(...$foregroundObjects)
+    {
+        $this->getMainQualifier()->getPropertiesValue()->setSimpleNamedValue(
+            self::HINTS,
+            new FullListExpressionQualifierMultiValue(
+                ...$foregroundObjects
+            )
+        );
+
+        return $this;
+    }
+}

src/Transformation/Effect/Pixel/ImagePixelEffectTrait.php

@@ -68,6 +68,23 @@ public static function removeBackground($screen = false, $colorToRemove = null)
         return new RemoveBackground($screen, $colorToRemove);
     }
 
+    /**
+     * Uses the Cloudinary AI Background Removal add-on to make the background of an image transparent.
+     *
+     *
+     * @param bool|null $fineEdges        Enables detailed background removal around a foreground object with fine
+     *                                    detail around its edges.
+     * @param array     $hints            A list of foreground objects to keep.
+     *
+     * @return BackgroundRemoval
+     *
+     * @see \Cloudinary\Transformation\BackgroundRemoval
+     */
+    public static function backgroundRemoval($fineEdges = null, $hints = [])
+    {
+        return new BackgroundRemoval($fineEdges, $hints);
+    }
+
     /**
      * Applies an ordered dither filter to the image.
      *

src/Transformation/Effect/Pixel/PixelEffect.php

@@ -20,16 +20,17 @@ abstract class PixelEffect
     const VIGNETTE = 'vignette';
 
     // Image
-    const BLUR_FACES        = 'blur_faces';
-    const BLUR_REGION       = 'blur_region';
-    const PIXELATE          = 'pixelate';
-    const PIXELATE_REGION   = 'pixelate_region';
-    const PIXELATE_FACES    = 'pixelate_faces';
-    const ORDERED_DITHER    = 'ordered_dither';
-    const GRADIENT_FADE     = 'gradient_fade';
-    const MAKE_TRANSPARENT  = 'make_transparent';
-    const REMOVE_BACKGROUND = 'bgremoval';
-    const CUT_OUT           = 'cut_out';
+    const BLUR_FACES         = 'blur_faces';
+    const BLUR_REGION        = 'blur_region';
+    const PIXELATE           = 'pixelate';
+    const PIXELATE_REGION    = 'pixelate_region';
+    const PIXELATE_FACES     = 'pixelate_faces';
+    const ORDERED_DITHER     = 'ordered_dither';
+    const GRADIENT_FADE      = 'gradient_fade';
+    const MAKE_TRANSPARENT   = 'make_transparent';
+    const REMOVE_BACKGROUND  = 'bgremoval';
+    const BACKGROUND_REMOVAL = 'background_removal';
+    const CUT_OUT            = 'cut_out';
 
     use PixelEffectTrait;
     use ImagePixelEffectTrait;

src/Transformation/Qualifier/QualifierValue/Effect/ForegroundObject.php

@@ -0,0 +1,42 @@
+<?php
+/**
+ * This file is part of the Cloudinary PHP package.
+ *
+ * (c) Cloudinary
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Cloudinary\Transformation;
+
+/**
+ *  Defines the available foreground objects.
+ *
+ * @api
+ */
+class ForegroundObject extends BaseArgument
+{
+    const AIRPLANE     = 'airplane';
+    const BUS          = 'bus';
+    const DINING_TABLE = 'dining_table';
+    const SHEEP        = 'sheep';
+    const BICYCLE      = 'bicycle';
+    const CAR          = 'car';
+    const DOG          = 'dog';
+    const SOFA         = 'sofa';
+    const BIRD         = 'bird';
+    const CAT          = 'cat';
+    const HORSE        = 'horse';
+    const TRAIN        = 'train';
+    const BOAT         = 'boat';
+    const CHAIR        = 'chair';
+    const PERSON       = 'person';
+    const TV           = 'tv';
+    const BOTTLE       = 'bottle';
+    const COW          = 'cow';
+    const POTTED_PLANT = 'potted_plant';
+    const MOTORBIKE    = 'motorbike';
+
+    use ForegroundObjectTrait;
+}