feat: Make Image utility immutable

Author: CodeWithKyrian

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.

src/FeatureExtractors/ImageFeatureExtractor.php

@@ -7,64 +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;
@@ -171,7 +143,7 @@ public function cropMargin(Image $image, int $grayThreshold = 200): static
      * @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,
@@ -233,7 +205,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;
@@ -278,6 +250,7 @@ private function calculateReflectOffset(int $val, int $max): int
      * @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
     {
@@ -351,7 +324,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));
         }
     }
 
@@ -360,13 +333,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,
@@ -382,7 +355,6 @@ public function preprocess(
             $image = $image->cropMargin();
         }
 
-
         $originalInputSize = $image->size(); // original image size
 
         // Convert image to RGB if specified in config.
@@ -414,7 +386,7 @@ public function preprocess(
                 $cropHeight = $this->cropSize['height'];
             }
 
-           $image =  $image->centerCrop($cropWidth, $cropHeight);
+            $image = $image->centerCrop($cropWidth, $cropHeight);
         }
 
         $reshapedInputSize = $image->size();
@@ -449,7 +421,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
@@ -485,25 +457,18 @@ public function preprocess(
      */
     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
         ];