Merge pull request #33 from CodeWithKyrian/0.4.0-dev

Merge 0.4.0 Changes

Author: CodeWithKyrian

.gitignore

@@ -9,3 +9,4 @@ playground/*
 .idea
 .transformers-cache/*
 tests/models/*
+dist

LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright [yyyy] [name of copyright owner]
+   Copyright 2024 Kyrian Obikwelu
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

bin/transformers

@@ -12,7 +12,7 @@ $application = new Application();
 try {
     $application->setName('Transformers PHP CLI');
 
-//    $application->add(new Codewithkyrian\Transformers\Commands\InitCommand());
+    $application->add(new Codewithkyrian\Transformers\Commands\InstallCommand());
     $application->add(new Codewithkyrian\Transformers\Commands\DownloadModelCommand());
 
     $application->run();

composer.json

@@ -14,20 +14,21 @@
   "type": "library",
   "require": {
     "php": "^8.1",
-    "guzzlehttp/guzzle": "^7.0",
-    "ankane/onnxruntime": "^0.2.0",
-    "rindow/rindow-math-matrix": "^1.2",
+    "ext-ffi": "*",
     "codewithkyrian/jinja-php": "^1.0",
-    "codewithkyrian/onnxruntime-downloader-plugin": "^1.1",
-    "symfony/console": "^6.4|^7.0",
+    "codewithkyrian/transformers-libsloader": "^1.0",
     "imagine/imagine": "^1.3",
-    "rokka/imagine-vips": "^0.31.0"
+    "rokka/imagine-vips": "^0.31.0",
+    "rindow/rindow-math-matrix": "^2.0",
+    "rindow/rindow-matlib-ffi": "^1.0",
+    "rindow/rindow-openblas-ffi": "^1.0",
+    "symfony/console": "^6.4|^7.0"
   },
   "require-dev": {
     "pestphp/pest": "^2.31",
     "symfony/var-dumper": "^7.0"
   },
-  "license": "MIT",
+  "license": "Apache-2.0",
   "autoload": {
     "psr-4": {
       "Codewithkyrian\\Transformers\\": "src/"
@@ -46,17 +47,21 @@
   "config": {
     "allow-plugins": {
       "pestphp/pest-plugin": true,
-      "codewithkyrian/onnxruntime-downloader-plugin": true
+      "codewithkyrian/transformers-libsloader": true
     }
   },
   "bin": [
     "bin/transformers"
   ],
   "scripts": {
     "test": "vendor/bin/pest",
-    "test:coverage": "XDEBUG_MODE=coverage ./vendor/bin/pest --coverage"
+    "test:coverage": "XDEBUG_MODE=coverage ./vendor/bin/pest --coverage",
+    "post-install-cmd": "Codewithkyrian\\Transformers\\Utils\\LibsChecker::check",
+    "post-update-cmd": "Codewithkyrian\\Transformers\\Utils\\LibsChecker::check"
   },
   "archive": {
-    "exclude": ["/docs"]
+    "exclude": [
+      "/docs"
+    ]
   }
 }

docs/configuration.md

@@ -37,6 +37,11 @@ The cache directory is where TransformersPHP stores the downloaded ONNX models.
 the `.transformers-cache/models` directory from the root of your project. Please ensure this directory is writable by
 your application.
 
+### `setLibsDir(?string $libsDir)`
+
+The libs directory is where TransformersPHP stores the shared libraries required for running the models. You typically
+don't need to change this setting unless you have a specific requirement to store the libraries in a different location.
+
 ### `setRemoteHost(string $remoteHost)`
 
 The remote host defines where TransformersPHP looks to download model files. The default host

docs/getting-started.md

@@ -22,14 +22,18 @@ You can install the library via Composer. This is the recommended way to install
 composer require codewithkyrian/transformers
 ```
 
-ONNX runtime will be installed automatically as well. For Windows users, it may take more time to install the ONNX
-library compared to Linux or macOS users (no shades 😅).
+All the shared libraries required by TransformersPHP will be installed automatically. If it fails for some reason, you
+can install them manually using the following command:
+
+```bash
+./vendor/bin/transformers install
+```
 
 > [!CAUTION]
-> The ONNX library is platform-specific, so it's important to run the composer require command on the target platform
-> where the code will be executed. In most cases, this will be your development machine or a server where you deploy
-> your
-> application, but if you're using a Docker container, run the `composer require` command inside that container.
+> The ONNX library is platform-specific, so it's important to run the `composer require`, or `transformers install`
+> command on the target platform where the code will be executed. In most cases, this will be your development machine
+> or a server where you deploy your application, but if you're using a Docker container, run the `composer require`
+> command inside that container.
 
 This command sets up everything you need to start using pre-trained ONNX models with TransformersPHP.
 

docs/utils/image.md

@@ -36,6 +36,14 @@ Transformers::setup()
     ->apply();
 ```
 
+If you're using the `Image` class directly, you can set the image driver using the `setImageDriver()` method.
+
+```php
+use Codewithkyrian\Transformers\Utils\Image;
+
+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
@@ -101,6 +109,23 @@ operations include:
   ```php
   $resizedImage = $image->resize(300, 200);
   ```
+  
+- ### `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.
+    
+    Parameters:
+        - `$width` (int) The target width of the thumbnail.
+        - `$height` (int) The target height of the thumbnail.
+        - `$resample` (int|Resample) The resampling method to use. Default is `Resample::BICUBIC`.
+    
+    Returns:
+        - An image object representing the thumbnail.
+    
+    Example:
+    ```php
+    $thumbnailImage = $image->thumbnail(100, 100);
+    ```
 
 - ### `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
@@ -268,7 +293,6 @@ can leverage this interoperability to perform advanced image processing tasks wi
 
 ```php
 use Codewithkyrian\Transformers\Utils\Image;
-use Codewithkyrian\Transformers\Utils\Tensor;
 
 // Read an image
 $image = Image::read('path/to/image.jpg');

docs/utils/tensor.md

@@ -39,6 +39,18 @@ Tensors have the following properties:
   each dimension. Strides are used to efficiently access elements in a tensor without the need for reshaping the
   underlying data.
 
+## Tensors in TransformersPHP
+
+The `Tensor` class in TransformersPHP provides a flexible and efficient way to work with tensors in PHP. By default, it
+uses a C-based buffer to store the tensor's data, which allows for fast element-wise operations and mathematical
+operations using OpenBLAS. The operations can further be accelerated if you installed OpenMP - allowing for parallel
+computation across multiple cores. TransformersPHP selects the best available backend for your system, depending on the
+installed libraries. OpenBLAS is already included in the package, so you don't need to install it separately. However,
+you can install OpenMP to enable parallel computation. Checkout the OpenMP installation guide for your operating system.
+
+There are few edge cases where OpenBLAS might not be installed properly. In such cases, TransformersPHP will fall back
+to using the PHP-based buffer, which is slower but still functional.
+
 ## Creating a Tensor
 
 You can create a tensor using the Tensor class constructor or by converting from a multidimensional array using the
@@ -47,28 +59,37 @@ fromArray method. Below are examples of how to create tensors:
 ### Using the Constructor
 
 ```php
-use Codewithkyrian\Transformers\Utils\Tensor;
-use Interop\Polite\Math\Matrix\NDArray;
+use Codewithkyrian\Transformers\Tensor\Tensor;
 
 $data = [1, 2, 3, 4, 5, 6];
 $shape = [2, 3];
-$dtype = NDArray::int16;
+$dtype = Tensor::int16;
 $tensor = new Tensor($data, $dtype, $shape); // If dtype is not provided, it defaults to NDArray::float32
 ```
 
 ### Using the fromArray Method
 
 ```php
-use Codewithkyrian\Transformers\Utils\Tensor;
+use Codewithkyrian\Transformers\Tensor\Tensor;
 
 $data = [[1, 2, 3], [4, 5, 6]];
 $tensor = Tensor::fromArray($data);
 ```
 
+### Using fill Method
+
+```php
+use Codewithkyrian\Transformers\Tensor\Tensor;
+
+$shape = [2, 3];
+$value = 5;
+$tensor = Tensor::fill($shape, $value); // Creates a tensor filled with the specified value
+```
+
 ### Using zeros and ones methods
 
 ```php
-use Codewithkyrian\Transformers\Utils\Tensor;
+use Codewithkyrian\Transformers\Tensor\Tensor;
 
 $shape = [2, 3];
 $tensor = Tensor::zeros($shape); // Creates a tensor of zeros with the specified shape
@@ -78,7 +99,7 @@ $tensor = Tensor::ones($shape); // Creates a tensor of ones with the specified s
 ### Using zerosLike and onesLike methods
 
 ```php
-use Codewithkyrian\Transformers\Utils\Tensor;
+use Codewithkyrian\Transformers\Tensor\Tensor;
 
 $data = [[1, 2, 3], [4, 5, 6]];
 $tensor = Tensor::fromArray($data);
@@ -114,7 +135,7 @@ and buffer.
   Returns the tensor's flat buffer as a regular PHP array.
 
 ```php
-use Codewithkyrian\Transformers\Utils\Tensor;
+use Codewithkyrian\Transformers\Tensor\Tensor;
 
 $data = [[1, 2, 3], [4, 5, 6]];
 
@@ -281,6 +302,27 @@ matrix multiplication, reshaping, transposing, etc. Below are some common tensor
 
   $softmax->toArray(); // [[0.09003057317038, 0.2447284710548, 0.66524095577482], [0.09003057317038, 0.2447284710548, 0.66524095577482]]
   ```
+  
+- ### `topk(int $k = null, bool $sorted = true)`
+  Returns the top k elements and their indices along the specified axis.
+
+  Parameters:
+    - `$k`: The number of top elements to return. If not provided, all elements are returned.
+    - `$sorted`: Whether to return the elements in sorted order.
+
+  Returns:
+    - A tuple containing two tensors: the top k elements and their indices.
+
+  Example:
+  ```php
+  $data = [[1, 2, 3], [4, 5, 6]];
+  $tensor = Tensor::fromArray($data);
+  
+  [$values, $indices] = $tensor->topk(2);
+  
+  $values->toArray(); // [[3, 2], [6, 5]]
+  $indices->toArray(); // [[2, 1], [2, 1]]
+  ```
 
 - ### `max(int $axis = null)`
   Returns the maximum values along the specified axis.
@@ -438,7 +480,7 @@ matrix multiplication, reshaping, transposing, etc. Below are some common tensor
     $result = $tensor->add($tensor2); // [[6, 8], [10, 12]]
     ```
 
-- ### `multiply(float|int $value)`
+- ### `multiply(Tensor|float|int $value)`
   Multiplies the tensor by the specified scalar value.
 
   Parameters:

examples/composer.json

@@ -1,29 +1,35 @@
 {
-    "name": "kyrian/examples",
-    "autoload": {
-        "psr-4": {
-            "Kyrian\\Examples\\": "/"
-        }
-    },
-    "authors": [
-        {
-            "name": "Kyrian Obikwelu",
-            "email": "[email protected]"
-        }
-    ],
-    "require": {
-        "php": "^8.1",
-        "symfony/console": "^7.0",
-        "codewithkyrian/transformers": "dev-change-init-process"
-    },
-    "minimum-stability": "dev",
-    "require-dev": {
-        "symfony/var-dumper": "^7.0"
-    },
-    "repositories": [
-        {
-            "type" : "path",
-            "url": "../"
-        }
-    ]
+  "name": "kyrian/examples",
+  "autoload": {
+    "psr-4": {
+      "Kyrian\\Examples\\": "/"
+    }
+  },
+  "authors": [
+    {
+      "name": "Kyrian Obikwelu",
+      "email": "[email protected]"
+    }
+  ],
+  "require": {
+    "php": "^8.1",
+    "symfony/console": "^7.0",
+    "codewithkyrian/transformers": "*"
+  },
+  "require-dev": {
+    "symfony/var-dumper": "^7.0"
+  },
+  "minimum-stability": "dev",
+  "repositories": [
+    {
+      "type": "path",
+      "url": "../"
+    }
+  ],
+  "config": {
+    "allow-plugins": {
+      "codewithkyrian/transformers-libraries-downloader": true,
+      "codewithkyrian/transformers-libsloader": true
+    }
+  }
 }

examples/image-test.php

@@ -2,14 +2,16 @@
 
 declare(strict_types=1);
 
+use Codewithkyrian\Transformers\Tensor\Tensor;
 use Codewithkyrian\Transformers\Transformers;
 use Codewithkyrian\Transformers\Utils\Image;
 use Codewithkyrian\Transformers\Utils\ImageDriver;
-use Codewithkyrian\Transformers\Utils\Tensor;
 use function Codewithkyrian\Transformers\Utils\timeUsage;
 
 require_once './bootstrap.php';
 
+ini_set('memory_limit', '2048M');
+
 function toTensorTest(ImageDriver $imageDriver): Tensor
 {
     timeUsage();
@@ -18,13 +20,13 @@ function toTensorTest(ImageDriver $imageDriver): Tensor
         ->setImageDriver($imageDriver)
         ->apply();
 
-    $image = Image::read('images/butterfly.jpg');
+    $image = Image::read('images/kyrian-cartoon.jpeg');
 
     $image->rgb();
 
     $tensor =  $image->toTensor();
 
-    dump("$imageDriver->name (toTensor) : ". timeUsage());
+    dump("$imageDriver->name (toTensor) : ". timeUsage(true));
 
     return $tensor;
 }
@@ -37,7 +39,7 @@ function fromTensorTest(ImageDriver $imageDriver, Tensor $tensor) : Image
 
     $image =  Image::fromTensor($tensor);
 
-    dump("$imageDriver->name (fromTensor) : ". timeUsage());
+    dump("$imageDriver->name (fromTensor) : ". timeUsage(true));
 
     return $image;
 }
@@ -54,3 +56,6 @@ function fromTensorTest(ImageDriver $imageDriver, Tensor $tensor) : Image
 $image = fromTensorTest(ImageDriver::IMAGICK, $tensor);
 $image = fromTensorTest(ImageDriver::GD, $tensor);
 $image = fromTensorTest(ImageDriver::VIPS, $tensor);
+
+// Save the image
+//$image->save('images/images/kyrian-cartoon-converted.jpeg');