Skip to content

nv-ext-tile

View as Markdown

@niivue/nv-ext-tile opens images that are too big to download in one go: whole-slide microscopy scans and OME-Zarr stores. These files are stored as a pyramid of small tiles at several resolutions. Instead of fetching the whole file, the package reads only the tiles on screen, at the resolution you are looking at.

Use it to:

  • show a whole-slide scan and let people pan and zoom around it. It reads tiled TIFF, BigTIFF, OME-TIFF, Aperio SVS and other scanner files, DICOM whole-slide images and flat OME-Zarr images.
  • load an OME-Zarr volume into a NiiVue scene, either one resolution level at a time or streamed piece by piece.

You do not need it for NIfTI, plain TIFF stacks and the other formats NiiVue reads itself. See Loading images.

Install

Terminal window
npm install @niivue/nv-ext-tile@next @niivue/niivue@next

NiiVue is a peer dependency, so you install it alongside the package.

Your first slide

import { createSlideView, NVSlide } from '@niivue/niivue'
import { openSlide } from '@niivue/nv-ext-tile/open'
const url =
'https://media.githubusercontent.com/media/niivue/niivue-demo-images-lfs/main/streaming/svs/CMU-1-Small-Region.svs'
const { candidates } = await openSlide(url)
const slide = NVSlide.fromSource(await candidates[0].open())
const canvas = document.getElementById('slide') as HTMLCanvasElement
const view = await createSlideView(canvas, { slide })

openSlide works out what kind of file it was given and lists the slides in it. createSlideView comes from NiiVue. It draws the slide with WebGPU, or WebGL2 when WebGPU is not available, follows the canvas when it resizes, and handles panning and zooming. The view fills the canvas, so give the canvas a size in your CSS.

When you are finished, view.destroy() releases the view, the slide and the file reads behind it.

What do you want to do?

  • Show a slide from a URL or from the user’s computer: see Viewing slides.
  • Open DICOM whole-slide images from a folder, a DICOMweb server or your own web server: see DICOM slides.
  • Load an OME-Zarr volume into a NiiVue scene: see OME-Zarr volumes.

Each format has its own import path (/open, /tiff, /dicom and /zarr), so a page downloads only the code for the formats it uses. /open loads a format’s code the first time it meets a file of that kind.

The live demo opens sample slides of each kind. Its source is in apps/demo-ext-tile.

Moving from older packages

This package replaces @niivue/nv-ext-wsi, @niivue/nv-ext-tiff and the OME-Zarr functions that used to be part of @niivue/niivue. Import them from here instead.

Using it without a bundler

The published package includes ready-to-load files in dist/standalone/: open.js, tiff.js, dicom.js and zarr.js. Everything they need is bundled in except NiiVue itself (and dcm2niix, below), so point an import map at NiiVue’s own standalone build and both share one copy:

<script type="importmap">
{
"imports": {
"@niivue/niivue": "./niivue/niivue.js",
"@niivue/nv-ext-tile/open": "./nv-ext-tile/open.js"
}
}
</script>

Map any other entry point you import, such as @niivue/nv-ext-tile/zarr, the same way. Copy NiiVue’s dist/standalone/ folder to niivue/ and this package’s to nv-ext-tile/.

For JPEG 2000 tiles, also map @niivue/dcm2niix to ./dcm2niix/index.jpeg.js and copy that package’s dist/ folder to dcm2niix/. Without it, ordinary JPEG tiles still show.