Skip to content

Viewing slides

View as Markdown

A slide is one very large 2D image, such as a scanned microscope slide. This package reads its tiles. NiiVue’s NVSlide keeps track of which tiles are needed, and createSlideView draws them on a canvas.

Opening a slide from a URL

import { createSlideView, NVSlide } from '@niivue/niivue'
import { openSlide } from '@niivue/nv-ext-tile/open'
const { candidates } = await openSlide('https://example.org/scans/kidney.svs')
const slide = NVSlide.fromSource(await candidates[0].open())
const view = await createSlideView(canvas, { slide })

openSlide tells the kind of file from the end of the URL:

  • .svs, .tif, .tiff, .ndpi, .scn, .bif and other TIFF-based scanner files are read as tiled TIFF.
  • A path ending in .zarr or / is an OME-Zarr image.
  • .dzi is a Deep Zoom image.
  • .json is a slide manifest, such as a hosted DICOM slide.

When the URL does not say, it reads the first few bytes of the file to find out. A single DICOM file cannot be opened by URL, because a DICOM slide is spread over several files.

Opening files from the user’s computer

Pass the files from a file input, a folder picker or a drop. Nothing is uploaded: tiles are read straight from the files.

const input = document.getElementById('files') as HTMLInputElement
const { candidates } = await openSlide(Array.from(input.files ?? []))

TIFF files and DICOM whole-slide files can be mixed. A folder of DICOM files can hold several slides, so the next section matters here. A local OME-Zarr folder or Deep Zoom image cannot be opened this way; serve it and open it by URL.

When there is more than one slide

openSlide never chooses for you. It lists every slide it found, in the order of the files you gave it, each with a label you can show in a menu:

const { candidates } = await openSlide(files)
const names = candidates.map((c) => c.label)
// later, when the user picks one:
const slide = NVSlide.fromSource(await candidates[picked].open())

To show a different slide in the same view, call view.setSlide(slide). The view releases the slide it was showing.

JPEG 2000 tiles

Some Aperio SVS files and DICOM slides store their tiles as JPEG 2000, and some DICOM slides use JPEG-LS. Browsers cannot decode either, so these tiles fail to load until you add decoders from @niivue/dcm2niix:

Terminal window
npm install @niivue/dcm2niix@rc

The package needs dcm2niix 1.4.20261105-rc.3 or newer. Then register the decoders once, before you open any slide:

import { registerDcm2niixDecoders } from '@niivue/nv-ext-tile/dicom'
import { registerDcm2niixTiffDecoders } from '@niivue/nv-ext-tile/tiff'
registerDcm2niixDecoders() // DICOM tiles and colour profiles
registerDcm2niixTiffDecoders() // JPEG 2000 tiles in TIFF and SVS files

The decoders run in web workers that load the first time a tile needs them. registerDcm2niixDecoders also turns on colour management: a slide that carries a colour (ICC) profile is shown in the colours the scanner intended. A slide reads its profile when it is created, which is why registering comes first. Ordinary JPEG tiles decode without any of this.

Servers that need a login

Pass your own fetch. It is called the same way as the browser’s fetch for every read, so you can add headers or sign URLs:

const { candidates } = await openSlide(url, {
fetch: (url, init) =>
fetch(url, {
...init,
headers: { ...init?.headers, Authorization: `Bearer ${token}` },
}),
})

Deep Zoom images are the exception: they always use the browser’s fetch, and opening one with a custom fetch throws an error.

What the server must support

Slides are read in small pieces with HTTP Range requests, so the server must answer them with 206 Partial Content. A server that sends the whole file instead is refused with “server ignored the HTTP Range request”; the package does not fall back to downloading a slide that might be gigabytes.

If the slide is on another domain, the server must also allow it with CORS: send Access-Control-Allow-Origin and allow the Range request header.

For a server you cannot change, download the file and open it from disk as shown above.

Images with several channels

Fluorescence images in OME-TIFF and OME-Zarr often have many channels. They open blended together, using the channel names and colours stored in the file. The contrast comes from the file when it gives one, or else from a quick look at a low-resolution copy. When the file does not say which channels to show, the first four are shown. Hidden channels are not downloaded until you show them.

Three 8-bit channels in an OME-Zarr image are shown as an ordinary colour picture, and a one-channel image is shown in grey.

For ready-made controls, such as a channel panel, a focal-plane slider and a minimap, see UIKit.

Focal planes and time points

Some slides hold a stack of focal planes or a series of time points: OME-TIFF stacks, Argos z-stacks, OME-Zarr images with z or t, and DICOM focal stacks. slide.planes tells you how many there are, and setPlaneIndex moves between them:

console.log(slide.planes) // for example { z: 5, t: 1 }
await slide.setPlaneIndex({ z: 3, t: 0 })

The current plane stays on screen until the new one is ready. To open a TIFF at a given plane, pass tiff: { z: 3 } to openSlide.

Files from particular scanners

Besides standard pyramidal TIFF, these open as you would expect: Philips TIFF, Hamamatsu NDPI (up to 4 GiB) and Argos z-stacks. Ventana BIF tile joints, Trestle overlaps and Leica SCN regions open placed as the scanner laid them out; pass tiff: { placement: false } to openSlide for the grid of tiles stored in the file.

Opening one format directly

If you always know the format, you can skip openSlide and use that format’s source:

import { TiffSlideSource } from '@niivue/nv-ext-tile/tiff'
const source = await TiffSlideSource.fromUrl('https://example.org/scan.svs')
const slide = NVSlide.fromSource(source)

For OME-Zarr, ZarrSlideSource.fromUrl from @niivue/nv-ext-tile/zarr works the same way.

Decoding in the background

By default, TIFF tiles decode on the page’s main thread. A Pool from @niivue/geotiff-rs decodes them in web workers instead, which keeps the page smooth. It is also safer for files you do not trust: a few of the decoders do not limit how much memory a damaged tile can claim, and in a worker the damage stays out of your page.

import { Pool } from '@niivue/geotiff-rs'
const pool = new Pool()
const { candidates } = await openSlide(url, { pool })
// when you no longer need it:
pool.destroy()

The pool belongs to you: the package borrows it and never shuts it down. @niivue/geotiff-rs is already a dependency of this package; add it to your own dependencies to import it.

Memory and bandwidth

A slide keeps 96 MiB of decoded tiles (maxCacheBytes), loads 12 tiles at once (maxConcurrentLoads), and picks its level from targetScreenPixelsPerTilePixel. When the finest level in view will not fit the cache, it draws a coarser one and says why. See Memory and bandwidth for every setting and a live demo.

Cleaning up

Ownership runs in a chain: the view owns the slide, and the slide owns the source it was made from. So view.destroy() releases everything. To share one source between two slides, make them with NVSlide.fromSource(source, { ownsSource: false }) and call source.dispose() yourself when both are gone.

To stop an open that is taking too long, or one the user has moved on from, pass an AbortSignal:

const controller = new AbortController()
const opened = openSlide(url, { signal: controller.signal })
controller.abort()