markdown-body entry-content container-lg" itemprop="text">

Slim: Interoperable slide microscopy viewer and annotation tool for imaging data science and computational pathology

Slim is a single-page application for interactive visualization and annotation of digital whole slide microscopy images and derived image analysis results in standard DICOM format. The application is based on the dicom-microscopy-viewer JavaScript library and runs fully client side without any custom server components. It relies on DICOMweb RESTful services to search for, retrieve, and store imaging data and can thereby simply be placed in front of any DICOMweb-conformant Image Management System (IMS), Picture Archiving and Communication (PACS), or Vendor Neutral Archive (VNA).

Explore
- National Cancer Institute's Imaging Data Commons
- Demo
Features
Authentication and Authorization
Configuration
Deployment
- Local
- Google Cloud Platform
  - OAuth 2.0 configuration
Development
Linking Slim to a Local dicom-microscopy-viewer Library
Citation
Acknowledgments
DICOM Conformance Statement

Explore

National Cancer Institute's Imaging Data Commons

Slim is used as the slide microscopy viewer by the National Cancer Institute's Imaging Data Commons (IDC).

Explore public IDC cancer imaging data collections by visiting the IDC web portal: portal.imaging.datacommons.cancer.gov. Some of the highlights of the data types available in IDC that can be handled by Slim are shown below.

Example/URL	Screenshot
Cyclic Immunofluorescence (CycIF)
H&E slide + manual annotations (DICOM SR)
H&E slide + nuclei segmentations (DICOM SEG)
H&E slide + nuclei polygon annotations (DICOM ANN)

The IDC viewer uses the Google Cloud Healthcare API as DICOMweb server.

Demo

Below you will find links to the representative DICOM SM images opened in Slim viewer:

Features

Display of images

Slim enables interactive visualization of DICOM VL Whole Slide Microscopy Image instances in a vendor-neutral and device-independent manner.

Interoperability with various image acquisition and management systems was successfully demonstrated at the DICOM WG-26 Connectathon at Path Visions 2020 and the DICOM WG-26 Hackathon at Path Visions 2021. Shown below are screenshots of examples images that are publicly available on the NEMA FTP server at medical.nema.org.

Vendor	Illumination	Stain
Roche Tissue Diagnostics	Brightfield	Trichrome
3DHISTECH	Brightfield	H&E
3DHISTECH	Fluorescence	DAPI, FITC, Rhodamine
SamanTree Medical	Fluorescence	Histolog

Display of image annotations and analysis results

Slim further allows for interative visualization of image annotations and analysis results. The viewer currently supports the following types of DICOM instances:

Vector graphics:

DICOM Comprehensive 3D SR instances that are structured according to template TID 1500 "Measurements Report" and contain planar image region of interest (ROI) annotations structured according to template TID 1410 "Planar ROI Measurements and Qualitative Evaluations"
DICOM Microscopy Bulk Simple Annotations instances that contain groups of many ROI annotations (e.g., single cells)

Raster graphics:

DICOM Segmentation instances that contain binary or fractional segmentation masks
DICOM Parametric Map instances that contain saliency maps, attention maps, class activation maps, etc.

	DICOM IOD
	Segmentation
	Parametric Map
	Comprehensive 3D SR
	Segmentation
	Microscopy Bulk Simple Annotations

Note that selection of a derived object in the URL will automatically load the referenced slide and will toggle visibility of the selected derived object.

Annotation of images

In addition to display, Slim provides annotation tools that allow users to create graphical image region of interest (ROI) annotations and store them as DICOM Comprehensive 3D SR instances using SR template TID 1500 "Measurement Report". ROIs are stored as 3D spatial coordinates (SCOORD3D) in millimeter unit according to SR template TID 1410 "Planar ROI Measurements and Qualitative Evaluations" together with measurements and qualitative evaluations (labels). Specifically, Image Region is used to store the vector graphic data and Finding is used to describe what has been annotated using a standard medical terminology such as SNOMED CT. The terms that can be chosen by a user can be configured (see AppConfig.d.ts).

Autentication and authorization

Users can authenticate and authorize the application to access data via OpenID Connect (OIDC) based on the OAuth 2.0 protocol using either the authorization code grant type (with Proof Key for Code Exchange (PKCE) extension) or the legacy implicit grant type.

