docs: update documentation on transform function

Author: EscapedGibbon

.github/workflows/nodejs.yml

@@ -10,7 +10,9 @@ jobs:
   nodejs:
     uses: zakodium/workflows/.github/workflows/nodejs.yml@nodejs-v1
     with:
+      node-version: 18.x
       lint-check-types: true
       npm-test-command: npm run build
       node-version-matrix: '[18]'
       upload-coverage: false
+      disable-test-package: true

docs/Features/Geometry/Geometry.md

@@ -8,10 +8,11 @@ Geometric operations in image processing involve transforming the spatial coordi
 
 ### Methods
 
-| Can be applied on                                                                                        | Images  | Masks    |
-| -------------------------------------------------------------------------------------------------------- | ------- | -------- |
-| [Flip(`flip`)](./Flip.md 'internal link on flip')                                                        | ✅ | ❌ |
-| [Resize(`resize`)](./Resize.md 'internal link on resize')                                                | ✅ | ❌ |
-| [Rotate(`rotate`)](./Rotate.md 'internal link on rotate')                                                | ✅ | ❌ |
-| [Transform(`transform`)](./Transform.md 'internal link on transform')                                    | ✅ | ❌ |
-| [Transform and rotate(`transformRotate`)](./Transform%20and%20Rotate 'internal link on transformRotate') | ✅ | ❌ |
+| Can be applied on                                                                                                                 | Images  | Masks    |
+| --------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
+| [Flip(`flip`)](./Flip.md 'internal link on flip')                                                                                 | ✅ | ❌ |
+| [Resize(`resize`)](./Resize.md 'internal link on resize')                                                                         | ✅ | ❌ |
+| [Rotate(`rotate`)](./Rotate.md 'internal link on rotate')                                                                         | ✅ | ❌ |
+| [Transform(`transform`)](./Transform.md 'internal link on transform')                                                             | ✅ | ❌ |
+| [Transform and rotate(`transformRotate`)](./Transform%20and%20Rotate 'internal link on transformRotate')                          | ✅ | ❌ |
+| [Get perspective warp matrix(`getPerspectiveWarp`)](./Get%20Perspective%20Warp%20Matrix.md 'internal link on getPerspectiveWarp') | -       | -        |

docs/Features/Geometry/Get Perspective Warp Matrix.md

@@ -0,0 +1,53 @@
+---
+sidebar_position: 41
+---
+
+# Get perspective warp matrix
+
+_Returns a perspective transformation matrix from source points that transforms a quadrilateral._
+
+[Options and parameters of `getPerspectiveWarp` function](https://image-js.github.io/image-js-typescript/functions/getPerspectiveWarp.html)
+
+`getPerspectiveWarp` function takes 4 corner points (source quadrilateral) and then calculates the 3×3 perspective transformation matrix that allows removing [perspective distortion](https://en.wikipedia.org/wiki/Perspective_distortion).
+The function also returns width and height of the new image.
+If they were put as option's parameters it just returns indicated width and height, otherwise it calculates new width and height from given source points.
+
+### Basic use case
+
+```ts
+const image = readSync('path/to/file.png');
+// Define source corners (original image points) and destination image width and height.
+//  In this case they correspond to credit card's corner points.
+const sourcePoints = [
+  [
+    { column: 55, row: 140 },
+    { column: 680, row: 38 },
+    { column: 840, row: 340 },
+    { column: 145, row: 460 },
+  ],
+  { width: 725, height: 425 },
+];
+
+// Get transformation matrix using 4 points and `getPerspectiveWarp` function.
+const projectionMatrix = getPerspectiveWarp(sourcePoints);
+const projectedImage = image.transform(matrix.matrix, {
+  width: matrix.width,
+  height: matrix.height,
+  inverse: true,
+});
+```
+
+![Basic use case of perspectiveWarp](./images/cardPerspective.png)
+
+### Parameters and default values
+
+- `pts`
+
+- `options`
+
+#### Options
+
+| Property                                                                                                    | Required | Default value |
+| ----------------------------------------------------------------------------------------------------------- | -------- | ------------- |
+| [`width`](https://image-js.github.io/image-js-typescript/interfaces/GetPerspectiveWarpOptions.html#width)   | no       | -             |
+| [`height`](https://image-js.github.io/image-js-typescript/interfaces/GetPerspectiveWarpOptions.html#height) | no       | -             |

docs/Features/Geometry/Transform.md

@@ -10,16 +10,25 @@ _Applies linear transformations to an image, such as scaling, rotation, skewing,
 
 [🖼️ Image options and parameters of `transform` method](https://image-js.github.io/image-js-typescript/classes/Image.html#transform 'github.io link')
 
-`transform` method uses transformation matrix to rotate, translate, and/or scale the image. User needs to pass on the matrix that will be applied to the image. Matrix must have 2 rows and 3 columns:
+`transform` method uses transformation matrix to rotate, translate, and/or scale the image.
+User needs to pass on the matrix that will be applied to the image. Matrix must have either 2 rows and 3 columns or 3 rows and 3 columns:
 
 $$
 \begin{bmatrix}
-1 & 2 & 3\\
-a & b & c
+a & b & c\\
+d & e & f \\
+g & h & i
 \end{bmatrix}
 $$
 
-Where the first two columns are responsible for image [rotation](https://en.wikipedia.org/wiki/Rotation 'wikipedia link on rotation') and [shear](https://en.wikipedia.org/wiki/Shear_mapping 'wikipedia link on image shearing'), while last column is responsible for image [translation](<https://en.wikipedia.org/wiki/Translation_(geometry)#:~:text=In%20Euclidean%20geometry%2C%20a%20translation,origin%20of%20the%20coordinate%20system> 'wikipedia link on translation').
+If 2x3 matrix is passed, the algorithm will consider it as [affine transformation](https://en.wikipedia.org/wiki/Affine_transformation) so last row will be set as `[0,0,1]`;
+
+- the first `a` and `e` are responsible for image scaling
+- `b` and `d` are responsible for [shear](https://en.wikipedia.org/wiki/Shear_mapping 'wikipedia link on image shearing'). Combination of these 4 variables allows [rotating](https://en.wikipedia.org/wiki/Rotations_and_reflections_in_two_dimensions 'wikipedia link on rotation'). `c` and `f` are responsible for image [translation](<https://en.wikipedia.org/wiki/Translation_(geometry)#:~:text=In%20Euclidean%20geometry%2C%20a%20translation,origin%20of%20the%20coordinate%20system> 'wikipedia link on translation').
+- `g` and `h` are used for an operation called projection. It allows changing image perspective.
+- `i` is a normalization factor. It acts like a "scaling factor" for the entire coordinate system. Think of it as a zoom lens setting.
+
+For more information take a look at the tutorial about [image transformations](../../Tutorials/Applying%20transform%20function%20on%20images.md)
 
 :::caution
 Matrix cannot be singular. Otherwise it cannot be inverted. Click [here](https://en.wikipedia.org/wiki/Invertible_matrix 'wikipedia link on invertible matrices') to learn more.