pica 9.0.1 → 10.0.0

package/README.md

@@ -14,22 +14,34 @@ pica - high quality image resize in browser
 With pica you can:
 
 - Reduce upload size for large images, saving upload time.
-- Saves server resources on image processing.
+- Save server resources on image processing.
 - Generate thumbnails in browser.
 - ...
 
-**Note. If you need File/Blob resize (from form's file input), consider use
+**Note. If you need File/Blob resize (from form's file input), consider using
 [image-blob-reduce](https://github.com/nodeca/image-blob-reduce).** It has
 additional machinery to process orientation, keep EXIF metadata and so on.
 
 
-Migration from pica v6 to pica v7
----------------------------------
+Migration from pica v9 to pica v10
+----------------------------------
 
-Multiply `unsharpAmount` 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 })`
+- If you targeted IE or other legacy browsers — drop them, only modern
+  browsers are supported now.
+- If you used `new` on the default export (`new (require('pica'))()` or
+  `import Pica from 'pica'; new Pica()`) — switch to either the factory call
+  `require('pica')()` / `pica()`, or to the named `Pica` class:
+  `import { Pica } from 'pica'; new Pica()`. The default export is now a
+  factory function only.
+- If you passed `createCanvas` in options — remove it. To override canvas
+  creation, expose a custom `OffscreenCanvas` on the global scope instead.
+- If you used the positional `quality` argument
+  (`pica.resize(from, to, 3)`) — switch to
+  `pica.resize(from, to, { filter: 'lanczos3' })`. The object form
+  `{ quality: 3 }` also works but is deprecated, prefer `filter`.
+- If you relied on multiple `Pica` instances sharing the same worker pool —
+  refactor to create a single instance and reuse it. Implicit sharing is
+  gone.
 
 
 Prior to use
@@ -40,15 +52,15 @@ Here is a short list of problems you can face:
 - Loading image:
   - Due to JS security restrictions, you can process images
     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 cause
+    a remote domain, use the proper `Access-Control-Allow-Origin` header.
+  - iOS has memory limits for canvas elements, which may cause
     problems 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
+  - If your source data is a jpeg image, it can be rotated. Consider using
     [image-blob-reduce](https://github.com/nodeca/image-blob-reduce).
 - Saving image:
-  - Some ancient browsers do not support `canvas.toBlob()` method.
-    Use `pica.toBlob()`, it includes required shim.
-  - For jpeg source, it's a good idea to keep `exif` data. Consider use
+  - Some ancient browsers do not support the `canvas.toBlob()` method.
+    Use `pica.toBlob()`, it includes the required shim.
+  - For jpeg source, it's a good idea to keep `exif` data. Consider using
     [image-blob-reduce](https://github.com/nodeca/image-blob-reduce).
 - Quality
   - JS canvas does not support access to info about gamma correction.
@@ -72,18 +84,40 @@ Use
 ---
 
 ```js
-const pica = require('pica')();
+// ESM (default factory)
+import pica from 'pica';
+const resizer = pica();
+
+// ESM (class)
+import { Pica } from 'pica';
+const resizer = new Pica();
+
+// CommonJS
+const resizer = require('pica')();
 
 // Resize from Canvas/Image to another Canvas
-pica.resize(from, to)
+resizer.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))
+resizer.resize(from, to)
+  .then(result => resizer.toBlob(result, 'image/jpeg', 0.90))
   .then(blob => console.log('resized to canvas & created blob!'));
 ```
 
+By default, the main entry (`pica`) inlines the webworker code. If you want
+the worker as a separate file (smaller main bundle, easier CSP), use the
+split build — `pica/dist/pica_main.mjs` together with
+`pica/dist/pica_worker.js`. In that case `workerURL` is required:
+
+```js
+import createPica from 'pica/dist/pica_main.mjs';
+
+const resizer = createPica({
+  workerURL: new URL('pica/dist/pica_worker.js', import.meta.url)
+});
+```
+
 
 API
 ---
@@ -96,18 +130,15 @@ Create resizer instance with given config (optional):
   to restrict peak memory use. Default 1024.
 - __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.
-  This option allow reuse webworkers effectively. Default 2000.
+  or `[ 'all' ]`. Note, `cib` is buggy in Chrome and does not support the
+  default `mks2013` filter.
+- __idle__ - cache timeout, ms. Creating webworkers is not fast,
+  so this option allows reusing them effectively. Default 2000.
+- __workerURL__ - URL for `pica_worker.js` when using split builds
+  (`pica_main.js` / `pica_main.mjs`) with `ww` enabled. Full builds
+  (`pica.js` / `pica.mjs`) include worker code and do not need this option.
 - __concurrency__ - max webworkers pool size. Default is autodetected
   CPU count, but not more than 4.
-- __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](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/createImageBitmap).
 This feature is supported (`cib`) but disabled by default and not recommended
@@ -115,9 +146,9 @@ for use. So:
 
 - `createImageBitmap()` is used for non-blocking image decode (when available,
   without downscale).
-- It's resize feature is blocked by default pica config. Enable it only on your
-  own risk. Result with enabled `cib` will depend on your browser. Result
-  without `cib` will be predictable and good.
+- Its resize feature is blocked in the default pica config. Enable it only at
+  your own risk. The result with `cib` enabled will depend on your browser.
+  The result without `cib` will be predictable and good.
 
 
 ### .resize(from, to, options) -> Promise
@@ -127,9 +158,9 @@ taken from source and destination objects.
 
 - __from__ - source, can be `Canvas`, `Image` or `ImageBitmap`.
 - __to__ - destination canvas, its size is supposed to be non-zero.
-- __options__ - quality (number) or object:
+- __options__ - object:
   - __quality__ (deprecated, use `.filter` instead) - 0..3.
-  - __filter__ - filter name (Default - `mks2013`). See [resize_filter_info.js](https://github.com/nodeca/pica/blob/master/lib/mm_resize/resize_filter_info.js) for details. `mks2013` does both resize and sharpening, it's optimal and not recommended to change.
+  - __filter__ - filter name (Default - `mks2013`). See [resize_filter_info.ts](https://github.com/nodeca/pica/blob/master/src/mm_resize/resize_filter_info.ts) for details. `mks2013` does both resize and sharpening, it's optimal and not recommended to change.
   - __unsharpAmount__ - >=0. Default = `0` (off). Usually
     value between 100 to 200 is good. Note, `mks2013` filter already does
     optimal sharpening.
@@ -145,7 +176,8 @@ 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).
+how to use multiple cores (if browser allows). Create a single
+`Pica` instance and reuse it across calls.
 
 
 ### .toBlob(canvas, mimeType [, quality]) -> Promise
@@ -169,7 +201,7 @@ binary data (for example, if you decode jpeg files "manually").
   - __toWidth__ - output width, >=0, in pixels.
   - __toHeight__ - output height, >=0, in pixels.
   - __quality__ (deprecated, use `.filter` instead) - 0..3.
-  - __filter__ - filter name (Default - `mks2013`). See [resize_filter_info.js](https://github.com/nodeca/pica/blob/master/lib/mm_resize/resize_filter_info.js) for details. `mks2013` does both resize and sharpening, it's optimal and not recommended to change.
+  - __filter__ - filter name (Default - `mks2013`). See [resize_filter_info.ts](https://github.com/nodeca/pica/blob/master/src/mm_resize/resize_filter_info.ts) for details. `mks2013` does both resize and sharpening, it's optimal and not recommended to change.
   - __unsharpAmount__ - >=0. Default = `0` (off). Usually
     value between 100 to 200 is good. Note, `mks2013` filter already does
     optimal sharpening.
@@ -179,34 +211,34 @@ binary data (for example, if you decode jpeg files "manually").
   - __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.
+    if you don't wish `pica` to create a 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:
+`quality` is a legacy preset still accepted for backwards compatibility,
+but deprecated — prefer the `filter` option. Mapping:
 
-- 0 - Box filter, window 0.5px
-- 1 - Hamming filter, window 1.0px
-- 2 - Lanczos filter, window 2.0px
-- 3 - Lanczos filter, window 3.0px
+- 0 - Box filter, window 0.5px (`filter: 'box'`)
+- 1 - Hamming filter, window 1.0px (`filter: 'hamming'`)
+- 2 - Lanczos filter, window 2.0px (`filter: 'lanczos2'`)
+- 3 - Lanczos filter, window 3.0px (`filter: 'lanczos3'`)
 
-In real world you will never need to change default (max)
-quality. All this variations were implemented to better
+In the real world you will never need to change the default (`mks2013`)
+filter. All these 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).
-Set `unsharpAmount` to positive number to activate the filter.
+After scale down, an image can look a bit blurred. It's a good idea to
+sharpen it a bit. Pica has a built-in "unsharp mask" filter (off by default).
+Set `unsharpAmount` to a positive number to activate the filter.
 
-Filter's parameters are similar to ones from Photoshop.
-We recommend to start with `unsharpAmount = 160`,
+Filter parameters are similar to ones from Photoshop.
+We recommend starting with `unsharpAmount = 160`,
 `unsharpRadius = 0.6` and `unsharpThreshold = 1`.
 There is [a correspondence between UnsharpMask parameters
 in popular graphics software](https://github.com/nodeca/pica/wiki/Unsharp-mask-params-in-popular-softare).
@@ -227,9 +259,20 @@ We didn't have time to test all possible combinations, but in general:
 - If you plan to use only pure math core,
   then [typed arrays support](http://caniuse.com/#feat=typedarrays) will be enough.
 
-__Note.__ Though you can run this package on `node.js`, browsers
-are the main target platform. On server side we recommend to use
-[sharp](https://github.com/lovell/sharp).
+__Note.__ Browsers are the main target platform. For Node.js we strongly
+recommend [sharp](https://github.com/lovell/sharp) — it is faster and
+produces better quality. If you really need pica in Node.js anyway, it can
+run in a limited mode (no WebWorkers) by exposing an external canvas library
+as the global `OffscreenCanvas`. This is not recommended.
+
+```js
+import { Canvas } from '@napi-rs/canvas'; // or any other canvas library
+import pica from 'pica';
+
+global.OffscreenCanvas = Canvas;
+
+const resizer = pica(); // WebWorkers will not be used
+```
 
 
 References

package/dist/pica.cjs.d.ts

@@ -0,0 +1,69 @@
+type MathResizeFilter = 'box' | 'hamming' | 'lanczos2' | 'lanczos3' | 'mks2013';
+
+type PicaFeaturesFlat = ('js' | 'wasm' | 'ww' | 'cib' | 'all')[];
+type Filter = MathResizeFilter;
+type CibResizeQuality = 0 | 1 | 2 | 3;
+type PicaCanvas = HTMLCanvasElement | OffscreenCanvas;
+type PicaSource = PicaCanvas | HTMLImageElement | ImageBitmap;
+type CreateCanvasPreference = {
+    preferOffscreen?: boolean;
+};
+interface PicaOptions {
+    tile?: number;
+    concurrency?: number;
+    features?: PicaFeaturesFlat;
+    idle?: number;
+    workerURL?: string | URL;
+}
+interface _ResizeOptionsCommon {
+    quality?: CibResizeQuality;
+    filter?: Filter;
+    unsharpAmount?: number;
+    unsharpRadius?: number;
+    unsharpThreshold?: number;
+}
+interface ResizeOptions extends _ResizeOptionsCommon {
+    cancelToken?: Promise<unknown>;
+}
+interface ResizeBufferOptions extends _ResizeOptionsCommon {
+    src: Uint8Array | Uint8ClampedArray;
+    width: number;
+    height: number;
+    toWidth: number;
+    toHeight: number;
+    dest?: Uint8Array;
+}
+
+declare class Pica {
+    private options;
+    private __limit;
+    private resize_features;
+    private __workersPool;
+    private capabilities;
+    private __requested_features;
+    private __mathlib;
+    private __initPromise?;
+    constructor(options?: PicaOptions);
+    init(): Promise<this>;
+    private __init;
+    createCanvas(width: number, height: number, preferOffscreen?: CreateCanvasPreference): PicaCanvas;
+    private __createWorkerSlot;
+    private __invokeWorker;
+    private __invokeResize;
+    private __extractTileData;
+    private __landTileData;
+    private __tileAndResize;
+    private __planStagesAndResize;
+    private __resizeViaCreateImageBitmap;
+    resize<TCanvas extends PicaCanvas>(from: PicaSource, to: TCanvas, options?: ResizeOptions): Promise<TCanvas>;
+    resizeBuffer(options: ResizeBufferOptions): Promise<Uint8Array>;
+    toBlob(canvas: HTMLCanvasElement | OffscreenCanvas, mimeType?: string, quality?: number): Promise<Blob>;
+    debug(..._args: unknown[]): void;
+}
+declare function pica(options?: PicaOptions): Pica;
+
+declare const picaWithClass: typeof pica & {
+    Pica: typeof Pica;
+};
+
+export { picaWithClass as default };

package/dist/pica.es.d.ts

@@ -0,0 +1,66 @@
+type MathResizeFilter = 'box' | 'hamming' | 'lanczos2' | 'lanczos3' | 'mks2013';
+
+type PicaFeaturesFlat = ('js' | 'wasm' | 'ww' | 'cib' | 'all')[];
+type Filter = MathResizeFilter;
+type CibResizeQuality = 0 | 1 | 2 | 3;
+type PicaCanvas = HTMLCanvasElement | OffscreenCanvas;
+type PicaSource = PicaCanvas | HTMLImageElement | ImageBitmap;
+type CreateCanvasPreference = {
+    preferOffscreen?: boolean;
+};
+interface PicaOptions {
+    tile?: number;
+    concurrency?: number;
+    features?: PicaFeaturesFlat;
+    idle?: number;
+    workerURL?: string | URL;
+}
+interface _ResizeOptionsCommon {
+    quality?: CibResizeQuality;
+    filter?: Filter;
+    unsharpAmount?: number;
+    unsharpRadius?: number;
+    unsharpThreshold?: number;
+}
+interface ResizeOptions extends _ResizeOptionsCommon {
+    cancelToken?: Promise<unknown>;
+}
+interface ResizeBufferOptions extends _ResizeOptionsCommon {
+    src: Uint8Array | Uint8ClampedArray;
+    width: number;
+    height: number;
+    toWidth: number;
+    toHeight: number;
+    dest?: Uint8Array;
+}
+
+declare class Pica {
+    private options;
+    private __limit;
+    private resize_features;
+    private __workersPool;
+    private capabilities;
+    private __requested_features;
+    private __mathlib;
+    private __initPromise?;
+    constructor(options?: PicaOptions);
+    init(): Promise<this>;
+    private __init;
+    createCanvas(width: number, height: number, preferOffscreen?: CreateCanvasPreference): PicaCanvas;
+    private __createWorkerSlot;
+    private __invokeWorker;
+    private __invokeResize;
+    private __extractTileData;
+    private __landTileData;
+    private __tileAndResize;
+    private __planStagesAndResize;
+    private __resizeViaCreateImageBitmap;
+    resize<TCanvas extends PicaCanvas>(from: PicaSource, to: TCanvas, options?: ResizeOptions): Promise<TCanvas>;
+    resizeBuffer(options: ResizeBufferOptions): Promise<Uint8Array>;
+    toBlob(canvas: HTMLCanvasElement | OffscreenCanvas, mimeType?: string, quality?: number): Promise<Blob>;
+    debug(..._args: unknown[]): void;
+}
+declare function pica(options?: PicaOptions): Pica;
+
+export { Pica, pica as default };
+export type { CibResizeQuality, Filter, PicaCanvas, PicaFeaturesFlat, PicaOptions, PicaSource, ResizeBufferOptions, ResizeOptions };