dicom-microscopy-viewer
v0.50.0
Published
Interactive web-based viewer for DICOM Microscopy Images
Readme
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-viewerpackage 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
- 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, 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-viewerTypeScript 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")
).defaultUsing 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:
- Create an instance of VolumeImageViewer. The constructor requires an instance of
DICOMwebClientfor retrieving frames from the archive, as well as the metadata for each DICOM image as an instance of VLWholeSlideMicroscopyImage. - 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, sosetViewState(getViewState())changes nothing (slide coordinates are rounded to 0.1 µm). VIEW_CHANGEDfires at most once per animation frame while the view changes.MOVE_STARTEDandMOVE_ENDEDalso carryviewState.POINTER_MOVEcarriesclientX,clientYandcoordinates(slide coordinates in millimeter) next to the matched ROIs.setImageColorMatrix()takes the 4 x 5 matrix of an SVGfeColorMatrix(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 theeventfield 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
TypeErrororRangeError(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, whosetypeis one oferrors.errorTypes. Where available,codeis one oferrors.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(aDOMExceptionnamedAbortErrorby default).destroy()aborts tiles that are still in flight; latergetTilecalls also reject with anAbortError. - Other failures reject with an
Errorwhosecauseis the underlying error, such as the dicomweb-client request error with itsstatus.
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.signaloption (proposed in dcmjs-org/dicomweb-client#144, not released yet), the request that is actually sent is aborted (also whenrequestHooksreplace the XMLHttpRequest), it is not reported to the client'serrorInterceptor, and request hooks receive the signal asmetadata.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'sonTileError. - 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'siccProfilesEnabled(on by default, as in the viewer) andiccOutputTypeoptions. To use a reader you already have, callviv.createPixelSources({ reader }); you then keep owning the reader and destroy it yourself.
Development
Prerequisites
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-viewerInstall dependencies and build the package:
pnpm install
pnpm run buildRun tests:
pnpm run testBuild the API documentation:
pnpm run generateDocsUseful 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.
