Chevron Down
Table of Contents
Chevron DownAPI Reference

Image Loaders

The image loader category documents a common data format, options, conventions and utilities for loader and writers for images that follow loaders.gl conventions.

Image Category Loaders

LoaderNotes
ImageLoaderLoads compressed images (PNG, JPG, etc)
CompressedTextureLoaderParses compressed textures to image data mipmap array
BasisLoaderTranspiles into supported compressed texture format

Core image category support is provided by the @loaders.gl/images module:

Usage

Individual loaders for specific image formats can be imported for @loaders.gl/images:

import '@loaders.gl/polyfills'; // Only required if loading images under Node.js
import {ImageLoader} from '@loaders.gl/images';
import {registerLoaders, load} from '@loaders.gl/core';
registerLoaders(ImageLoader);
const image = await load('image.jpeg');

However since each image loader is quite small (in terms of code size and bundle size impact), most applications will just install all image loaders in one go:

import '@loaders.gl/polyfills'; // Only required if loading images under Node.js
import {ImageLoaders} from '@loaders.gl/images';
import {registerLoader, load} from '@loaders.gl/core';
registerLoaders(ImageLoader);
const image = await load('image.jpeg');

Image Types

Images can be loaded as image data or as opaque image objects (Image or ImageBitmap), and the image type option can be used to control the type of image object produced by the ImageLoader.

A loaded image can always be returned as an image data object (an object containing a Uint8Array with the pixel data, and metadata like width and height, and in Node.js images are always loaded as image data objects).

In the browser, the ImageLoader uses the browser's native image loading functionality, and if direct access to the image data is not required, it is more efficient to load data into an opaque image object. The ImageLoader prefers ImageBitmap when supported, falling back to Image (aka HTMLImageElement) on older browsers.

Note that type is independent of the format of the image (see below).

Image TypeClassAvailabilityWorkersDescription
dataObject with {width: Number, height: Number, data: Uint8Array, ...}Node.js and browsersNoCompatible with headless gl.
imagebitmapImageBitmapChrome/FirefoxYes: transferrableA newer JavaScript class designed for efficient loading of images, optimized for use in worker threads and with WebGL
imageImage (aka HTMLImageElement)All browsersNoThe traditional HTML/JavaScript class used for image loading into DOM trees. WebGL compatible.

Image Data

Image data objects are images loaded as data, represented by an object that contains a typed array with the pixel data, size, and possibly additional metadata {width: Number, height: Number, data: Uint8Array, ...}

To get an image data object from a loaded Image or ImageBitmap, call getImageData(image). To load an image data object directly, set the image.type: 'data' option when loading the image.

Image Format

The format of the image describes how the memory is laid out. It is mainly important when working with data type images. The default format / memory layout for image data is RGBA and UNSIGNED_BYTE i.e. four components per pixel, each a byte.

Some loaders may add additional fields to the image data structure to describe the data format. Currently the image category does not provide any documentation for how to describe alternate formats/memory layouts, however a preliminary recommendation is to follow OpenGL/WebGL conventions.

Compressed Images

Compressed images are always returned as image data objects. They will have an additional field, compressed: true, indicating that the typed array in the data field contains compressed pixels and is not directly indexable.

Applications that use e.g. the CompressedTextureLoader and/or the BasisLoader together with the ImageLoader can check this flag before attempting to access the image data.

Options

The image category support some generic options (specified using options.image.<option-name>), that are applicable to all (or most) image loaders.

OptionDefaultTypeAvailabilityDescription
options.image.type'auto'stringSee tableOne of auto, data, imagebitmap, image
options.image.decodeHTMLtruebooleanNo: Edge, IE11Wait for HTMLImages to be fully decoded.

Notes

About worker loading

Worker loading is only supported for the data and imagebitmap formats. Since image worker loading is only available on some browsers (Chrome and Firefox), the ImageLoader dynamically determines if worker loading is available. Use options.worker: false to disable worker loading of images.

Image API

The image category also provides a few utilities:

  • Detecting ("sniffing") mime type and size of image files before parsing them
  • Getting image data (arrays of pixels) from an image without knowing which type was loaded (TBA)

Remarks

  • image data objects have the same fields as the browser's built-in ImageData class, but are not actual instances of ImageData. It is however easy to create an ImageData instance from an image data object:
const imageData = new ImageData(imagedata.data, imagedata.width, imagedata.height);

Note that this assumes its image format is the default 8-bit RGBA.