Metadata-Version: 2.4
Name: monocle-viewer
Version: 0.1.0
Summary: Python interface for the Monocle radiology viewer
Author: Andrew Hoopes
License-Expression: MIT
Keywords: medical-imaging,radiology,mri,ct,visualization,viewer,volume,nifti,dicom
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Dynamic: license-file

# 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:

```sh
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:

```python
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.

```python
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`.
