Skip to content

kreininmv/Medical-viewer

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Medical Viewer

A simple, interactive tool for exploring 3D medical images in Jupyter notebooks

License: MIT Python 3.8+

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.

Supported Formats

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

Quick Start

Basic Usage

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)

Loading from Files

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"
)

With Custom Class Names

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}
)

Customizing with ViewerParameters

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
)

Using the I/O Module Directly

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")

Examples

Axial soft window
Axial — Soft tissue window
Axial lung window
Axial — Lung window
Sagittal bone window
Sagittal — Bone window
Coronal soft window
Coronal — Soft tissue window

Installation

1. Clone the repository

git clone https://github.com/kreininmv/Medical-viewer.git
cd Medical-viewer

2. Install in editable mode

pip install -e .

Requirements

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 SimpleITK

License

This project is licensed under the MIT License.

Releases

No releases published

Packages

 
 
 

Contributors

Languages