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 therefore be placed in front of any DICOMweb-conformant Image Management System (IMS), Picture Archiving and Communication System (PACS), or Vendor Neutral Archive (VNA).

• Explore
  • National Cancer Institute's Imaging Data Commons
  • Demo
• Features
  • Display of images
  • Display of image annotations and analysis results
  • Annotation of images
  • Memory monitoring
• Authentication and authorization
• Configuration
  • Server Configuration
  • Handling Mixed Content and HTTPS
  • Messages/Popups Configuration
  • Additional configuration topics
• Deployment
  • Local
  • Google Cloud Platform
• Development
• Linking Slim to a local dicom-microscopy-viewer library
• Related projects
• Contributing
• Citation
• Acknowledgments
• DICOM Conformance Statement
• License

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 in the IDC web portal. Highlights of data types available in IDC that Slim can handle 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 its DICOMweb server.

Representative DICOM SM images opened in Slim:

• H&E
• Multichannel fluorescence

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. Screenshots below show example 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

Slim also supports interactive visualization of image annotations and analysis results. The viewer currently supports the following types of DICOM instances:

Vector graphics:

• DICOM Comprehensive 3D SR instances structured according to template TID 1500 "Measurements Report" and containing 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 (for example, 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, and similar derived images

Fractional segmentations and parametric maps show an in-viewport color legend when at least one overlay is visible. The legend is collapsible and its per-item visibility toggles stay in sync with the switches in the right-hand panel.

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

Note: Selecting a derived object in the URL automatically loads the referenced slide and toggles visibility of the selected derived object.

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 units 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).

Slim includes automatic memory monitoring to help track browser memory usage when viewing large whole slide images. The memory monitor:

• Displays real-time memory usage in the footer (used memory, heap limit, usage percentage, remaining memory)
• Automatically monitors memory every 5 seconds using modern browser APIs when available
• Shows color-coded status indicators (green/orange/red) based on usage levels
• Issues warnings when memory usage exceeds 80% (high) or 90% (critical)
• Falls back to Chrome-specific APIs when modern APIs are not available

The memory footer appears at the bottom of all pages and updates automatically. When memory usage is high, users receive notifications with recommendations to refresh the page or close other tabs.

Memory monitoring is enabled by default and can be disabled by setting enableMemoryMonitoring: false in the application config.

For technical details, see Memory Monitoring Documentation.

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 the Proof Key for Code Exchange (PKCE) extension) or the legacy implicit grant type.

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.

A single-page guide covering external servers, runtime server selection, the gcp secondary data source, annotation colors, and read-only / worklist flags is available in docs/CONFIGURATION.md and on the project wiki.

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

When enableServerSelection is enabled in config (default false), users can switch the active DICOMweb server at runtime via the header Select server button (ApiOutlined icon):

window.config = {
  // ...
  enableServerSelection: true,
};

• Full URLs: Paste the complete server URL (e.g. https://healthcare.googleapis.com/v1/projects/.../dicomWeb).
• Path-only (GCP Healthcare): Paste a GCP DICOM store path without the domain (e.g. /projects/my-project/locations/us-central1/datasets/my-dataset/dicomStores/my-store). The app always prepends https://healthcare.googleapis.com/v1 and appends /dicomWeb (normalizeServerUrl; not controlled by gcpBaseUrl).

Custom selections are stored in localStorage, re-apply the current Bearer token when OIDC is in use, and use a temporary read-only client (write: false) for all SOP classes until you switch back to the default server.

See docs/CONFIGURATION.md for details.

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 are 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:

1. Add the Content-Security-Policy: upgrade-insecure-requests header to requests
2. 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.

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
}

Defaults (if not specified):

• duration: 5 seconds
• top: 100 pixels

Memory monitoring can be enabled or disabled through configuration:

window.config = {
  // ... other config options ...
  enableMemoryMonitoring: false, // Set to false to disable memory monitoring footer
}

• Default: Memory monitoring is enabled (enableMemoryMonitoring: true or undefined)
• Disable: Set enableMemoryMonitoring: false to hide the memory footer and stop monitoring

When enabled, the memory footer appears at the bottom of all pages and monitors memory usage every 5 seconds.

The following topics are documented in docs/CONFIGURATION.md:

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

Download the latest release from github.com/ImagingDataCommons/slim/releases, then install dependencies and build the app:

pnpm install
PUBLIC_URL=/ pnpm run build

Once the app has been built, the content of the build folder can be served directly 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 be deployed (for example, PUBLIC_URL=https://imagingdatacommons.github.io/slim or PUBLIC_URL=/slim).

To learn how to deploy Slim as a Google Firebase web app, see this tutorial.

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 services are up, DICOM objects can be stored 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 straightforward:

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, which reads the DICOMweb URL from window.slim.env.SLIM_LOCAL_DICOMWEB_URL (set in .env; see .env.example):

window.config = {
  path: "/",
  servers: [
    {
      id: "local",
      url: window.slim.env.SLIM_LOCAL_DICOMWEB_URL,
      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.

Slim can be 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],
        },
      },
    },
  ],
}

