Idetik

Getting Started ​

Idetik is a high-performance library for exploring multi-dimensional OME-Zarr datasets right in the browser. This guide builds the smallest complete Idetik application: a viewer that pans and zooms through one slice of a terabyte-scale image. Along the way it introduces the base concepts every Idetik application is made of.

Installing Idetik ​

Idetik is published to npm as @idetik/core. The package ships ES modules with TypeScript declarations. Its few dependencies are installed with it.

bash
npm install @idetik/core

Adding a Canvas ​

Idetik needs a single canvas element to draw into.

html
<canvas id="viewer"></canvas>

Idetik matches its drawing surface to the canvas element's layout size and follows the element when it resizes. Size the canvas with CSS as you would any other element.

Loading an OME-Zarr Image ​

A source connects a layer to the data it renders. OmeZarrImageSource opens a multiscale OME-Zarr image from an HTTP store or a local directory. Its static method fromHttp takes the URL of the image's root group and returns a promise that resolves to the source once the store's metadata has been read.

INFO

This guide uses a light-sheet time-lapse of a developing zebrafish embryo from Zebrahub, a sequencing and imaging atlas of zebrafish development.

typescript
import { OmeZarrImageSource } from '@idetik/core';

const baseUrl = 'https://public.czbiohub.org/royerlab/zebrahub/imaging';

const source = await OmeZarrImageSource.fromHttp({
  url: `${baseUrl}/single-objective/ZSNS001.ome.zarr/`,
});

Only metadata has been fetched at this point. The source knows the image's axes, resolution levels, and channel count. No pixel data has been downloaded yet.

Configuring the Camera ​

A camera defines which part of the world a viewport shows. OrthographicCamera uses a parallel projection that draws every pixel at the same size regardless of depth. That makes it the camera for 2D image viewing. Its constructor takes the extent of the visible frame. The source metadata can be used to set the initial view to frame the whole image.

typescript
import { OrthographicCamera, PanZoomControls } from '@idetik/core';

const dims = source.getDimensions();
const x = dims.x.lods[0];
const y = dims.y.lods[0];

const camera = new OrthographicCamera({
  left: x.translation,
  right: x.translation + x.size * x.scale,
  top: y.translation,
  bottom: y.translation + y.size * y.scale,
});

const controls = new PanZoomControls(camera);

As mentioned, Idetik automatically responds to changes to the canvas size. The frame is padded rather than stretched when the canvas's aspect ratio differs from the frame's.

PanZoomControls turns pointer and wheel events into pan and zoom on the camera. Controls are separate from the camera so that any camera can be driven by any input scheme or by one you write yourself.

Creating an Image Layer ​

A layer renders data from a source. ImageLayer draws one 2D slice of a multi-channel image and streams the chunks that intersect the current view at a resolution matched to the zoom level. Its constructor takes the source, the slice, and the appearance of each channel.

Slice coordinates select the data in the same world units the camera uses. Idetik models five axes: time, channel, z, y, and x; matching the OME-NGFF v0.4 and v0.5 specs. Data axes are mapped onto these by name, so x and y must be present while t, c, and z are picked up when the metadata declares them.

The image layer shows the XY plane by default. The slice therefore fixes a time point and a z position and lists which channels to load.

typescript
import { ImageLayer } from '@idetik/core';

const layer = new ImageLayer({
  source,
  sliceCoords: { t: 400, z: 278, c: [0] },
  channelProps: [{ contrastLimits: [0, 60] }],
});

These coordinates pick a slice halfway through the time-lapse and halfway through the stack. The value 278 for z is a world coordinate and means 278 µm into the stack. c takes channel indices. This dataset has one channel. The layer holds the slice coordinates by reference. Changing them later moves through the data.

channelProps takes one entry per channel in the source. Each entry sets the channel's visibility, tint color, and contrast limits. Contrast limits are the intensity range mapped onto the display. The signal in this dataset lies below 60. The limits are set tightly to bring out the embryo. visible defaults to true and color defaults to white.

Which resolution levels to load and how far ahead to fetch are decided by the layer's loading policy. The default suits interactive panning and zooming.

Starting the Runtime ​

Idetik is the entry point of an application. An instance owns the renderer and the chunk manager and drives the render loop for its viewports. A viewport pairs a camera and its controls with a stack of layers and draws into the canvas. Everything built so far comes together in the constructor.

typescript
import { Idetik } from '@idetik/core';

const idetik = new Idetik({
  canvas: document.querySelector<HTMLCanvasElement>('#viewer')!,
  viewports: [{ camera, cameraControls: controls, layers: [layer] }],
});

idetik.start();

start connects the input handlers and begins the render loop. Each frame the layer asks the chunk manager for the chunks visible through the camera. The manager fetches them in priority order and uploads them to the GPU.

The renderer draws what has arrived. Coarser resolution levels cover chunks that have not arrived yet. The view fills in progressively instead of waiting on the network. Layers in every viewport share one memory budget.

Drag to pan and scroll to zoom. The sliders do nothing more than write new values into the layer's slice coordinates. Zooming in moves the layer to finer resolution levels and requests only the chunks inside the frame. The full-resolution image is explored without ever being downloaded whole.

Conclusion ​

The complete program fits in forty lines and is the shape of every Idetik application. A source provides data. A layer decides what to draw from it and streams only what the view needs. A camera and its controls define the view. The runtime owns the render loop and a chunk budget shared by everything on the canvas.

typescript
import {
  Idetik,
  ImageLayer,
  OmeZarrImageSource,
  OrthographicCamera,
  PanZoomControls,
} from '@idetik/core';

const baseUrl = 'https://public.czbiohub.org/royerlab/zebrahub/imaging';

const source = await OmeZarrImageSource.fromHttp({
  url: `${baseUrl}/single-objective/ZSNS001.ome.zarr/`,
});

const dims = source.getDimensions();
const x = dims.x.lods[0];
const y = dims.y.lods[0];

const camera = new OrthographicCamera({
  left: x.translation,
  right: x.translation + x.size * x.scale,
  top: y.translation,
  bottom: y.translation + y.size * y.scale,
});

const controls = new PanZoomControls(camera);

const layer = new ImageLayer({
  source,
  sliceCoords: { t: 400, z: 278, c: [0] },
  channelProps: [{ contrastLimits: [0, 60] }],
});

const idetik = new Idetik({
  canvas: document.querySelector<HTMLCanvasElement>('#viewer')!,
  viewports: [{ camera, cameraControls: controls, layers: [layer] }],
});

idetik.start();

None of these pieces is a viewer. There is no user interface, no application state, and no opinion about the page around the canvas. Those belong to the application. Idetik stays out of their way. Applications that need time sliders, channel panels, or several synchronized views build them from these same pieces.

Released under the MIT License

Biohub