Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mat-sz/imtool
🖼️ Client-side canvas-based image manipulation library.
https://github.com/mat-sz/imtool
image-manipulation image-processing javascript javascript-library library thumbnail-generator thumbnails typescript typescript-library
Last synced: 2 months ago
JSON representation
🖼️ Client-side canvas-based image manipulation library.
- Host: GitHub
- URL: https://github.com/mat-sz/imtool
- Owner: mat-sz
- License: bsd-3-clause-clear
- Created: 2020-02-23T22:29:00.000Z (almost 5 years ago)
- Default Branch: master
- Last Pushed: 2023-09-06T16:35:32.000Z (over 1 year ago)
- Last Synced: 2024-08-02T13:35:51.129Z (6 months ago)
- Topics: image-manipulation, image-processing, javascript, javascript-library, library, thumbnail-generator, thumbnails, typescript, typescript-library
- Language: TypeScript
- Homepage: https://demo.mat.dev/imtool/
- Size: 364 KB
- Stars: 43
- Watchers: 4
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
🖼️🔧 imtool • demo
Canvas-based TypeScript image manipulation library.
Quickstart:
```sh
npm install imtool
# or:
yarn add imtool
```
## Table of contents
1. [Why?](#why)
2. [Examples](#examples)
3. [Usage](#usage)
- [Import](#import)
- [Image manipulation](#image-manipulation)
- [Export options](#export-options)
- [Export](#export)
- [Properties](#properties)
## Why?
Client-side image manipulation:
- allows for end to end encryption of thumbnails along with the original images,
- allows for easy usage within Electron without relying on external tools like Imagemagick,
- allows for cropping and compressing the image on the client side without quality loss.
## Examples
### Demo
The source code of the [live demo](https://demo.mat.dev/imtool/) is available here: https://github.com/mat-sz/imtool-demo
### Load an image, create a thumbnail and export it as data URL
```js
import { fromImage } from 'imtool';
async function example() {
const tool = await fromImage('./image.png');
return await tool.thumbnail(250).toDataURL();
}
```
### Load a screenshot, crop a part of it and export it as a Blob
```js
import { fromScreen } from 'imtool';
async function example() {
const tool = await fromScreen();
return await tool.crop(50, 50, 200, 200).toBlob();
}
```
### Load a webcam capture, crop a part of it, create a thumbnail and export as data URL
```js
import { fromWebcam } from 'imtool';
async function example() {
const tool = await fromWebcam();
return await tool.crop(50, 50, 500, 500).thumbnail(250).toDataURL();
}
```
## Usage
### Import
`imtool` provides 6 easy to use `from*` functions, **all of the functions return a Promise**:
#### fromImage(image: string | Blob | File | HTMLImageElement)
Creates an instance of `ImTool` from an URL, Blob, File or HTMLImageElement.
**In case of URL and HTMLImageElement being used the image must be accessible to the current origin, by either being from the same origin or by being from an origin specified in `Access-Control-Allow-Origin` header on the response from the desired URL.**
#### fromVideo(video: HTMLVideoElement)
Creates an instance of `ImTool` from an HTMLVideoElement.
**The video must be accessible to the current origin, by either being from the same origin or by being from an origin specified in `Access-Control-Allow-Origin` header on the response from the desired URL.**
#### fromCanvas(video: HTMLCanvasElement)
Creates an instance of `ImTool` from an HTMLCanvasElement.
**The canvas must not be [tainted](https://developer.mozilla.org/en-US/docs/Web/HTML/CORS_enabled_image#Security_and_tainted_canvases).**
#### fromWebcam()
Asks the user for the permission to access their webcam, captures the image, and creates an instance of `ImTool`.
**Must be called directly from an user action, for example: a button press.**
#### fromScreen()
Asks the user for the permission to access their desktop capture, captures the image, and creates an instance of `ImTool`.
**Must be called directly from an user action, for example: a button press. May be not supported on some browsers, like Safari (including all internet browsers on iOS), Internet Explorer and older versions of other browsers.**
#### fromMediaStream(stream: MediaStream)
Creates an instance of `ImTool` from MediaStream (must contain at least one video track).
### Image manipulation
All functions return the same instance of `ImTool`, allowing for easy chaining.
#### thumbnail(maxSize: number, cover: boolean = false)
Creates a thumbnail. The code for this comes from my older project, [nailit](https://github.com/mat-sz/nailit).
- `maxSize` specifies the maximum size (either width or height) of the resulting image.
- `cover` when set to true will cause the resulting image to be a square and the input image will be centered with its smallest dimension becoming as large as maxDimension and the overflow being cut off.
#### scale(width: number, height: number)
Scales the image down/up to specified `width` and `height`.
#### crop(x: number, y: number, width: number, height: number)
Moves the input image from (`x`, `y`) to (0, 0) and crops it down to the specified `width` and `height`.
#### flipV()
Flips the image vertically.
#### flipH()
Flips the image horizontally.
#### rotate(rad: number)
Rotates the input image by `rad` radians relative to the center of the image. The output image size will be increased to fit the entire rotated image.
#### rotateDeg(degrees: number)
Rotates the input image by `degrees` degrees relative to the center of the image. The output image size will be increased to fit the entire rotated image.
#### background(color: string)
Set the background color of the current image.
### Export options
#### type(type: string)
Sets the output mimetype (most commmonly supported ones are `image/jpeg` and `image/png`).
#### quality(quality: number)
Output quality (for lossy compression), a number between 0.0 and 1.0.
### Export
#### toBlob(): Promise\
Outputs a Blob.
#### toBlobURL(): Promise\
Outputs a blob URL.
#### toDataURL(): Promise\
Outputs a data URL.
#### toCanvas(): Promise\
Outputs a ``.
#### toImage(): Promise\
Outputs an `![]()
`.
#### toDownload(name: string): Promise
Causes the resulting file to be downloaded by the browser with a given name.
#### toFile(name: string): Promise\
Outputs a `File` that can be easily sent with `FormData`.
### Properties
**All of the following are readonly unless noted otherwise.**
#### width: number
Width of the output image.
#### height: number
Height of the output image.
#### originalWidth: number
Width of the input image.
#### originalHeight: number
Height of the input image.