semvec/pypi-packages huggingface dataset:
ipydicom 0.1.0
Lightweight DICOM MPR + 3D viewer for Jupyter notebooks with overlay support.
License: MIT
Requires Python: >=3.9

# 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`):
```bash
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.
```python
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:
```python
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.]
```python
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
```python
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.