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 data. It targets clinical, multimodal imaging as well as research-related viewing requirements. 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 installs a monocle console command that opens the viewer on files from the shell:

monocle t1.nii.gz t2.nii.gz          # positional image arguments
monocle t1.nii.gz -s tumor.nii.gz    # image + segmentation
monocle t1.nii.gz -m pial.surf       # image + mesh
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; -m/--mesh adds triangular meshes. Without --html it opens the browser via the one-shot local server.

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 .image(...) adds a scan:

import monocle

m = monocle.Monocle(title='Patient 123')
t1 = m.image(t1, name='T1')
m.image(flair, name='FLAIR')
m.segmentation(label, name='Tumor', apply=t1)
m.mesh(surface, name='Cortex', apply=t1)

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

.image(...) returns the added image, and .segmentation(apply=...) takes one (or a list) to open with the mask already overlaid on those images' panels — or apply=True to overlay every populated panel.

The return values are session references rather than replacements for the objects supplied by nibabel, voxel, or surfa:

image: monocle.ImageHandle = m.image(t1)
annotation: monocle.AnnotationHandle = m.segmentation(mask, apply=image)

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

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

Segmentation label metadata is passed through to the viewer automatically when an in-memory volumes have a populated .labels lookup. You can override it, or provide labels for an array or file source, with labels=:

m.segmentation(
    mask,
    labels={
        0: 'background',              # omitted from the viewer label table
        1: 'tumor',
        2: ('edema', (255, 128, 0)),  # RGB can be 0..255
        3: ('necrosis', (0.8, 0.1, 0.2)),  # or 0..1
    },
)

.mesh(...) accepts voxel/trimesh objects, (vertices, faces) pairs, OBJ/STL/PLY paths, and FreeSurfer meshes. Mesh vertices must use world / scanner-RAS coordinates.

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

Payload interoperability

The payload adapters are available when a backend needs Monocle's normalized transfer representation directly:

payload = monocle.as_voxel_payload(nib_image)
mesh_payload = monocle.as_mesh_payload((vertices, faces))

monocle.decode_voxel_payload(entry, data) performs the inverse operation for a voxel manifest entry and its raw byte block. Payloads contain geometry and binary data only; display settings and annotation relationships live on the session handles.

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.

License

Monocle is free for noncommercial use and distribution, and for internal use by commercial organizations. Commercial distribution or use in a customer-facing product or service requires a separate commercial license. See LICENSE for the complete terms.