pica - high quality image resize in browser
Resize images in browser without pixelation and reasonably fast. Autoselect the best of available technologies: webworkers, webassembly, createImageBitmap, pure JS.
demo
With pica you can:
- Reduce upload size for large images, saving upload time.
- Saves server resources on image processing.
- Generate thumbnails in browser.
- ...
Note. If you need File/Blob resize (from form's file input), consider use image-blob-reduce. It has additional machinery to process orientation, keep EXIF metadata and so on.
Migration from pica v6 to pica v7
MultiplyunsharpAmount
by 2, divide unsharpThreshold
by 2, example:-
pica@6
: pica.resize(a, b, { unsharpAmount: 80, unsharpThreshold: 2 })
- pica@7
: pica.resize(a, b, { unsharpAmount: 160, unsharpThreshold: 1 })
Prior to use
Here is a short list of problems you can face:- Loading image:
from the same domain or local files only. If you load images from
remote domain use proper `Access-Control-Allow-Origin` header.
- iOS has a memory limits for canvas elements, that may causeproblems in some cases, [more details](https://github.com/nodeca/pica/wiki/iOS-Memory-Limit).
- If your source data is jpeg image, it can be rotated. Consider use[image-blob-reduce](https://github.com/nodeca/image-blob-reduce).
- Saving image:
canvas.toBlob()
method.Use `pica.toBlob()`, it includes required shim.
- For jpeg source, it's a good idea to keep exif
data. Consider use[image-blob-reduce](https://github.com/nodeca/image-blob-reduce).
- Quality
Bitmaps have 8 bits per channel. That causes some quality loss,
because with gamma correction precision could be 12 bits per
channel.
- Precision loss will not be noticeable for ordinary images likekittens, selfies and so on. But we don't recommend this library
for resizing professional quality images.
Install
npm install pica
Use
const pica = require('pica')();
// Resize from Canvas/Image to another Canvas
pica.resize(from, to)
.then(result => console.log('resize done!'));
// Resize & convert to blob
pica.resize(from, to)
.then(result => pica.toBlob(result, 'image/jpeg', 0.90))
.then(blob => console.log('resized to canvas & created blob!'));
API
new Pica(config)
Create resizer instance with given config (optional):- tile - tile width/height. Images are processed by regions,
- features - list of features to use. Default is
[ 'js', 'wasm', 'ww' ]
. Can be [ 'js', 'wasm', 'cib', 'ww' ]
or [ 'all' ]
. Note, cib
is buggy in Chrome and not supports default
mks2013
filter.- idle - cache timeout, ms. Webworkers create is not fast.
- concurrency - max webworkers pool size. Default is autodetected
- createCanvas - function which returns a new canvas, used internally
by pica.
Default returns a [\<canvas\> element](https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API),
but this function could return an [OffscreenCanvas](https://developer.mozilla.org/en-US/docs/Web/API/OffscreenCanvas)
instead (to run pica in a Service Worker). Function signature: createCanvas(width: number, height: number): Canvas
Important! Latest browsers may support resize via createImageBitmap.
This feature is supported (cib
) but disabled by default and not recommended
for use. So:createImageBitmap()
is used for non-blocking image decode (when available,
- It's resize feature is blocked by default pica config. Enable it only on your
cib
will depend on your browser. Result
without cib
will be predictable and good..resize(from, to, options) -> Promise
Resize image from one canvas (or image) to another. Sizes are taken from source and destination objects.- from - source, can be
Canvas
,Image
orImageBitmap
. - to - destination canvas, its size is supposed to be non-zero.
- options - quality (number) or object:
.filter
instead) - 0..3.
- filter - filter name (Default - mks2013
). See resizefilterinfo.js for details. mks2013
does both resize and sharpening, it's optimal and not recommended to change.
- unsharpAmount - >=0. Default = 0
(off). Usuallyvalue between 100 to 200 is good. Note, `mks2013` filter already does
optimal sharpening.
- unsharpRadius - 0.5..2.0. By default it's not set. Radius of Gaussianblur. If it is less than 0.5, Unsharp Mask is off. Big values are clamped
to 2.0.
- unsharpThreshold - 0..255. Default = 0
. Threshold forapplying unsharp mask.
- cancelToken - Promise instance. If defined, currentoperation will be terminated on rejection.
Result is Promise, resolved with to
on success.(!) If you need to process multiple images, do it sequentially to optimize CPU & memory use. Pica already knows how to use multiple cores (if browser allows).
.toBlob(canvas, mimeType , quality) -> Promise
Convenience method, similar tocanvas.toBlob()
, but with
promise interface & polyfill for old browsers..resizeBuffer(options) -> Promise
Supplementary method, not recommended for direct use. Resize Uint8Array with raw RGBA bitmap (don't confuse with jpeg / png / ... binaries). It does not use tiles & webworkers. Left for special cases when you really need to process raw binary data (for example, if you decode jpeg files "manually").- options:
.filter
instead) - 0..3.
- filter - filter name (Default - mks2013
). See resizefilterinfo.js for details. mks2013
does both resize and sharpening, it's optimal and not recommended to change.
- unsharpAmount - >=0. Default = 0
(off). Usuallyvalue between 100 to 200 is good. Note, `mks2013` filter already does
optimal sharpening.
- unsharpRadius - 0.5..2.0. Radius of Gaussian blur.If it is less than 0.5, Unsharp Mask is off. Big values are
clamped to 2.0.
- unsharpThreshold - 0..255. Default = 0
. Thresholdfor applying unsharp mask.
- dest - Optional. Output buffer to write data,if you don't wish `pica` to create new one.
Result is Promise, resolved with resized rgba buffer.What is "quality"
Pica has presets to adjust speed/quality ratio. Simply usequality
option param:- 0 - Box filter, window 0.5px
- 1 - Hamming filter, window 1.0px
- 2 - Lanczos filter, window 2.0px
- 3 - Lanczos filter, window 3.0px
In real world you will never need to change default (max) quality. All this variations were implemented to better understand resize math :)
Unsharp mask
After scale down image can look a bit blured. It's good idea to sharpen it a bit. Pica has built-in "unsharp mask" filter (off by default). SetunsharpAmount
to positive number to activate the filter.Filter's parameters are similar to ones from Photoshop. We recommend to start with
unsharpAmount = 160
,
unsharpRadius = 0.6
and unsharpThreshold = 1
.
There is a correspondence between UnsharpMask parameters
in popular graphics software.Browser support
We didn't have time to test all possible combinations, but in general:- Top level API should work in all browsers,
- If you plan to use only pure math core,
Note. Though you can run this package on
node.js
, browsers
are the main target platform. On server side we recommend to use
sharp.References
You can find these links useful:- discussions on stackoverflow:
- chromium skia sources:
pica for enterprise
Available as part of the Tidelift Subscription.The maintainers of pica and thousands of other packages are working with Tidelift to deliver commercial support and maintenance for the open source packages you use to build your applications. Save time, reduce risk, and improve code health, while paying the maintainers of the exact packages you use. Learn more.