Skip to content

docs: update documentation on transform function #124

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 16 commits into from
Jul 8, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .github/workflows/nodejs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
15 changes: 8 additions & 7 deletions docs/Features/Geometry/Geometry.md
Original file line number Diff line number Diff line change
Expand Up @@ -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') | - | - |
53 changes: 53 additions & 0 deletions docs/Features/Geometry/Get Perspective Warp Matrix.md
Original file line number Diff line number Diff line change
@@ -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 | - |
17 changes: 13 additions & 4 deletions docs/Features/Geometry/Transform.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading