npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

dicom-microscopy-viewer

v0.50.0

Published

Interactive web-based viewer for DICOM Microscopy Images

Readme

Build Status NPM version NPM downloads per month License: MIT

DICOM Microscopy Viewer

Vanilla JS library for web-based visualization of DICOM VL Whole Slide Microscopy Image datasets and derived information.

The viewer visualizes slide microscopy images stored in a DICOMweb-compatible archive. It uses the dicomweb-client JavaScript library to retrieve data from the archive.

Note: The dicom-microscopy-viewer package is a library for building viewer applications, not a standalone viewer application. For a full application built on this library, see Slim.

Table of Contents

Features

  • Display of different image types: VOLUME / THUMBNAIL, OVERVIEW, LABEL
  • Annotation of regions of interest (ROI) as vector graphics based on 3-dimensional spatial coordinates (SCOORD3D): POINT, MULTIPOINT, POLYLINE, POLYGON, ELLIPSE, ELLIPSOID
  • Assembly of concatenations
  • Decoding of compressed pixel data, supporting baseline JPEG, JPEG 2000, JPEG-LS, High-Throughput JPEG 2000 (HTJ2K), and JPEG XL codecs
  • Correction of color images using ICC profiles
  • Additive blending and coloring of monochromatic images of multiple optical paths (channels), supporting highly multiplexed immunofluorescence imaging
  • Overlay of image analysis results in the form of DICOM Segmentation, Parametric Map, Comprehensive 3D SR, or Microscopy Bulk Simple Annotations

Documentation

API documentation is available online at imagingdatacommons.github.io/dicom-microscopy-viewer.

Installation

Install the dicom-microscopy-viewer package using your preferred package manager:

pnpm add dicom-microscopy-viewer

TypeScript declarations are included. pyramid, viv, errors, events and the view API of VolumeImageViewer are typed exactly; the other namespaces are declared with loose types for now. Applications that declare the module themselves (declare module "dicom-microscopy-viewer") keep their own declarations.

Getting started

Below is an example of the most basic usage: a web page that displays a collection of DICOM VL Whole Slide Microscopy Image instances of a digital slide. For more advanced usage, see the Slim viewer.

Packaging

The library is packaged as two builds: one using dynamic import, and another bundling into a single larger library.

The dynamic import version uses a public path of /dicom-microscopy-viewer/ so it can be used by adding an alias to the appropriate version and then deploying that version. In a plain web application, this can be loaded as:

const DICOMMicroscopyViewer = (
  await import("/dicom-microscopy-viewer/dicomMicroscopyViewer.min.js")
).default

Using a subdirectory isolates the dependencies that are unique to dicom-microscopy-viewer.

Basic usage

The viewer can be embedded in any website. To do so:

  1. Create an instance of VolumeImageViewer. The constructor requires an instance of DICOMwebClient for retrieving frames from the archive, as well as the metadata for each DICOM image as an instance of VLWholeSlideMicroscopyImage.
  2. Call the render() method, passing it the HTML element (or the name of the element) that should contain the viewport.
import * as DICOMMicroscopyViewer from "dicom-microscopy-viewer"
import * as DICOMwebClient from "dicomweb-client"

// Construct client instance
const client = new DICOMwebClient.api.DICOMwebClient({
  url: "http://localhost:8080/dicomweb",
})

// Retrieve metadata of a series of DICOM VL Whole Slide Microscopy Image instances
const retrieveOptions = {
  studyInstanceUID: "1.2.3.4",
  seriesInstanceUID: "1.2.3.5",
}
client.retrieveSeriesMetadata(retrieveOptions).then((metadata) => {
  // Parse, format, and filter metadata
  const volumeImages = []
  metadata.forEach((m) => {
    const image = new DICOMMicroscopyViewer.metadata.VLWholeSlideMicroscopyImage({
      metadata: m,
    })
    const imageFlavor = image.ImageType[2]
    if (imageFlavor === "VOLUME" || imageFlavor === "THUMBNAIL") {
      volumeImages.push(image)
    }
  })

  // Construct viewer instance
  const viewer = new DICOMMicroscopyViewer.viewer.VolumeImageViewer({
    client,
    metadata: volumeImages,
  })

  // Render viewer instance in the "viewport" HTML element
  viewer.render({ container: "viewport" })
})