Configuration

Server Configuration

The app can be configured via a public/config/{name}.js JavaScript configuration file (see for example the default public/config/local.js). Please refer to the AppConfig.d.ts file for configuration options.

The configuration can be changed at build-time using the REACT_APP_CONFIG environment variable.

Handling Mixed Content and HTTPS

When deploying SLIM with HTTPS, you may encounter mixed content scenarios where your PACS/VNA server returns HTTP URLs in its responses. This commonly occurs when:

The PACS server populates bulkdataURI fields with internal HTTP URLs
Your viewer is running on HTTPS but needs to communicate with services that respond with HTTP URLs
You're using a reverse proxy that terminates SSL

To handle these scenarios, SLIM provides the upgradeInsecureRequests option in the server configuration:

window.config = {
  servers: [
    {
      id: "local",
      url: "https://your-server.com/dcm4chee-arc/aets/MYAET/rs",
      upgradeInsecureRequests: true, // Enable automatic HTTP -> HTTPS upgrade
    },
  ],
};

When upgradeInsecureRequests is set to true and at least one of your URLs (service URL, QIDO, WADO, or STOW prefixes) uses HTTPS, the viewer will automatically:

Add the Content-Security-Policy: upgrade-insecure-requests header to requests
Attempt to upgrade any HTTP responses to HTTPS

This feature was implemented in response to issue #159 where PACS servers would return HTTP bulkdata URIs even when accessed via HTTPS.

Messages/Popups Configuration

Configure message popup notifications that appear at the top of the screen. By default, all message popups are enabled.

window.config = {
  // ... other config options ...
  messages: {
    disabled: ["warning", "info"], // Disable specific message types
    duration: 5, // Show messages for 5 seconds
    top: 100, // Show 100px from top of screen
  },
};

Options:

disabled: Disable specific message types or all messages
duration: How long messages are shown (in seconds)
top: Distance from top of screen (in pixels)

Available message types:

success - Green popups
error - Red popups
warning - Yellow popups
info - Blue popups

Examples:

// Disable specific types with custom duration and position
messages: {
  disabled: ['warning', 'info'],
  duration: 5, // Show for 5 seconds
  top: 50 // Show 50px from top
}

// Disable all popups
messages: {
  disabled: true;
}

Default values if not specified:

duration: 5 seconds
top: 100 pixels

Deployment

Download the latest release from github.com/imagingdatacommons/slim/releases and then run the following commands to install build dependencies and build the app:

yarn install
PUBLIC_URL=/ yarn build

