feat: Make Image utility immutable

CodeWithKyrian · CodeWithKyrian · commit 6e938ec11487 · 2024-08-01T22:56:08.000+01:00
diff --git a/docs/utils/image.md b/docs/utils/image.md
@@ -47,7 +47,9 @@ Image::setDriver(ImageDriver::GD);
 ## Image Processing Operations
 
 The `Image` utility class provides a range of image processing operations that can be performed on images. These
-operations include:
+operations are immutable, meaning that all operations essentially return a new instance of `Image` with the operation
+applied without affecting the current instance. This allows for method chaining and simplifies the process of applying
+multiple operations to an image.
 
 - ### `read(string $input, array $options = [])`
   Reads an image from a file path, URL, or resource and returns an image object.
@@ -94,8 +96,7 @@ operations include:
   ```
 
 - ### `resize(int $width, int $height, int|Resample $resample = 2)`
-  Resizes an image to the specified width and height, using the specified resampling method. This operation affects the
-  instance it's called on, but still returns that instance for method chaining.
+  Resizes an image to the specified width and height, using the specified resampling method.
 
   Parameters:
     - `$width` (int) The target width of the resized image.
@@ -111,8 +112,7 @@ operations include:
   ```
   
 - ### `thumbnail(int $width, int $height, int|Resample $resample = 2)`
-    Creates a thumbnail of the image with the specified width and height, using the specified resampling method. This
-    operation affects the instance it's called on, but still returns that instance for method chaining.
+    Creates a thumbnail of the image with the specified width and height, using the specified resampling method.
     
     Parameters:
         - `$width` (int) The target width of the thumbnail.
@@ -128,8 +128,7 @@ operations include:
     ```
 
 - ### `crop(int $xMin, int $yMin, int $xMax, int $yMax)`
-  Crops the image to the specified bounding box defined by the top-left and bottom-right coordinates. This operation
-  affects the instance it's called on, but still returns that instance for method chaining.
+  Crops the image to the specified bounding box defined by the top-left and bottom-right coordinates.
 
   Parameters:
     - `$xMin` (int) The x-coordinate of the top-left corner of the bounding box.
@@ -146,8 +145,7 @@ operations include:
   ```
 
 - ### `centerCrop(int $width, int $height)`
-  Crops the image to the specified width and height by centering the crop around the image's center. This operation
-  affects the instance it's called on, but still returns that instance for method chaining.
+  Crops the image to the specified width and height by centering the crop around the image's center.
 
   Parameters:
     - `$width` (int) The target width of the cropped image.
@@ -162,8 +160,7 @@ operations include:
   ```
 
 - ### `pad(int $left, int $right, int $top, int $bottom)`
-  Pads the image with the specified number of pixels on each side. This operation affects the instance it's called on,
-  but still returns that instance for method chaining.
+  Pads the image with the specified number of pixels on each side.
 
   Parameters:
     - `$left` (int) The number of pixels to add to the left side.
@@ -180,8 +177,7 @@ operations include:
   ```
 
 - ### `grayscale()`
-  Converts the image to grayscale. This operation affects the instance it's called on, but still returns that instance
-  for method chaining.
+  Converts the image to grayscale.
 
   Returns:
     - An image object representing the grayscale image.
@@ -192,8 +188,7 @@ operations include:
   ```
 
 - ### `rgb()`
-  Converts the image to RGB color space. This operation affects the instance it's called on, but still returns that
-  instance for method chaining.
+  Converts the image to RGB color space.
 
   Returns:
     - An image object representing the RGB image.
@@ -204,8 +199,7 @@ operations include:
   ```
 
 - ### `rgba()`
-  Converts the image to RGBA color space. This operation affects the instance it's called on, but still returns that
-  instance for method chaining.
+  Converts the image to RGBA color space.
 
   Returns:
     - An image object representing the RGBA image.
@@ -214,10 +208,27 @@ operations include:
   ```php
   $rgbaImage = $image->rgba();
   ```
+  
+- ### `applyMask(Image $mask)`
+  Applies a mask to the current image.
+
+  Parameters:
+  - `$mask` (Image) The mask to apply.
+
+  Returns:
+  - An image object representing the image with the mask applied.
+
+  Throws:
+  - `InvalidArgumentException` if the given mask doesn't match the current image's size or if the image driver is unsupported.
+  - `RuntimeException` if the apply mask operation fails.
+
+  Example:
+  ```php
+  $maskedImage = $image->applyMask($mask);
+  ```
 
 - ### `drawRectangle(int $xMin, int $yMin, int $xMax, int $yMax, string $color = 'FFF', $fill = false, float $thickness = 1)`