Controlling the view

The view is described in slide coordinates (millimeter), the same coordinate system as navigate() and ROIs, so applications do not depend on the rendering library:

const { center, resolution, rotation } = viewer.getViewState()
// center: [x, y] in mm; resolution: mm per screen pixel;
// rotation: clockwise on screen, in radians, relative to the slide's default orientation

viewer.setViewState({ center: [10.5, 20.25], resolution: 0.001 })
viewer.fitBounds([[10, 20], [12, 21]], { padding: [20, 20, 20, 20] })
// Window [10, 200] of the 8-bit image values (image only, not ROIs or overlays)
const s = 255 / 190
const o = -10 / 190
viewer.setImageColorMatrix([s, 0, 0, 0, o, 0, s, 0, 0, o, 0, 0, s, 0, o, 0, 0, 0, 1, 0])
viewer.setImageColorMatrix(null) // back to the original colors

document.getElementById("viewport").addEventListener(
  DICOMMicroscopyViewer.events.EVENTS.VIEW_CHANGED,
  (event) => console.log(event.detail.payload.viewState),
)
  • The view state uses physical units only, so it means the same for every slide and renderer. To compare it with a renderer that uses zoom levels of the pixel matrix, such as deck.gl, use log2(pixelSpacing / resolution).
  • Use these methods after render(), which fits the whole slide into the viewport. setViewState() leaves properties that equal the current ones untouched, so setViewState(getViewState()) changes nothing (slide coordinates are rounded to 0.1 µm).
  • VIEW_CHANGED fires at most once per animation frame while the view changes. MOVE_STARTED and MOVE_ENDED also carry viewState.
  • POINTER_MOVE carries clientX, clientY and coordinates (slide coordinates in millimeter) next to the matched ROIs.
  • setImageColorMatrix() takes the 4 x 5 matrix of an SVG feColorMatrix (row by row, components in [0, 1]), applied in sRGB by default or in linear sRGB with { colorSpace: "linear-srgb" }. It covers brightness, contrast, windowing and white balance.
  • getMap(), which returns the OpenLayers map, is deprecated: the map is an implementation detail that can change with OpenLayers upgrades. It keeps working; use the methods above where they cover your needs. The OpenLayers event in the event field of event payloads is deprecated for the same reason.

Reading tiles without the viewer

Other renderers (for example deck.gl / Viv) can reuse the DICOMweb retrieval, frame decoding and ICC color management of this library through pyramid.VolumeImageReader. It takes the same client and metadata as VolumeImageViewer but needs neither OpenLayers nor a DOM element.

VolumeImageReader.fromSeries() retrieves the series metadata and keeps the VOLUME and THUMBNAIL images, as in the example above:

const reader = await DICOMMicroscopyViewer.pyramid.VolumeImageReader.fromSeries({
  client,
  studyInstanceUID: "1.2.3.4",
  seriesInstanceUID: "1.2.3.5",
  skipThumbnails: true,
})

Or construct it from metadata you already have:

const reader = new DICOMMicroscopyViewer.pyramid.VolumeImageReader({
  client,
  metadata: volumeImages,
  // A THUMBNAIL level has a different tile size than the VOLUME levels;
  // skip it when the renderer needs one tile size for all levels (e.g. Viv)
  skipThumbnails: true,
})

// Optical paths (channels), in the same order as viewer.getAllOpticalPaths()
const channels = reader.opticalPaths.map((opticalPath) => opticalPath.identifier)

// Pyramid levels, from highest to lowest resolution (as in OpenSlide and Viv)
const base = reader.levels[0]
console.log(base.totalPixelMatrixColumns, base.tileColumns, base.gridColumns)

// Pixel layout, e.g. { samplesPerPixel: 1, bitsAllocated: 16, arrayType: "Uint16Array", ... }
const pixelInfo = reader.getPixelInfo(channels[0])

