Lens Docs

Appearance

Migration from v1 guide ​

WARNING

Legacy browser support has been stopped in v2. See supported browsers list at Vite docs.

Import ​

If you have loaded Lens script by url, change file name from lens.js or lens.min.js to lens.umd.cjs.

lens.js is now ES module and can be used for native imports.

distort() function changes ​

image argument type changed ​

HTMLImageElement, ImageBitmap, Blob, Promise<ImageAdapter> and other types are not supported as input arguments. Only ImageAdapter implementations or underlying resource types (HTMLCanvasElement, OffscreenCanvas in browser, Jimp in Node.js) are supported.

ts
let adapterPromise: Promise<ImageAdapter>;
// ...
const result = await distort(
  adapterPromise, 
  await adapterPromise, 
  distortion,
  args
);
ts
import { Canvas } from "@alxcube/lens";
let imageBlob: Blob;
// ...
const result = await distort(
  imageBlob, 
  await Canvas.createFromBlob(imageBlob), 
  distortion,
  args
);
ts
import { Canvas } from "@alxcube/lens";
let image: HTMLImageElement;
// ...
const result = await distort(
  image, 
  Canvas.createFromImage(image), 
  distortion,
  args
);

resampler option changed ​

resampler option was renamed to preferredResampler and only supports "ewa" | "point" type. "ewa" is still used as default value.

ts
const result = await distort(image, distortion, args, {
  resampler: "point", 
  preferredResampler: "point", 
});

imageVirtualPixelMethod option renamed ​

Renamed to virtualPixelMethod

ts
const result = await distort(image, distortion, args, {
  imageVirtualPixelMethod: VirtualPixelMethod.TILE, 
  virtualPixelMethod: VirtualPixelMethod.TILE, 
});

imageInterpolationMethod option renamed ​

Renamed to interpolationMethod

ts
const result = await distort(image, distortion, args, {
  imageInterpolationMethod: InterpolationMethod.INTEGER, 
  interpolationMethod: InterpolationMethod.INTEGER, 
});

repage option behavior changed ​

In Lens v1.x when repage option was set to [number, number] (Point) value, it was ADDING given offset to image virtual viewport offset. This was incorrect behavior. In v2, given offset SETS image virtual viewport offset to given value.

ImageAdapter changes ​

Removed getVirtualPixelMethod() method ​

Method was removed and has no alternatives.

Removed setVirtualPixelMethod() method ​

Method was removed. virtualPixelMethod option can be used instead:

ts
import { distort, VirtualPixelMethod } from "@alxcube/lens";

/* ... */

const result = distort(image, distortion, args, {
  virtualPixelMethod: VirtualPixelMethod.TILE,
});

Removed getInterpolationMethod() method ​

Method was removed and has no alternatives.

Removed setInterpolationMethod() method ​

Method was removed. interpolationMethod option can be used instead:

ts
import { distort, InterpolationMethod } from "@alxcube/lens";

/* ... */

const result = distort(image, distortion, args, {
  interpolationMethod: InterpolationMethod.INTEGER,
});

Removed getInterpolatedPixelColor() method. ​

Color interpolation was reworked and decoupled from ImageAdapter.

getResource() method is made synchronous ​

Replace async usages to sync:

ts
const resource = await adapter.getResource(); 
const resource = adapter.getResource();
ts
adapter.getResource().then(handleResource); 
handleResource(adapter.getResource());

scale() method is made synchronous ​

If you have used this method, replace async usage to sync usage.

getBlank() method is made synchronous ​

If you have used this method (which is unlikely), replace async usage to sync usage.

commit() method is made synchronous ​

Method is made synchronous and now returns void. It is very unlikely that you have used this method, but worth noting.

Canvas class changes ​

All changes to the ImageAdapter interface apply to the Canvas class in particular.

All public methods, not related to ImageAdapter interface was removed.

The following are some alternatives:

Removed getCanvasElement() method ​

ts
import { toHTMLCanvasElement } from "@alxcube/lens"; 
/* ... */
document.body.appendChild(await adapter.getCanvasElement()); 
document.body.appendChild(toHTMLCanvasElement(adapter.getResource()));

Removed getOffscreenCanvas() method ​

You may write tiny helper function to be sure you have OffscreenCanvas:

ts
function toOffscreen(
  canvas: HTMLCanvasElement | OffscreenCanvas
): OffscreenCanvas {
  if (canvas instanceof OffscreenCanvas) {
    return canvas;
  }
  const offscreen = new OffscreenCanvas(canvas.width, canvas.height);
  offscreen.getContext("2d").drawImage(canvas, 0, 0);
  return offscreen;
}

...and use it with getResource() method:

ts
const offscreen = await adapter.getOffscreenCanvas(); 
const offscreen = toOffscreen(adapter.getResource());

Removed getImageElement method ​

ts
import { preloadHtmlImage, toHTMLCanvasElement } from "@alxcube.lens"; 

const image = await adapter.getImageElement(); 
const image = await preloadHtmlImage( 
  toHTMLCanvasElement(adapter.getResource()).toDataUrl() 
);

Removed getBlob() method ​

You can use toOffscreen() function from above example:

ts
const blob = await adapter.getBlob(); 
const blob = await toOffscreen(adapter.getResource()).convertToBlob();