-  Draws a rectangle on the image with the specified coordinates, color, and thickness. This operation affects the
-  instance it's called on, but still returns that instance for method chaining.
+  Draws a rectangle on the image with the specified coordinates, color, and thickness.
 
   Parameters:
     - `$xMin` (int) The x-coordinate of the top-left corner of the rectangle.
@@ -238,8 +249,7 @@ operations include:
 
 - ### `drawText(string $text, int $xPos, int $yPos, string $fontFile, int $fontSize = 16, string $color = 'FFF')`
 
-  Draws text on the image at the specified position with the specified font, size, and color. This operation affects the
-  instance it's called on, but still returns that instance for method chaining.
+  Draws text on the image at the specified position with the specified font, size, and color.
 
   Parameters:
     - `$text` (string) The text to draw on the image.
diff --git a/src/FeatureExtractors/ImageFeatureExtractor.php b/src/FeatureExtractors/ImageFeatureExtractor.php
@@ -7,57 +7,36 @@
 
 use Codewithkyrian\Transformers\Tensor\Tensor;
 use Codewithkyrian\Transformers\Utils\Image;
+use Exception;
 use Imagine\Image\Point;
 
 class ImageFeatureExtractor extends FeatureExtractor
 {
-    /**
-     * The mean values for image normalization.
-     * @var int|int[]
-     */
+    /** The mean values for image normalization. */
     protected int|array|null $imageMean;
 
-    /**
-     * The standard deviation values for image normalization.
-     * @var int|int[]
-     */
+    /** The standard deviation values for image normalization. */
     protected int|array|null $imageStd;
 
-    /*
-     * What method to use for resampling.
-     */
+    /* What method to use for resampling. */
     protected int $resample;
 
-    /**
-     * Whether to rescale the image pixel values to the [0,1] range.
-     * @var bool
-     */
+    /** Whether to rescale the image pixel values to the [0,1] range. */
     protected bool $doRescale;
 
-    /**
-     * The factor to use for rescaling the image pixel values.
-     * @var float
-     */
+    /** The factor to use for rescaling the image pixel values. */
     protected float $rescaleFactor;
 
-    /**
-     * Whether to normalize the image pixel values.
-     * @var ?bool
-     */
+    /** Whether to normalize the image pixel values. */
     protected ?bool $doNormalize;
 
-    /**
-     * Whether to resize the image.
-     * @var ?bool
-     */
+    /**  Whether to resize the image. */
     protected ?bool $doResize;
 
+    /**  The size to resize the image to. */
     protected ?bool $doThumbnail;
 
-    /**
-     * The size to resize the image to.
-     * @var ?array
-     */
+    /**  The size to resize the image to. */
     protected ?array $size;
     protected mixed $sizeDivisibility;
     protected ?bool $doCenterCrop;
@@ -102,18 +81,20 @@ public function __construct(public array $config)
 
     /**
      * Pad the image by a certain amount.
+     *
      * @param Tensor $imageTensor The pixel data to pad.
      * @param int[]|int $padSize The dimensions of the padded image.
      * @param string $mode The type of padding to add.
      * @param bool $center Whether to center the image.
      * @param int $constantValues The constant value to use for padding.
+     *
      * @return Tensor The padded pixel data and image dimensions.
-     * @throws \Exception
+     * @throws Exception
      */
     public function padImage(
         Tensor    $imageTensor,
         int|array $padSize,
-        string $tensorFormat = 'CHW', // 'HWC' or 'CHW
+        string    $tensorFormat = 'CHW', // 'HWC' or 'CHW
         string    $mode = 'constant',
         bool      $center = false,
         int       $constantValues = 0
@@ -170,7 +151,7 @@ public function padImage(
 
             if ($mode === 'symmetric') {
                 if ($center) {
-                    throw new \Exception('`center` padding is not supported when `mode` is set to `symmetric`.');
+                    throw new Exception('`center` padding is not supported when `mode` is set to `symmetric`.');
                     // TODO: Implement this
                 }
                 $h1 = $imageHeight - 1;
@@ -210,9 +191,12 @@ private function calculateReflectOffset(int $val, int $max): int
     /**
      * Find the target (width, height) dimension of the output image after
      * resizing given the input image and the desired size.
+     *
      * @param Image $image The image to be resized.
      * @param int|array|null $size The size to use for resizing the image.
+     *
      * @return array The target (width, height) dimension of the output image after resizing.
+     * @throws Exception
      */
     public function getResizeOutputImageSize(Image $image, int|array|null $size): array
     {
@@ -286,7 +270,7 @@ public function getResizeOutputImageSize(Image $image, int|array|null $size): ar
         } elseif ($this->sizeDivisibility != null) {
             return $this->enforceSizeDivisibility([$srcWidth, $srcHeight], $this->sizeDivisibility);
         } else {
-            throw new \Exception("Could not resize image due to unsupported 'size' parameter passed: " . json_encode($size));
+            throw new Exception("Could not resize image due to unsupported 'size' parameter passed: ".json_encode($size));
         }
     }
 
@@ -295,12 +279,13 @@ public function getResizeOutputImageSize(Image $image, int|array|null $size): ar
      * Preprocesses the given image.
      *
      * @param Image $image The image to preprocess.
-     * @param ?bool $doNormalize
-     * @param ?bool $doPad
-     * @param ?bool $doConvertRGB
-     * @param ?bool $doConvertGrayscale
+     * @param ?bool $doNormalize Whether to normalize the image.
+     * @param ?bool $doPad Whether to pad the image.
+     * @param ?bool $doConvertRGB Whether to convert the image to RGB.
+     * @param ?bool $doConvertGrayscale Whether to convert the image to grayscale.
+     *
      * @return array The preprocessed image.
-     * @throws \Exception
+     * @throws Exception
      */
     public function preprocess(
         Image $image,
@@ -316,7 +301,6 @@ public function preprocess(
             $image = $image->cropMargin();
         }
 
-
         $originalInputSize = $image->size(); // original image size
 
         // Convert image to RGB if specified in config.
@@ -348,7 +332,7 @@ public function preprocess(
                 $cropHeight = $this->cropSize['height'];
             }
 
-           $image =  $image->centerCrop($cropWidth, $cropHeight);
+            $image = $image->centerCrop($cropWidth, $cropHeight);
         }
 
         $reshapedInputSize = $image->size();
@@ -362,7 +346,7 @@ public function preprocess(
         if ($doNormalize ?? $this->doNormalize) {
             if (is_array($this->imageMean)) {
                 // Negate the mean values to add instead of subtract
-                $negatedMean = array_map(fn($mean) => -$mean, $this->imageMean);
+                $negatedMean = array_map(fn ($mean) => -$mean, $this->imageMean);
                 $imageMean = Tensor::repeat($negatedMean, $image->height() * $image->width(), 1);
             } else {
                 $imageMean = Tensor::fill([$image->channels * $image->height() * $image->width()], -$this->imageMean);
@@ -371,7 +355,7 @@ public function preprocess(
 
             if (is_array($this->imageStd)) {
                 // Inverse the standard deviation values to multiple instead of divide
-                $inversedStd = array_map(fn($std) => 1 / $std, $this->imageStd);
+                $inversedStd = array_map(fn ($std) => 1 / $std, $this->imageStd);
                 $imageStd = Tensor::repeat($inversedStd, $image->height() * $image->width(), 1);
             } else {
                 $imageStd = Tensor::fill([$image->channels * $image->height() * $image->width()], 1 / $this->imageStd);
@@ -383,7 +367,7 @@ public function preprocess(
             $imageStd = $imageStd->reshape($imageTensor->shape());
 
             if (count($imageMean) !== $image->channels || count($imageStd) !== $image->channels) {
-                throw new \Exception("When set to arrays, the length of `imageMean` (" . count($imageMean) . ") and `imageStd` (" . count($imageStd) . ") must match the number of channels in the image ({$image->channels}).");
+                throw new Exception("When set to arrays, the length of `imageMean` (".count($imageMean).") and `imageStd` (".count($imageStd).") must match the number of channels in the image ({$image->channels}).");
             }
 
             // Normalize pixel data
@@ -411,31 +395,26 @@ public function preprocess(
      * Calls the feature extraction process on an array of images,
      * preprocesses each image, and concatenates the resulting
      * features into a single Tensor.
+     *
      * @param Image|Image[] $images The image(s) to extract features from.
      * @param mixed ...$args Additional arguments.
+     *
      * @return array An object containing the concatenated pixel values (and other metadata) of the preprocessed images.
      */
     public function __invoke(Image|array $images, ...$args): array
     {
-        // Ensure $images is an array
         if (!is_array($images)) {
             $images = [$images];
         }
 
-        // Preprocess each image
-        $imageData = [];
-        foreach ($images as $image) {
-            $imageData[] = $this->preprocess($image);
-        }
+        $imageData = array_map([$this, 'preprocess'], $images);
 
         $pixelValues = array_column($imageData, 'pixel_values');
         $originalSizes = array_column($imageData, 'original_size');
         $reshapedInputSizes = array_column($imageData, 'reshaped_input_size');
 
-        $stackedPixelValues = Tensor::stack($pixelValues, 0);
-
         return [
-            'pixel_values' => $stackedPixelValues,
+            'pixel_values' => Tensor::stack($pixelValues),
             'original_sizes' => $originalSizes,
             'reshaped_input_sizes' => $reshapedInputSizes
         ];
diff --git a/src/Utils/Image.php b/src/Utils/Image.php
