A simple, interactive tool for exploring 3D medical images in Jupyter notebooks
PatientViewer is a Python class for interactive visualization of 3D medical images, such as CT or MRI scans, with optional segmentation mask overlays. It allows users to explore different anatomical planes (axial, sagittal, coronal) and apply visualization settings like windowing, alpha transparency, contour lines, and bounding boxes for connected components.
| Format | Extensions | Description |
|---|---|---|
| DICOM | directories, .dcm |
Standard medical imaging format |
| NRRD | .nrrd |
Nearly Raw Raster Data |
| NIfTI | .nii, .nii.gz |
Neuroimaging Informatics format |
| NumPy | .npy, .npz |
NumPy array files |
import numpy as np
from medical.viewer import PatientViewer
# Create viewer with numpy arrays
volume = np.random.rand(256, 256, 100)
mask = np.random.randint(0, 2, (256, 256, 100))
viewer = PatientViewer(volume=volume, mask=mask)from medical.viewer import PatientViewer
# Load from DICOM directory
viewer = PatientViewer(volume="/path/to/dicom_folder")
# Load from NRRD file
viewer = PatientViewer(volume="/path/to/scan.nrrd")
# Load from NIfTI file
viewer = PatientViewer(volume="/path/to/brain.nii.gz")
# Load from NumPy files
viewer = PatientViewer(
volume="/path/to/volume.npy",
mask="/path/to/mask.npy"
)from medical.viewer import PatientViewer
# Provide labels for mask values
viewer = PatientViewer(
volume="/path/to/scan.nrrd",
mask="/path/to/segmentation.npy",
class_names=["tumor", "edema", "necrosis"]
)
# Or use a dictionary mapping names to values
viewer = PatientViewer(
volume=volume,
mask=mask,
class_names={"background": 0, "liver": 1, "tumor": 2}
)Use ViewerParameters to configure the viewer's initial state:
from medical.viewer import PatientViewer, ViewerParameters
params = ViewerParameters(
projection="axial", # Initial view: "axial", "sagittal", or "coronal"
window="Soft", # Window preset: "Soft", "Lung", "Brain", "Bone", "Mask"
flip_on=False, # Flip the view
contour=True, # Show contour lines on masks
alpha=0.3, # Mask overlay transparency (0.0 - 1.0)
color_map=True, # Show color legend for classes
clip=(-100, 300), # Custom intensity clipping range
z=50, # Initial slice index
slice_bbox=False, # Show bounding box for current slice
mask_bbox=True, # Show bounding box around mask
component_bbox=False, # Show per-component bounding boxes
image_format="jpeg", # Output format: "jpeg" or "png"
jpeg_quality=95, # JPEG quality (1-100)
)
viewer = PatientViewer(
volume="/path/to/scan.nrrd",
mask="/path/to/mask.npy",
params=params
)from medical.io import read_volume
# Read volume as numpy array
volume = read_volume("/path/to/dicom_folder")
volume = read_volume("/path/to/scan.nrrd")
volume = read_volume("/path/to/data.npy")
volume = read_volume("/path/to/data.npz", npz_key="arr_0")|
Axial — Soft tissue window |
Axial — Lung window |
|
Sagittal — Bone window |
Coronal — Soft tissue window |
git clone https://github.com/kreininmv/Medical-viewer.git
cd Medical-viewerpip install -e .| Package | Purpose |
|---|---|
numpy |
Array operations |
matplotlib |
Color mapping |
ipywidgets |
Interactive controls |
opencv-python |
Image rendering |
cc3d |
Connected components |
SimpleITK |
Medical image I/O |
torch |
Tensor support (optional) |
Install all dependencies:
pip install numpy matplotlib ipywidgets opencv-python cc3d SimpleITKThis project is licensed under the MIT License.