monocle-viewer 0.1.0__tar.gz

monocle_viewer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Hoopes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

monocle_viewer-0.1.0/PKG-INFO

@@ -0,0 +1,94 @@
+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`.

monocle_viewer-0.1.0/README.md

@@ -0,0 +1,76 @@
+# 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`.

monocle_viewer-0.1.0/monocle/__init__.py

@@ -0,0 +1,4 @@
+from .normalize import Volume, to_volume
+from .session import Monocle, show
+
+__all__ = ['Monocle', 'show', 'to_volume', 'Volume']

monocle_viewer-0.1.0/monocle/cli.py

@@ -0,0 +1,175 @@
+"""
+The `monocle` console command to open the viewer from the shell.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from typing import Optional
+
+from .normalize import display_name
+from .session import Monocle
+
+
+def _flatten(groups: list) -> list:
+    """
+    Flatten argparse append+nargs groups into a single list.
+    """
+    return [item for group in groups for item in group]
+
+
+def _load_mgz(path: str):
+    """
+    Load an MGZ/MGH volume natively via surfa (the browser can't parse them).
+
+    Args:
+        path: The source file path.
+
+    Returns:
+        A surfa Volume the `Monocle` builder can normalize.
+    """
+    try:
+        import surfa
+    except ImportError:
+        sys.exit('reading MGZ files needs surfa: pip install surfa')
+    return surfa.load_volume(path)
+
+
+def _load_dicom(path: str) -> list:
+    """
+    Convert DICOM (a file or a directory of series) to in-memory nibabel
+    images via dicom2nifti — the browser can't parse DICOM, so it's decoded
+    here and embedded as voxels.
+
+    Slices are grouped by series so a directory of mixed series yields one
+    image each; series dicom2nifti can't handle (e.g. some vendor mosaics) are
+    skipped with a warning rather than aborting the batch.
+
+    Args:
+        path: A `.dcm` file or a directory containing DICOM files.
+
+    Returns:
+        A list of `(name, nibabel_image)` pairs, one per converted series.
+    """
+    try:
+        import pydicom
+        from dicom2nifti.convert_dicom import dicom_array_to_nifti
+    except ImportError:
+        sys.exit('reading DICOM needs dicom2nifti: pip install dicom2nifti')
+
+    files = [path] if os.path.isfile(path) else [
+        os.path.join(d, f) for d, _, fs in os.walk(path) for f in fs
+    ]
+    # Group readable image slices by series.
+    series: dict = {}
+    for f in files:
+        try:
+            ds = pydicom.dcmread(f)
+        except Exception:
+            continue  # non-DICOM (DICOMDIR, sidecars) — skip
+        if not hasattr(ds, 'PixelData') or not hasattr(ds, 'SeriesInstanceUID'):
+            continue
+        series.setdefault(ds.SeriesInstanceUID, []).append(ds)
+    if not series:
+        sys.exit(f'{path!r}: no DICOM image series found')
+
+    images = []
+    # Stable order: by series number, then description.
+    for uid in sorted(series, key=lambda u: (
+            int(getattr(series[u][0], 'SeriesNumber', 0) or 0),
+            str(getattr(series[u][0], 'SeriesDescription', '')))):
+        datasets = series[uid]
+        first = datasets[0]
+        name = (str(getattr(first, 'SeriesDescription', '')).strip()
+                or f'Series {getattr(first, "SeriesNumber", "?")}')
+        try:
+            # reorient_nifti=False keeps it fully in memory (reorientation
+            # would round-trip through a file path).
+            result = dicom_array_to_nifti(datasets, None, reorient_nifti=False)
+        except Exception as e:
+            print(f'skipping series {name!r}: {type(e).__name__}: {e}', file=sys.stderr)
+            continue
+        images.append((name, result['NII']))
+    if not images:
+        sys.exit(f'{path!r}: no DICOM series could be converted')
+    return images
+
+
+def _add(m: Monocle, path: str, *, seg: bool) -> None:
+    """
+    Add one input to the session, choosing the native-vs-browser load path.
+
+    Args:
+        m: The session builder.
+        path: A file path, or a directory of DICOM series.
+        seg: Whether the input is a segmentation label mask.
+    """
+    add = m.segmentation if seg else m.volume
+    lower = path.lower()
+    if os.path.isdir(path) or lower.endswith('.dcm'):
+        for name, img in _load_dicom(path):
+            add(img, name=name)
+    elif lower.endswith(('.mgz', '.mgh')):
+        add(_load_mgz(path), name=display_name(path))
+    else:
+        # Raw passthrough: embedded verbatim, parsed by the browser.
+        add(path)
+
+
+def main(argv: Optional[list] = None) -> None:
+    """
+    Parse arguments and open (or write) the Monocle viewer.
+    """
+    parser = argparse.ArgumentParser(
+        prog='monocle',
+        description='Open the Monocle viewer.',
+    )
+    parser.add_argument(
+        'images', nargs='*', help='image files or dicom directories to view')
+    parser.add_argument(
+        '-i', '--image', action='append', nargs='+', default=[],
+        metavar='IMAGE', help='additional image file(s); repeatable')
+    parser.add_argument(
+        '-s', '--seg', '--segmentation', action='append', nargs='+', default=[],
+        dest='segs', metavar='SEG', help='segmentation label mask(s); repeatable')
+    parser.add_argument('--title', help='session title')
+    parser.add_argument(
+        '--mode', choices=('panels', 'stack'), help='initial view mode')
+    parser.add_argument(
+        '--panels', type=int, metavar='N',
+        help='initial number of viewer panels (snapped up to 1, 2, 3, or 6)')
+    parser.add_argument(
+        '--no-populate', dest='populate', action='store_const',
+        const=False, default=None,
+        help='start with empty panels instead of filling them with images')
+    parser.add_argument(
+        '--html', metavar='PATH',
+        help='write a shareable standalone HTML file instead of opening a browser')
+    args = parser.parse_args(argv)
+
+    images = list(args.images) + _flatten(args.image)
+    segs = _flatten(args.segs)
+    # No inputs is fine — opens a blank viewer to drag files into.
+
+    m = Monocle(
+        title=args.title,
+        mode=args.mode,
+        populate=args.populate,
+        panel_count=args.panels)
+
+    for path in images:
+        _add(m, path, seg=False)
+    for path in segs:
+        _add(m, path, seg=True)
+
+    if args.html:
+        m.write(args.html)
+        print(f'wrote {args.html}')
+    else:
+        m.show()
+
+
+if __name__ == '__main__':
+    main()

monocle_viewer-0.1.0/monocle/emit.py

@@ -0,0 +1,197 @@
+"""
+Render a self-contained standalone HTML file embedding a Monocle session.
+"""
+from __future__ import annotations
+
+import base64
+import gzip
+import json
+import webbrowser
+
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from typing import Callable, Optional, Sequence
+
+from .normalize import RawFile, Volume
+
+
+# library bundle package data
+_BUNDLE = Path(__file__).parent / 'static' / 'monocle.umd.js'
+
+
+def _bundle_source() -> str:
+    if not _BUNDLE.exists():
+        raise FileNotFoundError(
+            f'Bundled viewer not found at {_BUNDLE}. Build it with '
+            '`npm run build:lib` in frontend/ and copy frontend/dist-lib/monocle.umd.js there, or call '
+            'with inline=False and a monocle_url=.'
+        )
+    return _BUNDLE.read_text(encoding='utf-8')
+
+
+def _render_html(manifest, payload_blocks, inline, monocle_url, title) -> str:
+    # escape `<` so embedded JSON can't break out of its <script> block
+    manifest_json = json.dumps(manifest).replace('<', '\\u003c')
+    blocks = '\n'.join(
+        f'<script type="application/octet-stream" id="monocle-vol-{vid}">{b64}</script>'
+        for vid, b64 in payload_blocks
+    )
+    if inline:
+        src = _bundle_source().replace('</script', '<\\/script')
+        js_block = f'<script>{src}</script>'
+    else:
+        if not monocle_url:
+            raise ValueError('inline=False requires monocle_url=')
+        js_block = f'<script src="{monocle_url}"></script>'
+
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>{title}</title>
+<style>html,body{{height:100%;margin:0}}#root{{position:fixed;inset:0}}</style>
+</head>
+<body>
+<div id="root"></div>
+<script type="application/monocle+json" id="monocle-session">{manifest_json}</script>
+{blocks}
+{js_block}
+<script>Monocle.mountEmbedded('#root')</script>
+</body>
+</html>
+"""
+
+
+def _encode_volumes(
+    volumes: Sequence[Volume],
+    id_prefix: str,
+    compression: str,
+    payload_blocks: list) -> list[dict]:
+    """
+    Build manifest entries for `volumes` and append their payload blocks.
+
+    Args:
+        volumes: The volumes to encode.
+        id_prefix: Prefix for the generated per-volume ids.
+        compression: Payload compression, 'gzip' or 'none'.
+        payload_blocks: The `(id, base64)` list to append payloads to.
+
+    Returns:
+        The manifest entries.
+
+    Raises:
+        ValueError: If `compression` is unknown.
+    """
+    if compression not in ('gzip', 'none'):
+        raise ValueError(f'Unknown compression: {compression!r}')
+    entries = []
+    for i, v in enumerate(volumes):
+        vid = f'{id_prefix}-{i}'
+        entry = v.manifest_entry(vid)
+        raw = v.raw_bytes()
+        # Raw source files that are already compressed (.nii.gz, .png, …) are
+        # embedded verbatim; everything else honors the requested transport.
+        mode = 'none' if isinstance(v, RawFile) and v.precompressed else compression
+        payload = gzip.compress(raw) if mode == 'gzip' else raw
+        entry['compression'] = mode
+        entries.append(entry)
+        payload_blocks.append((vid, base64.b64encode(payload).decode('ascii')))
+    return entries
+
+
+def render_html(
+    volumes: Sequence[Volume],
+    *,
+    annotations: Optional[Sequence[Volume]] = None,
+    inline: bool = True,
+    monocle_url: Optional[str] = None,
+    compression: str = 'gzip',
+    config: Optional[dict] = None) -> str:
+    """
+    Build the self-contained standalone HTML for `volumes`.
+
+    Args:
+        volumes: The scans to embed.
+        annotations: Segmentation label masks overlaid onto the scans (emitted
+            as a separate `annotations` array).
+        inline: Inline the viewer bundle; if False, reference `monocle_url`.
+        monocle_url: URL of a hosted viewer bundle.
+        compression: Volume payload compression, 'gzip' or 'none'.
+        config: Session-level viewing config (viewMode, title, global
+            toggles); its `title` also becomes the HTML document title.
+
+    Returns:
+        The HTML document as a string.
+    """
+    payload_blocks: list = []
+    scans = _encode_volumes(volumes, 'vol', compression, payload_blocks)
+    anno_entries = _encode_volumes(annotations or [], 'anno', compression, payload_blocks)
+
+    manifest = {'scans': scans}
+    if anno_entries:
+        manifest['annotations'] = anno_entries
+    if config:
+        manifest['config'] = config
+    title = (config or {}).get('title') or 'Monocle'
+    return _render_html(manifest, payload_blocks, inline, monocle_url, title)
+
+
+def write_html(volumes: Sequence[Volume], path: str, **kwargs) -> str:
+    """
+    Write the standalone HTML for `volumes` to a file.
+
+    Args:
+        volumes: The scans to embed.
+        path: Destination file path.
+        **kwargs: Forwarded to `render_html`.
+
+    Returns:
+        The path written.
+    """
+    Path(path).write_text(render_html(volumes, **kwargs), encoding='utf-8')
+    return path
+
+
+def open_html_in_browser(
+    html: str,
+    *,
+    browser: Optional[str] = None,
+    _open: Optional[Callable[[str], object]] = None) -> None:
+    """
+    Serve `html` from a one-shot local HTTP server and open the browser to it.
+
+    Mirrors plotly's `open_html_in_browser`: bind a random free port on
+    127.0.0.1, open the browser there, serve exactly one GET, then shut down —
+    so nothing is written to disk. Blocks until that single request is served
+    (which keeps the process alive long enough for the browser to fetch).
+
+    Args:
+        html: The document to serve.
+        browser: A `webbrowser` browser name; defaults to the system browser.
+        _open: An injectable opener (receives the URL) used for testing
+            without a real browser; defaults to the resolved `webbrowser`
+            opener.
+    """
+    payload = html.encode('utf-8')
+
+    class OneShotRequestHandler(BaseHTTPRequestHandler):
+        def do_GET(self):  # noqa: N802 (http.server API)
+            self.send_response(200)
+            self.send_header('Content-type', 'text/html')
+            self.end_headers()
+            buffer_size = 1024 * 1024
+            for i in range(0, len(payload), buffer_size):
+                self.wfile.write(payload[i : i + buffer_size])
+
+        def log_message(self, format, *args):  # silence stderr logging
+            pass
+
+    server = HTTPServer(('127.0.0.1', 0), OneShotRequestHandler)
+    url = 'http://127.0.0.1:%s' % server.server_port
+    try:
+        opener = _open if _open is not None else webbrowser.get(browser).open
+        opener(url)
+        server.handle_request()
+    finally:
+        server.server_close()