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
• Documentation
• Installation
• Getting started
  • Packaging
  • Basic usage
• Development
• Related projects
• Contributing
• Citation
• Support
• Acknowledgments
• License

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, and JPEG-LS 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

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" })
})

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:

• Open Health Imaging Foundation (OHIF)
• Quantitative Image Informatics for Cancer Research (QIICR)
• Radiomics
• Imaging Data Commons (IDC)
• Neuroimage Analysis Center
• National Center for Image Guided Therapy
• MGH & BWH Center for Clinical Data Science (CCDS)

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.