Lens Docs

Appearance

API: Image Distortion ​

distort() ​

  • Type:
ts
declare function distort<ResourceType>(
  image: ResourceType | ImageAdapter<ResourceType>,
  distortion: Distortion,
  args: number[],
  options?: DistortionServiceOptions
): Promise<DistortionResult<ResourceType>>;

declare function distort<ResourceType>(
  image: ResourceType | ImageAdapter<ResourceType>,
  reversePixelMapper: ReversePixelMapper,
  options?: DistortionServiceOptions
): Promise<DistortionResult<ResourceType>>;
  • Params (overload 1):
    • image: ResourceType | ImageAdapter<ResourceType> - Source image
    • distortion: Distortion - Distortion enum value (or corresponding string).
    • args: number[] - Distortion arguments.
    • options?: DistortionServiceOptions - options
  • Params (overload 2):
    • image: ResourceType | ImageAdapter<ResourceType> - Source image
    • reversePixelMapper: ReversePixelMapper - ReversePixelMapper interface implementation.
    • options?: DistortionServiceOptions
  • Returns: Promise<DistortionResult<ResourceType>>

Most common use is overload 1. It takes source image, distortion name, distortion arguments and options and returns Promise that will be resolved with DistortionResult interface, containing distorted image and some additional data.

Source image can be either supported image resource, or ImageAdapter interface implementing object.

Distortion name is one of Distortion enum values (or corresponding string). And args is distortion arguments array, which is array of numbers.

Instead of distortion name and arguments, overload 2 can be used, which accepts object implementing ReversePixelMapper interface as second argument. You may get it from DistortionResult.distortion, got earlier, or event create by yourself, implementing custom image distortion.

The last argument is options object, which will be described below.

DistortionResult interface ​

ts
interface DistortionResult<ResourceType> {
  image: ImageAdapter<ResourceType>;
  distortion: ReversePixelMapper;
  startTimestamp: number;
  endTimestamp: number;
  duration: number;
  weightLookupTable?: number[];
}

image ​

  • Type: ImageInterface<ResourceType>

ImageAdatpter of distorted image. It contains underlying image resource and virtual viewport.

distortion ​

  • Type: ReversePixelMapper

Instance of ReversePixelMapper interface, used for current distortion. It is concrete ReversePixelMapper instance and may be used for inspecting exposed distortion function coefficients or for applying similar distortion, using overload 2 of distort() function.

startTimestamp ​

  • Type: number

Timestamp of distortion process start.

endTimestamp ​

  • Type: number

Timestamp of distortion process finish.

duration ​

  • Type: number

Distortion process duration.

weightLookupTable ​

  • Type: number[]

Array of 1024 numbers, which are color weights, calculated by ResampleFilter, used in EWA resampling. This property is defined only if EWA resampling was used.

DistortionServiceOptions type ​

ts
type DistortionServiceOptions = {
  viewport?: "bestFit" | boolean | ViewportLiteral;
  virtualPixelMethod?: VirtualPixelMethod;
  interpolationMethod?: InterpolationMethod;
  imageBackgroundColor?: Color | string;
  imageViewportOffset?: Point;
  outputScaling?: number;
  preferredResampler?: "point" | "ewa";
  filter?: FilterName | ResampleFilterPreset | ResampleFilter;
  filterBlur?: number;
  filterWindowSupport?: number;
  matteColor?: Color | string;
  repage?: boolean | Point | ViewportLiteral;
  abortSignal?: AbortSignal;
  asyncTimeout?: number;
};

viewport ​

  • Type: "bestFit" | boolean | ViewportLiteral
  • Default value: undefined

Controls output image viewport. When set to true or "bestFit", lens will calculate best-fit viewport for distortion result to contain whole distorted image with all paddings trimmed. If selected distortion doesn't support best-fit viewport calculation, source image viewport will be used for output image.

When set to viewport literal, provided viewport will be used as output image viewport.

When omitted, uses source image viewport as output viewport, unless selected distortion forces best-fit viewport.

INFO

Custom viewport, provided using ViewportLiteral has the highest priority, and always will be used as output image viewport, even if distortion forces best-fit.

virtualPixelMethod ​

  • Type: VirtualPixelMethod
  • Default value: VirtualPixelMethod.TRANSPARENT

Sets image virtual pixel method. Should be one of VirtualPixelMethod values.

interpolationMethod ​

  • Type: InterpolationMethod
  • Default value: InterpolationMethod.AVERAGE

Sets image color interpolation method. Should be one of InterpolationMethod values.

imageBackgroundColor ​

  • Type: Color | string
  • Default value: [0, 0, 0, 0]

Sets image background color. Can be either Color, or string.

INFO

