pica - high quality image resize in browser

pica is one more experiment with high speed javascript, from authors of paco. It does high quality image resize in browser as fast as possible.

demo

When you resize images using modern browsers' canvas low quality interpolation algorythms are used by default. That's why we wrote pica.

It's not as fast as canvas, but still reasonably fast. With Lanczos filter and window=3 huge image resize (5000x3000px) takes ~0.5s on desktop and ~2s on mobile.
In modern browsers pica automatically uses Webworkers, to avoid interface freeze and use multiple CPU cores in parallel.

Why it's useful:

reduces upload size for large images to pre-process in browser, saving time and bandwidth
saves server resources on image processing
HiDPI image technique for responsive and retina
use single image for both thumbnail and detailed view

Prior to use

Pica is a low level library that does math with minimal wrappers. If you need to resize binary image, you should take care to load it into canvas first (and to save it back to blob). Here is a short list of problems you can face:

Loading image:
- Due to JS security restrictions, you can load to canvas only images from same domain or local files. If you load images from remote domain use proper Access-Control-Allow-Origin header.
- iOS has resource limits for canvas size & image size. Look here for details and possible solutions.
- If you plan to show images on screen after load, you must parse exif header to get proper orientation. Images can be rotated.
Saving image:
- Some ancient browsers do not support .toBlob() method, use https://github.com/blueimp/JavaScript-Canvas-to-Blob if needed.
- It's a good idea to keep exif data, to avoid palette & rotation info loss. The most simple way is to cut original header and glue it to resized result. Look here for examples.
Quality
- JS canvas does not support access to info about gamma correction. 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 like kittens, selfies and so on. But we don't recommend this library for resizing professional quality images.

Install

node.js (to develop, build via browserify and so on):

npm install pica

bower:

bower install pica

API

.resizeCanvas(from, to, options, callback) -> task_id

Resize image from one canvas (or image) to another. Sizes are taken from source and destination objects. Return task ID to be able terminate it early.

from - source canvas or image.
to - destination canvas.
options - quality (number) or object:
- quality - 0..3. Default = 3 (lanczos, win=3).
- alpha - use alpha channel. Default = false.
- unsharpAmount - >=0, in percents. Default = 0 (off). Usually between 50 to 100 is good.
- 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. Threshold for applying unsharp mask.
callback(err) - function to call after resize complete:
- err - error if happened

(!) 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).

.terminate(task_id)

Terminate resizing task by id, returned from resize function.

.resizeBuffer(options, callback)

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:
- src - Uint8Array with source data.
- width - src image width.
- height - src image height.
- toWidth - output width.
- toHeigh - output height.
- quality - 0..3. Default = 3 (lanczos, win=3).
- alpha - use alpha channel. Default = false.
- unsharpAmount - >=0, in percents. Default = 0 (off). Usually between 50 to 100 is good.
- 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. Threshold for applying unsharp mask.
- dest - Optional. Output buffer to write data (callback will return result buffer anyway).
callback(err, output) - function to call after resize complete:
- err - error if happened.
- output - Uint8Array with resized RGBA image data.

.WW - true/false

true if webworkers are supported. You can use it for browser capabilities detection. Also, you can set it to false for debuging.

.WEBGL - true/false (experimental)

false by default. Pica can use WebGL when available, if you enable this feature. But current implementation is not complete and not recommended for production. Result is noisy and code can crash.

Though, you can enable it to investigate technology, test on different devices and provide feedback.

pica.WEBGL = true;
pica.debug = console.log.bind(console);

What is quality

Pica has presets, to adjust speed/quality ratio. Simply use quality 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

Pica has built-in unsharp mask. Set unsharpAmount to positive number to activate the filter.

The parameters of it are similar to ones from Photoshop. We recommend to start with unsharpAmount = 80, unsharpRadius = 0.6, unsharpThreshold = 2. 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, supporting canvas and typed arrays.
Webworkers support is not required, but they will be used if available.
If you plan to use only pure math core, then typed arrays support will be enougth.

Note. Though you can run this package on node.js, browsers are the main target platform. On server side we recommend to use sharp for better speed.

References

You can find these links useful:

discussions on stackoverflow: 1, 2, 3.
chromium skia sources: image_operations.cc, convolver.cc.

Authors

Vitaly Puzrin @puzrin
Alexander Rodin @a-rodin
@d08ble
Loïc Faure-Lacroix @llacroix

Licence

MIT

d08ble / pica