arodin/pica-toolchain repository overview

⁠pica - high quality image resize in browser

demo⁠

With pica you can:

• Reduce upload size for large images, saving upload time.
• Saves server resources on image processing.
• Generate thumbnails in browser.
• ...

⁠Prior to use

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 should parse exif header to get proper orientation. Images can be rotated.
• Saving image:
  • Some ancient browsers do not support canvas.toBlob() method. Use pica.toBlob(), it includes required shim.
  • It's a good idea to keep exif data, to avoid 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

Attention!. Compiled files are in /dist folder! If you wish to load module in node.js style as require('pica') - your project MUST be compiled with Broserify to properly use Web Workers. In other case - use require('pica/dist/pica').

⁠API

⁠new Pica(config)

Create resizer instance with given config.

const pica = require('pica')({
  tile: 1024,           // Tile width/height. Images are processed
                        // by regions, to restrict peak memory use.

  features: [ 'all' ],  // Mostly for testing, restricts
                        // available features. Can be:
                        // [ 'js', 'wasm', 'cib', 'ww' ] or [ 'all' ]

  idle: 2000,           // Cache timeout, ms. Webworkers create
                        // is not fast. This option allow reuse
                        // webworkers effectively.

  concurrency: 4        // Max webworkers pool size. Default is
                        // autodetected CPU count, but not more than 4.
});


// Resize from Canvas/Image to another Canvas
pica.resize(from, to, {
  unsharpAmount: 80,
  unsharpRadius: 0.6,
  unsharpThreshold: 2
})
.then(result => console.log('resize done!'));


// Resize & convert to blob
pica.resize(from, to)
  .then(result => pica.toBlob(result, 'image/jpeg', 90))
  .then(blob => console.log('resized to canvas & created blob!'));

⁠.resize(from, to, options) -> Promise

Resize image from one canvas (or image) to another. Sizes are taken from source and destination objects.

• 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.
  • cancelToken - Promise instance. If defined, current operation will be termitated 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 to canvas.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:
  • 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, 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 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

Ifter 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). Set unsharpAmount to positive number to activate the filter.

Filter's parameters are similar to ones from Photoshop. We recommend to start with unsharpAmount = 80, unsharpRadius = 0.6 and 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⁠, WebAssembly⁠ and createImageBitmap⁠ are 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⁠.

⁠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⁠
• Loïc Faure-Lacroix @llacroix⁠

⁠Licence

MIT⁠