// Base level pixel (column, row) to slide coordinates (millimeter) and back
const [x, y] = DICOMMicroscopyViewer.utils.applyTransform({
  coordinate: [0, 0],
  affine: reader.affine,
})

const controller = new AbortController()
const tile = await reader.getTile({
  opticalPathIdentifier: channels[0],
  level: base.index,
  column: 0,
  row: 0,
  signal: controller.signal, // optional, cancels the request and decoding
})
// tile.pixelArray holds the stored pixel values (native typed array).
// Edge tiles are padded: only tile.validColumns x tile.validRows hold image data.
// Pass crop: true to get edge tiles without the padding instead.

// Release the shared decoding web workers when done
reader.destroy()

fromSeries() also takes a signal to cancel the metadata request.

Errors follow one convention across pyramid and viv:

  • Invalid arguments throw a TypeError or RangeError (e.g. an unknown optical path or a tile outside of the grid), without a request.
  • Images that cannot be read or shown throw DICOMMicroscopyViewer.errors.CustomError, whose type is one of errors.errorTypes. Where available, code is one of errors.errorCodes (e.g. NO_IMAGES, INCONSISTENT_PYRAMIDS, UNSUPPORTED_PIXEL_DATA); codes keep their meaning across releases, so applications can act on them.
  • An aborted operation rejects with signal.reason (a DOMException named AbortError by default). destroy() aborts tiles that are still in flight; later getTile calls also reject with an AbortError.
  • Other failures reject with an Error whose cause is the underlying error, such as the dicomweb-client request error with its status.