Create an OIDC client ID for web application and register the app origin as an authorized redirect URI (same value as Slim's path / app root).

Existing configs continue to work without changes:

• grantType: "implicit" (common for Google Cloud Healthcare setups) remains supported
• Omitting grantType uses the authorization code response type (code)

Deep links are restored after login through the OIDC state parameter (not localStorage). Silent token renewal reuses the same registered redirect URI (no additional IdP redirect URI is required).

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

Install dependencies and run the app for local development:

pnpm install
pnpm run start

This serves 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 on the command line:

REACT_APP_CONFIG=local pnpm run start

Copy .env.example to .env (gitignored) and adjust as needed. Without .env, start/build defaults to REACT_APP_CONFIG=local and SLIM_LOCAL_DICOMWEB_URL defaults to the docker-compose DICOMweb URL. Committed demo / preview configs require SLIM_DEMO_DICOMWEB_URL / SLIM_PREVIEW_DICOMWEB_URL in .env or CI (see scripts/inject-slim-env.mjs).

If you merge this change into a fork or redeploy:

1. Copy .env.example to .env (or keep your existing .env).
2. Stock local builds work without extra setup (localhost DICOMweb default).
3. Before Firebase / GitHub Pages deploys, set Actions secret or variable SLIM_PREVIEW_DICOMWEB_URL and SLIM_DEMO_DICOMWEB_URL.
4. Custom configs with hardcoded servers[].url keep working; only Slim’s committed local / demo / preview configs read window.slim.env.

Useful scripts:

If you are developing features or fixing bugs that require changes in both Slim and the underlying dicom-microscopy-viewer library, you can use pnpm 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.

When a Slim pull request is opened, the Firebase preview can install dicom-microscopy-viewer from a git branch instead of the npm pin:

1. Set dmv-branch: <branch-name> in the PR description (see the PR template), or
2. Use the same branch name in both repos and leave dmv-branch empty.

If neither applies, the preview uses the version in package.json. Editing the PR body to change dmv-branch: regenerates the preview. Details are in CONTRIBUTING.md.

1. Clone dicom-microscopy-viewer
   If you have not already, clone the dicom-microscopy-viewer repository to your machine.

2. Set up pnpm link in dicom-microscopy-viewer
   In the root directory of your local dicom-microscopy-viewer repository, run:

   pnpm link --global

3. Link dicom-microscopy-viewer in Slim
   In the root directory of your Slim project, run:

   pnpm link dicom-microscopy-viewer

   Do not run pnpm link dicom-microscopy-viewer inside the dicom-microscopy-viewer repo itself — only pnpm link --global belongs there.

   Verify the link points at your local clone (not the registry copy under .pnpm):

   node -e "console.log(require('fs').realpathSync('node_modules/dicom-microscopy-viewer'))"

4. Enable live rebuilding in dicom-microscopy-viewer
   In a separate terminal, in the dicom-microscopy-viewer directory, run:

   pnpm run webpack:dynamic-import:watch

   Slim imports the built dist/dynamic-import bundle, not src/ directly. Wait for DMV watch to report [emitted] dicomMicroscopyViewer.min.js after each change.

5. Run Slim as usual
   In the Slim directory, start the development server:

   pnpm run start

   When linked, craco.config.js registers the DMV dist/ folder as a webpack watch dependency so Slim rebuilds after DMV watch emits a new bundle. Restart Slim after linking or after changing craco.config.js.

• Running pnpm install in Slim removes the link — re-run step 3 afterward.

• Do not add link: overrides to package.json; the commands above are sufficient.

• Slim imports OpenLayers CSS directly (ol/ol.css), so ol is listed as a direct dependency. This keeps linked dev working when DMV's transitive dependencies are not hoisted into Slim's node_modules.

• If Slim still serves a stale DMV bundle, confirm step 3 (realpath must not contain .pnpm) and that DMV watch logged [emitted] dicomMicroscopyViewer.min.js for your change.

• To unlink and return to the npm-published version:

  pnpm unlink dicom-microscopy-viewer
  pnpm install

• dicom-microscopy-viewer — JavaScript library used by Slim for web-based visualization of DICOM VL Whole Slide Microscopy Image datasets
• Imaging Data Commons — cloud-based environment for publicly available cancer imaging data

Contributions are welcome! Please read CONTRIBUTING.md for guidelines on coding style, documentation, pull requests (including optional DMV preview pairing), and the development workflow.

For more information about the motivation, design, and capabilities of Slim, 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.

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

The DICOM Conformance Statement for Slim is available in this repository: DICOM-Conformance-Statement.md.

This project is licensed under the Apache License 2.0.