simpleDicomViewer 2.0.4

A package to simplify visualizing DICOM data, including images and segmentations (RTSTRUCT and SEG) via Jupyter/Python.

Summary

This is a simplistic DICOM viewer for images and related segmentations (RTSTRUCT and SEG). It was developed as a quick and dirty solution for performing spot checks on data downloaded from The Cancer Imaging Archive (TCIA) using tcia_utils. It was later separated into a stand-alone simpleDicomViewer PyPI package as many users of tcia_utils are not concerned with interactively viewing images and this capability introduced a lot of additional dependencies. There are many other more advanced viewers out there (e.g. 3D Slicer or itkWidgets) that you should try if your data fails with this tool.

Installation

Installation is performed using pip install simpleDicomViewer.

Jupyter Widget Installation

The interactive viewer is built using ipywidgets. After installing the python package, you may also need to enable the corresponding extension for your Jupyter environment.

For classic Jupyter Notebook:

jupyter nbextension enable --py widgetsnbextension

For JupyterLab:

jupyter labextension install @jupyter-widgets/jupyterlab-manager

After running the appropriate command, restart your Jupyter server to ensure the changes take effect. If you are using a hosted Jupyter environment like Google Colab, this step is typically not necessary as the extensions are pre-configured.

For more detailed instructions, please refer to the ipywidgets installation guide.

Usage

For viewing images, specify the path to a directory containing images from a single DICOM series. For annotations/segmentations, the path should point to the specific SEG or RTSTRUCT DICOM file name (not directory) that you're trying to visualize.

from simpleDicomViewer import dicomViewer

viewDicom(imagePath, segmentationPath)

Functional examples using TCIA data can be found in TCIA_Segmentations.ipynb.

Troubleshooting

If you encounter an "Error displaying widget: model not found" message or a warning that the @jupyter-widgets/jupyterlab-manager extension is outdated, it likely means there is a version mismatch between the ipywidgets Python package and the JupyterLab extension. This can often be resolved by running the following commands:

# Upgrade the ipywidgets package in your environment
pip install --upgrade ipywidgets

# Clean and rebuild the JupyterLab assets
jupyter lab clean
jupyter lab build

Remember to run these commands in the correct Python environment where you have JupyterLab and your kernel installed, and restart the JupyterLab server afterwards.

Acknowledgements

Thanks to Adam Li who introduced the original functionality in v1.x to display the segmentation overlays.

Citations:

This repository includes sample data from The Cancer Imaging Archive in the "data" folder which you can use for testing its features.

1. Zhao, B., Schwartz, L. H., Kris, M. G., & Riely, G. J. (2015). Coffee-break lung CT collection with scan images reconstructed at multiple imaging parameters (Version 3) [Dataset]. The Cancer Imaging Archive. https://doi.org/10.7937/k9/tcia.2015.u1x8a5nr
2. Wee, L., Aerts, H., Kalendralis, P., & Dekker, A. (2020). RIDER Lung CT Segmentation Labels from: Decoding tumour phenotype by noninvasive imaging using a quantitative radiomics approach [Data set]. The Cancer Imaging Archive. https://doi.org/10.7937/tcia.2020.jit9grk8