monocle-viewer 0.1.0

Python interface for the Monocle radiology viewer

Monocle - a Python interface to the Monocle viewer

monocle is a Python interface to Monocle, a browser-based radiology viewer for interacting with 3D medical images and segmentations. It targets clinical, multimodal imaging. Load a study from Python (or the command line), and monocle emits a self-contained HTML page and opens it in the browser.

pip install monocle-viewer

Command line

Pip also installs a monocle console command that opens the viewer on files from the shell:

monocle t1.nii.gz t2.nii.gz          # positional images
monocle t1.nii.gz -s tumor.nii.gz    # image + segmentation
monocle -i t1.nii.gz -i t2.nii.gz    # -i is the explicit image flag
monocle t1.nii.gz --html scan.html   # write a shareable file (no browser)

Positionals are images; -i/--image adds more; -s/--seg adds segmentation label masks. Without --html it opens the browser via the one-shot local server.

Nifti and ordinary images (png/jpeg) are embedded as-is and parsed in the browser. DICOM series need dicom2nifti and MGH files need surfa to load.

The Monocle python builder

For per-volume display options and session-wide viewing config within python, use the builder class. Monocle(...) sets session config, each .volume(...) adds a scan:

import monocle

m = monocle.Monocle(title='Patient 123')
m.volume(t1,    name='T1')
m.volume(flair, name='FLAIR')
m.segmentation(label, name='Tumor')

m.show()                # open in browser (no file, see below)
m.write('scan.html')    # write a persistent file
html = m.html()         # or get the HTML string

.volume(...) and .segmentation(...) accept a range of sources and handle the conversion:

• voxel volumes
• nibabel images
• torch tensors
• numpy arrays
• File paths

Convenience methods

monocle.show(sources, ...) is a one-liner for a quick look. It builds a Monocle instance, adds each source (with optional names= and affine=), and serves the page in the browser. Session config kwargs (title=, mode=, …) pass straight through.

monocle.show(t1, flair, names=['T1', 'FLAIR'], title='Patient 123')

If you work with voxel Volumes, they carry a built-in volume.show() that visualizes the scan through monocle directly — monocle ships with voxel by default, so there's nothing extra to install.

The embedded viewer bundle

Offline mode (the default, inline=True) pastes the viewer's UMD bundle into the HTML so the file works from file:// with no network. That bundle ships as package data at monocle/static/monocle.umd.js.