Once the app has been built, the content of the build folder can be directly served by a static web server at the location specified by PUBLIC_URL (in this case at /). The PUBLIC_URL must be either a full URL or a relative path to the location at which the viewer application will get deployed (e.g., PUBLIC_URL=https://imagingdatacommons.github.io/slim or PUBLIC_URL='/slim').

To learn how to deploy Slim as a Google Firebase webapp, consider this tutorial.

Local

The repository provides a Docker compose file to deploy a static web server and a dcm4chee-arc-light DICOMweb server on localhost for local app development and testing:

docker-compose up -d

The local deployment serves the app via an NGINX web server at http://localhost:8008 and exposes the DICOMweb services at http://localhost:8008/dcm4chee-arc/aets/DCM4CHEE/rs. Once the serives are up, one can store DICOM objects in the archive using the Store transaction of the DICOMweb Studies Service.

The command line interface of the dicomweb-client Python package makes storing DICOM files in the archive straight forward:

dicomweb_client -vv --url http://localhost:8008/dcm4chee-arc/aets/DCM4CHEE/rs store instances -h

The local deployment uses the default configuration file public/config/local.js:

window.config = {
  path: "/",
  servers: [
    {
      id: "local",
      url: "http://localhost:8008/dcm4chee-arc/aets/DCM4CHEE/rs",
      write: true,
    },
  ],
  annotations: [
    {
      finding: {
        value: "85756007",
        schemeDesignator: "SCT",
        meaning: "Tissue",
      },
      style: {
        stroke: {
          color: [251, 134, 4, 1],
          width: 2,
        },
        fill: {
          color: [255, 255, 255, 0.2],
        },
      },
    },
  ],
};

Customize the configuration according to your needs at either build-time or run-time.

Google Cloud Platform

Slim can be readily configured to connect to a secured DICOMweb endpoint of the Google Cloud Healthcare API with OIDC authentication:

const gcpProject = "";
const gcpLocation = "";
const gcpDataset = "";
const gcpStore = "";
const gcpClientID = "";

window.config = {
  path: "/",
  servers: [
    {
      id: "gcp",
      url: `https://healthcare.googleapis.com/v1/projects/${gcpProject}/locations/${gcpLocation}/datasets/${gcpDataset}/dicomStores/${gcpStore}/dicomWeb`,
      write: true,
    },
  ],
  oidc: {
    authority: "https://accounts.google.com",
    clientId: gcpClientID,
    scope:
      "email profile openid https://www.googleapis.com/auth/cloud-healthcare",
    grantType: "implicit",
    endSessionEndpoint: "https://www.google.com/accounts/Logout",
  },
  annotations: [
    {
      finding: {
        value: "108369006",
        schemeDesignator: "SCT",
        meaning: "Neoplasm",
      },
      style: {
        stroke: {
          color: [251, 134, 4, 1],
          width: 2,
        },
        fill: {
          color: [255, 255, 255, 0.2],
        },
      },
    },
    {
      finding: {
        value: "85756007",
        schemeDesignator: "SCT",
        meaning: "Tissue",
      },
      style: {
        stroke: {
          color: [255, 255, 0, 1],
          width: 2,
        },
        fill: {
          color: [255, 255, 255, 0.2],
        },
      },
    },
  ],
};

OAuth 2.0 configuration

Create an OIDC client ID for web application.

Note that Google's OIDC implementation does currently not yet support the authorization code grant type with PKCE challenge for private clients. For the time being, the legacy implicit grand type has to be used.

Development

To install requirements and run the app for local development, run the following commands:

yarn install
yarn start

This will serve the app via a development server at http://localhost:3000 using the default local configuration.

The configuration can be specified using the REACT_APP_CONFIG environment variable, which can be set either in the .env file or directly in the command line:

REACT_APP_CONFIG=local yarn start

Linking Slim to a Local dicom-microscopy-viewer Library

If you are developing features or fixing bugs that require changes in both Slim and the underlying dicom-microscopy-viewer library, you can use yarn link to connect your local Slim project to a local clone of dicom-microscopy-viewer. This allows Slim to immediately use the latest local changes from the library without publishing to npm.

Steps

Clone dicom-microscopy-viewer
If you haven't already, clone the dicom-microscopy-viewer repository to your machine.
Set up yarn link in dicom-microscopy-viewer
In the root directory of your local dicom-microscopy-viewer repository, run:
```
yarn link
```
Link dicom-microscopy-viewer in Slim
In the root directory of your Slim project, run:
```
yarn link dicom-microscopy-viewer
```
Enable live rebuilding in dicom-microscopy-viewer
To automatically rebuild dicom-microscopy-viewer when you make changes, run the following command in the dicom-microscopy-viewer directory:
```
yarn webpack:dynamic-import:watch
```
This will watch for file changes and rebuild the library, so Slim can immediately use the updated code.
Run Slim as usual
In the Slim directory, start the development server:
```
yarn start
```
Slim will now use your locally linked version of dicom-microscopy-viewer.

Notes

If you want to unlink and return to the npm-published version, run yarn unlink dicom-microscopy-viewer and yarn install --force in the Slim directory.
Make sure both projects use compatible Node and Yarn versions to avoid dependency issues.

Citation

For more information about the motivation, design, and capabilities of Slim, please see the following article:

Interoperable slide microscopy viewer and annotation tool for imaging data science and computational pathology C. Gorman, D. Punzo, I. Octaviano, S. Pieper, W.J.R. Longabaugh, D.A. Clunie, R. Kikinis, A.Y. Fedorov, M.D. Herrmann Nature Communications 4:1572 (2023) https://doi.org/10.1038/s41467-023-37224-2

If you use Slim in your research, please cite the above article.

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. HHSN261201500003l.

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

DICOM Conformance Statement

The DICOM conformance statement for Slim is available in this repository here

License

ImagingDataCommons/slim

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 58

Uh oh!

Contributors 12

Uh oh!

Languages