Metadata-Version: 2.4
Name: monocle-viewer
Version: 0.2.0
Summary: Python interface for the Monocle radiology viewer
Author: Andrew Hoopes
License-Expression: PolyForm-Noncommercial-1.0.0 OR LicenseRef-PolyForm-Internal-Use-1.0.0
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
License-File: licenses/PolyForm-Internal-Use-1.0.0.md
License-File: licenses/PolyForm-Noncommercial-1.0.0.md
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 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:

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

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

```python
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=`:

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

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

```python
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](LICENSE) for the complete terms.