How much of the work an abort cancels depends on the dicomweb-client version of the client you pass in:

  • With a version that supports the request.signal option (proposed in dcmjs-org/dicomweb-client#144, not released yet), the request that is actually sent is aborted (also when requestHooks replace the XMLHttpRequest), it is not reported to the client's errorInterceptor, and request hooks receive the signal as metadata.signal (e.g. to cancel a scheduled retry).
  • With dicomweb-client 0.11, the XMLHttpRequest is aborted and not reported to the errorInterceptor, unless a request hook replaces the XMLHttpRequest or re-sends it later (e.g. a retry hook).
  • With older versions, which ignore request options, the request still completes in the background; only the promise rejects early.

Using with Viv / deck.gl

viv.loadDicomWeb() loads a series as a Viv multiscale image, like Viv's own loadOmeTiff(). Viv and deck.gl are not dependencies of this library: the returned pixel sources implement Viv's PixelSource interface, and tiles are retrieved and decoded with pyramid.VolumeImageReader.

import { MultiscaleImageLayer } from "@vivjs/layers"

const { data, metadata, destroy } = await DICOMMicroscopyViewer.viv.loadDicomWeb({
  client,
  studyInstanceUID: "1.2.3.4",
  seriesInstanceUID: "1.2.3.5",
  signal, // optional, e.g. from an AbortController of the component
})

const layer = new MultiscaleImageLayer({
  loader: data,
  // Channel c is the optical path metadata.opticalPaths[c]
  selections: [{ c: 0 }, { c: 1 }],
  channelsVisible: [true, true],
  contrastLimits: [[0, 4000], [0, 4000]],
  colors: [[0, 0, 255], [0, 255, 0]],
})

// When the image is no longer shown: cancel pending requests, drop cached
// tiles and release the decoding web workers
destroy()
  • Levels are ordered from highest to lowest resolution and each is half the size of the previous one (rounded up), as Viv requires. Levels that the DICOM pyramid lacks (e.g. when its levels are 4 times apart) are computed from the next higher resolution level, at most maxSyntheticLevels (default 2) in a row. A lowest level of more than 16 tiles is not drawn as Viv's background image.
  • Monochrome images have one channel per optical path. Color images have one channel with interleaved RGB samples (Viv supports 8 bits per sample).
  • Tiles must be square with a power-of-2 size. Edge tiles are cropped to the image, and the pixel spacing is reported as meta.physicalSizes (for Viv's scale bar).
  • Tiles that Viv no longer needs are cancelled through its abort signals. Other failures, including tiles requested after destroy(), reach Viv's onTileError.
  • Decoded tiles are kept in a cache shared by all levels (cacheSize, 64 MiB by default, 0 to disable), so computed levels and zooming back do not retrieve the same tiles again. Treat tile data as read-only.
  • loadDicomWeb() also takes the reader's iccProfilesEnabled (on by default, as in the viewer) and iccOutputType options. To use a reader you already have, call viv.createPixelSources({ reader }); you then keep owning the reader and destroy it yourself.

Development

Prerequisites

  • Node.js (LTS recommended)
  • pnpm 11.9.0 (see packageManager in package.json)

We use Babel to compile (transpile), webpack to bundle, and Jest to test JavaScript code.

Get the source code by cloning the git repository:

git clone https://github.com/ImagingDataCommons/dicom-microscopy-viewer
cd dicom-microscopy-viewer

Install dependencies and build the package:

pnpm install
pnpm run build

Run tests:

pnpm run test

Build the API documentation:

pnpm run generateDocs

Useful scripts:

| Command | Description | | ------- | ----------- | | pnpm run build | Build the library | | pnpm run test | Run the test suite | | pnpm run generateDocs | Generate API documentation | | pnpm run lint | Check for lint issues | | pnpm run lint:fix | Auto-fix lint issues | | pnpm run fmt | Format source code | | pnpm run webpack:dynamic-import:watch | Watch and rebuild the dynamic-import package |

Related projects

  • Slim — interoperable slide microscopy viewer and annotation tool built on this library
  • dicomweb-client — JavaScript client for DICOMweb
  • Imaging Data Commons — cloud-based environment for publicly available cancer imaging data

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on coding style, documentation, and the development workflow.

Citation

Please cite the following article when using the viewer for scientific studies: Herrmann et al. J Path Inform. 2018:

@article{jpathinform-2018-9-37,
    Author={
        Herrmann, M. D. and Clunie, D. A. and Fedorov A. and Doyle, S. W. and Pieper, S. and
        Klepeis, V. and Le, L. P. and Mutter, G. L. and Milstone, D. S. and Schultz, T. J. and
        Kikinis, R. and Kotecha, G. K. and Hwang, D. H. and Andriole, K, P. and Iafrate, A. J. and
        Brink, J. A. and Boland, G. W. and Dreyer, K. J. and Michalski, M. and
        Golden, J. A. and Louis, D. N. and Lennerz, J. K.
    },
    Title={Implementing the {DICOM} standard for digital pathology},
    Journal={Journal of Pathology Informatics},
    Year={2018},
    Number={1},
    Volume={9},
    Number={37}
}

Support

The developers gratefully acknowledge their research support:

Acknowledgments

This software is maintained by the Imaging Data Commons (IDC) team, which has been funded in whole or in part with Federal funds from the NCI, NIH, under task order no. HHSN26110071 under contract no. HHSN261201500003I.

NCI Imaging Data Commons (IDC) (https://imaging.datacommons.cancer.gov/) is a cloud-based environment containing publicly available cancer imaging data co-located with analysis and exploration tools and resources. IDC is a node within the broader NCI Cancer Research Data Commons (CRDC) infrastructure that provides secure access to a large, comprehensive, and expanding collection of cancer research data.

Learn more about IDC from this publication:

Fedorov, A., Longabaugh, W. J. R., Pot, D., Clunie, D. A., Pieper, S. D., Gibbs, D. L., Bridge, C., Herrmann, M. D., Homeyer, A., Lewis, R., Aerts, H. J. W., Krishnaswamy, D., Thiriveedhi, V. K., Ciausu, C., Schacherer, D. P., Bontempi, D., Pihl, T., Wagner, U., Farahani, K., Kim, E. & Kikinis, R. National Cancer Institute Imaging Data Commons: Toward Transparency, Reproducibility, and Scalability in Imaging Artificial Intelligence. RadioGraphics (2023). https://doi.org/10.1148/rg.230180

License

This project is licensed under the MIT License.