ipydicom 0.1.0

Lightweight DICOM MPR + 3D viewer for Jupyter notebooks with overlay support.

Jupyter DICOM Viewer

Lightweight MPR + 3D DICOM viewer for Jupyter notebooks. Runs entirely in the notebook (no desktop UI), with crosshair-synced axial/coronal/sagittal views, optional 3D volume render, and mask overlays.

Install

Using pip (from a local checkout or future PyPI release ipydicom):

pip install -e .   # from this repo
# or, once published: pip install ipydicom

Quick start

%matplotlib widget is recommended for best interactivity, but the viewer calls panel/VTK extensions internally. If widgets do not render, ensure ipywidgets/ipympl/Panel are installed and the widget manager is enabled in your notebook frontend.

from jupyter_dicom.DICOMViewer import DICOMViewer

# Option A: use the file chooser in the UI
viewer = DICOMViewer()

# Option B: preload a folder or a single DICOM file
# viewer = DICOMViewer(dicom_path="/path/to/folder_or_file.dcm")

viewer.display()

UI basics:

• File chooser: pick a DICOM folder (or pass dicom_path above).
• Buttons: Eye/Adjust/Magic = normalization modes; 3D View = VTK volume render with locator; Metadata = current slice metadata.
• Navigation: click any view or drag sliders; crosshair/sliders stay in sync.

Direct loading (no chooser)

You can still load programmatically:

viewer = DICOMViewer()
vol, dims = viewer.controller.dicom_handler.load_series("/path/to/folder_or_file.dcm")
viewer.controller.mpr_viewer.set_volume(vol, viewer.controller.dicom_handler.get_spacing())
viewer.display()

Overlays (masks/labelmaps)

Supports .npy masks and DICOM-SEG via load_mask_dicom_seg(path); labelmaps must match the loaded volume shape. [Requires overlay mask shape == volume shape (z, y, x); non-zero voxels are shown with the given color/alpha.]

mask = viewer.new_empty_mask()              # shape matches volume (z, y, x)
mask[10:20, 30:50, 40:60] = 1               # demo patch
viewer.set_overlay(mask, alpha=0.4, color=(0.0, 0.9, 0.2), jump_to=True)

# Multiple overlays
oid = viewer.add_overlay(mask2, color=(0.9, 0.0, 0.9), alpha=0.3, overlay_id="lesion", jump_to=True)
viewer.remove_overlay("lesion")
viewer.clear_overlay()

Navigation helpers

viewer.jump_to(x=120, y=90, z=42)  # move crosshair and 3D locator
viewer.reset_view()                # recenter crosshair

Notes

• Panel/VTK is initialized inside the library; you usually don’t need extra %matplotlib widget setup, but having ipywidgets/ipympl installed is required.
• Single-file DICOM or folders both work for dicom_path and for load_series. For 3D, the directory containing the file is used.
• Sample data: see samples/README.md (small CT + DICOM-SEG from QIICR/dcmqi, Apache-2.0). Larger TCIA samples are ignored in git (samples/tcia_prostate_seg/ placeholder).
• Publishing: package is named ipydicom (pyproject.toml). Build with python -m build and upload with twine once credentials are available.