ome-zarr.js

Appearance

render ​

The render(url) function takes an OME-Zarr url and returns a data: string for the src attribute of an html image.

Default usage ​

By default, render(url) will use the smallest resolution dataset from the multiscales pyramid.

It will also use any omero rendering settings in the image metadata to choose active channels and colors.

js
import * as omezarr from "https://cdn.jsdelivr.net/npm/ome-zarr.js/+esm";

let url = "https://livingobjects.ebi.ac.uk/idr/zarr/v0.4/idr0062A/6001240.zarr";
let thumbSrc = await omezarr.render(url);
document.getElementById("thumbnail").src = thumbSrc;

The thumbnails below are rendered at their natural size, corresponding to the smallest resolution for each OME-Zarr Image. Click the thumbnails to inspect each Image in ome-ngff-validator:

Target Size ​

You can choose a preferred targetSize and the resolution level where the longest side (x or y) is closest to the targetSize will be chosen.

js
let thumbSrc = await omezarr.render(url, 300);
thumbnail
thumbnail

Auto-boost ​

The intensity levels for each channel are mapped over the full intensity range of the pixels in the image. We find the min and max intensity values and then render the min intensity to black and the max to e.g. red, green, blue or white. However, if one or two pixels are much brighter than the rest, this can result in a dim image.

If autoBoost is true, then a histogram is calculated and if the top 20% of the histogram has less than 1% of pixels then we double the intensity of all pixels.

js
let thumbSrc = await omezarr.render(url, 200, {autoBoost: true});

Here we show the same Image thumbnail, with autoBoost = false and with autoBoost = true.

thumbnail
thumbnail

TIP

We only attempt to perform autoBoost if the initial render process took less than 100 millisecs, so as not to cause performance issues with larger images.

Max Size ​

We want to avoid attempts to render massive images. If the chosen resolution level has width x height greater than maxSize x maxSize then render() will throw an Error, with the default maxSize being 1000.

To change that threshold, we can specify a different value:

js
let maxSize = 1500;
let targetSize = 500;
let thumbSrc = await omezarr.render(url, targetSize, {maxSize: maxSize});

Test render() ​

Here you can test render() with your own images.

What's being loaded? ​

Under the hood, render() makes several calls to fetch zarr metadata and chunks.

When we specify targetSize the calls go like this:

js
// This loads the multiscales zarr.json or .zattrs and then
// loads the FIRST (largest) array by default, so we know the
// dimensions of the full-size image and can calculate the others
let ngffImg = await omezarr.NgffImage.load(store);

// This will load the appropriate array for the targetSize, then
// load chunks needed to render
let src = await ngffImg.render({targetSize, autoBoost});

If we don't specify targetSize, we save one extra fetch as we only need to load one array instead of 2.

js
// This loads the image and then loads the LAST (smallest) array
let datasetIndex = -1;  // last index
let ngffImg = await omezarr.NgffImage.load(store, {datasetIndex});

// We use the array at datasetIndex that we have alredy loaded.
let src = await ngffImg.render({arrayPathOrIndex: datasetIndex, autoBoost});

If we already have the zarr attributes in hand, then we can provide these and save the NgffImage from loading them itself:

js
// load the zarr.json manually (or our application already has this)
let zarrJson = await fetch("https://url/to/image.zarr/zarr.json").then((res) => res.json());
attrs = zarrJson.attributes; // v0.6 (zarr v3) nested attributes

// This won't need to load the zarr group again
let ngffImg = await omezarr.NgffImage.load(store, {attrs});