Lens supports color options in following formats:

  • HEX ("#ffffff", "#fff")
  • HEXA ("#ffffffff")
  • RGB ("rgb(255, 255, 255)", "rgb(100%, 100%, 100%)")
  • RGBA ("rgba(255, 255, 255, 0.5)", "rgba(100%, 100%, 100%, 1)")
  • Array: [255, 255, 255, 255]
  • Special string constant for transparent color: "transparent"

imageViewportOffset ​

  • Type: Point
  • Default value: undefined

Adds specified offset to source image viewport before distortion. In some cases you may want image viewport to have some specific offset before distortion. You can create instance of ImageAdapter and set it on it:

ts
import { Canvas, distort } from "@alxcube/lens";
const offsetX = 100;
const offsetY = 200;
const image: OffscreenCanvas = drawImageToDistort();
const adapter = new Canvas(image);
adapter.getViewport().offset(offsetX, offsetY);
const result = await distort(adapter, distortion, args);

Instead of this, if you are not explicitly creating adapter, you may use this option:

ts
import { distort } from "@alxcube/lens";
const offsetX = 100;
const offsetY = 200;
const image: OffscreenCanvas = drawImageToDistort();
const result = await distort(image, distortion, args, {
  imageViewportOffset: [offsetX, offsetY],
});

outputScaling ​

  • Type: number
  • Default value: 1

This is actually, supersampling factor. It won't change output image size, but instead, internally, will make output image canvas outputScaling times larger than normal result and after distortion is processed, this output image will be resized to 1 / outputScaling scale (normal size).

preferredResampler ​

  • Type: "point" | "ewa"
  • Default value: "ewa"

When set to "point", turns off EWA resampling, which makes distortion process much faster, but produces aliasing artifacts. Otherwise, uses EWA resampling.

filter ​

  • Type: "FilterName | ResampleFilterPreset | ResampleFilter"
  • Default value: "Robidoux"

Specifies resample filter, used in EWA resampling. Can be one of built-in filter preset names or custom filter settings object.

filterBlur ​

  • Type: number
  • Default value: undefined

Overrides blur setting of used filter preset, which is 1 by default.

filterWindowSupport ​

  • Type: number
  • Default value: undefined

Overrides windowSupport setting, which normally equals support.

matteColor ​

  • Type: Color | string
  • Default value: [0, 0, 0, 0]

Sets matte color. Can be either Color, or string.

INFO

Lens supports color options in following formats:

  • HEX ("#ffffff", "#fff")
  • HEXA ("#ffffffff")
  • RGB ("rgb(255, 255, 255)", "rgb(100%, 100%, 100%)")
  • RGBA ("rgba(255, 255, 255, 0.5)", "rgba(100%, 100%, 100%, 1)")
  • Array: [255, 255, 255, 255]
  • Special string constant for transparent color: "transparent"

repage ​

  • Type: boolean | Point | ViewportLiteral
  • Default value: undefined

Changes output image viewport after distortion. When set to ViewportLiteral, sets distorted image viewport to such as given. When set to Point value, sets image viewport offset to corresponding point coordinates. When set to true, resets viewport offset to (0, 0).

abortSignal ​

  • Type: AbortSignal
  • Default value: undefined

Allows to pass AbortSignal for ability to abort distortion later.

Examples:

Abort after timeout

ts
const result = await distort(image, name, args, {
  abortSignal: AbortSignal.timeout(2000),
});

Abort manually

ts
const abortController = new AbortController();
document.querySelector("#abort-button").onclick = () => abortController.abort();
const result = await distort(image, name, args, {
  abortSignal: abortController.signal,
});

asyncTimeout ​

  • Type: number
  • Default value: 50

Specifies timout of distortion processing, before further processing will be delayed to the next event loop iteration.

distortUnwrap() ​

  • Type:
ts
declare function distortUnwrap<ResourceType>(
  image: ResourceType | ImageAdapter<ResourceType>,
  distortion: Distortion,
  args: number[],
  options?: DistortionServiceOptions
): Promise<ResourceType>;

declare function distortUnwrap<ResourceType>(
  image: ResourceType | ImageAdapter<ResourceType>,
  reversePixelMapper: ReversePixelMapper,
  options?: DistortionServiceOptions
): Promise<ResourceType>;
  • Params (overload 1):
    • image: ResourceType | ImageAdapter<ResourceType> - Source image
    • distortion: Distortion - Distortion enum value (or corresponding string).
    • args: number[] - Distortion arguments.
    • options?: DistortionServiceOptions - options
  • Params (overload 2):
    • image: ResourceType | ImageAdapter<ResourceType> - Source image
    • reversePixelMapper: ReversePixelMapper - ReversePixelMapper interface implementation.
    • options?: DistortionServiceOptions
  • Returns: Promise<ResourceType>

This function is similar to distort() and accepts same arguments. The only difference is that it returns Promise which resolves to unwrapped underlying image resource. It can be used if you only need distorted image, and don't need it's virtual viewport and other distortion details.