Chevron DownAPI Reference

ImageLoader

An image loader that works under both Node.js (requires @loaders.gl/polyfills) and the browser.

LoaderCharacteristic
File Extension.png, .jpg, .jpeg, .gif, .webp, .bmp, .ico, .svg
File TypeBinary
File FormatImage
Data FormatImageBitmap, Image (older browsers) or data (node.js)
Supported APIsload, parse

Usage

import '@loaders.gl/polyfills'; // only needed if using under Node
import {ImageLoader} from '@loaders.gl/images';
import {load} from '@loaders.gl/core';

const image = await load(url, ImageLoader, options);

Options

OptionTypeDefaultDescription
image.typeString'auto'Set to imagebitmap, image or data to explicitly control type of returned image. auto selects the most efficient supported format (imagebitmap on Chrome and Firefix)
image.decodebooleantrueApplies to image type images only, ensures image is fully decoded before loading promise resolves.

ImageBitmap Options

In addition, for imagebitmap type images, it is possible to pass through options to createImageBitmap to control image extraction, via the separate options.imagebitmap object. However, for portability it may be best to avoid relying on these options for now, since some browsers do not support ImageBitmap options (and some browsers do not support ImageBitmaps at all).

OptionTypeDefaultDescription
imagebitmap.imageOrientationstring'none'image should be flipped vertically. Either 'none' or 'flipY'.
imagebitmap.premultiplyAlphastring'default'Premultiply color channels by the alpha channel. One of 'none', 'premultiply', or 'default'.
imagebitmap.colorSpaceConversionstring'default'Decode using color space conversion. Either 'none' or 'default' default indicates implementation-specific behavior.
imagebitmap.resizeWidthnumber-Output image width.
imagebitmap.resizeHeightnumber-Output image height.
imagebitmap.resizeQualitystring'low'Algorithm to be used for resizing the input to match the output dimensions. One of pixelated, low (default), medium, or high.

Portability note: The exact set of imagebitmap options supported may depend on the browser.

Remarks

  • While generic, the ImageLoader is designed with WebGL applications in mind, ensuring that loaded image data can be used to create a WebGLTexture both in the browser and in headless gl under Node.js
  • Node.js support requires import @loaders.gl/polyfills before installing this module.