seqeyes-python 0.2.0__py3-none-any.whl

seqeyes/__init__.py

@@ -0,0 +1,32 @@
+"""
+SeqEyes — Interactive Pulseq MRI Sequence Viewer
+=================================================
+
+Drop‑in replacement for ``pypulseq.Sequence.plot()``.
+
+Quick start
+-----------
+>>> import seqeyes
+>>> seqeyes.set(theme="dark")          # enable SeqEyes + set defaults
+
+>>> seq.plot()                          # interactive viewer in Jupyter
+>>> seq.plot(show_blocks=True)          # per‑call overrides
+>>> seq.plot(time_range=(0, 0.05))     # zoom to first 50 ms
+
+>>> seqeyes.reset()                     # back to matplotlib
+
+In a plain ``.py`` script (no Jupyter):
+>>> seq.plot()   # opens the viewer in your default web browser
+
+API
+---
+- :func:`set` — enable SeqEyes + configure defaults
+- :func:`reset` — restore matplotlib
+- :class:`SeqEyesViewer` — low‑level viewer
+"""
+
+from seqeyes._plot import set, reset
+from seqeyes._renderer import SeqEyesViewer
+
+__all__ = ["set", "reset", "SeqEyesViewer"]
+__version__ = "0.2.0"

seqeyes/_plot.py

@@ -0,0 +1,221 @@
+"""
+_plot.py — SeqEyes plotting API.
+
+Call ``seqeyes.set()`` to switch ``seq.plot()`` to the interactive
+SeqEyes viewer.  Call ``seqeyes.reset()`` to restore matplotlib.
+
+In Jupyter the viewer renders inline.  In a ``.py`` script it opens
+a native desktop pop‑up window (requires ``pywebview``:  ``pip install pywebview``).
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Any, Optional, Tuple, Union
+
+
+# ── Module state ──────────────────────────────────────────────────────────
+
+_defaults: dict[str, Any] = {}
+_original_plot = None
+_patched = False
+
+
+# ── Public API ────────────────────────────────────────────────────────────
+
+def set(
+    *,
+    theme: Optional[str] = None,
+    show_blocks: Optional[bool] = None,
+    time_disp: Optional[str] = None,
+    grad_disp: Optional[str] = None,
+    time_range: Optional[Tuple[float, float]] = None,
+) -> None:
+    """Enable SeqEyes for all ``seq.plot()`` calls and set global defaults.
+
+    Call this once at the top of your notebook / script — with or
+    without arguments.  Any keywords become defaults applied to every
+    subsequent ``seq.plot()`` (overridable per‑call).
+
+    >>> seqeyes.set()                             # enable, system defaults
+    >>> seqeyes.set(theme="dark", time_disp="ms") # enable + defaults
+    >>> seq.plot()                                 # uses dark + ms
+    >>> seq.plot(theme="light")                    # overrides theme only
+    """
+    _store_defaults(theme, show_blocks, time_disp, grad_disp, time_range)
+    _ensure_patched()
+
+
+def reset() -> None:
+    """Restore matplotlib ``seq.plot()`` and clear all SeqEyes defaults.
+
+    Call ``seqeyes.set()`` again to re‑enable at any time.
+    """
+    global _patched
+    _defaults.clear()
+    _patched = False
+
+    try:
+        from pypulseq import Sequence as _Seq
+    except ImportError:
+        return
+
+    if _original_plot is not None:
+        _Seq.plot = _original_plot  # type: ignore[attr-defined]
+
+
+# ── Internal helpers ──────────────────────────────────────────────────────
+
+def _store_defaults(
+    theme: Optional[str],
+    show_blocks: Optional[bool],
+    time_disp: Optional[str],
+    grad_disp: Optional[str],
+    time_range: Optional[Tuple[float, float]],
+) -> None:
+    for name, val in [
+        ("theme", theme),
+        ("show_blocks", show_blocks),
+        ("time_disp", time_disp),
+        ("grad_disp", grad_disp),
+        ("time_range", time_range),
+    ]:
+        if val is not None:
+            _defaults[name] = val
+
+
+def _ensure_patched() -> None:
+    global _patched, _original_plot
+
+    if _patched:
+        return
+    _patched = True
+
+    try:
+        from pypulseq import Sequence as _Seq
+    except ImportError:
+        raise ImportError("pypulseq is not installed.  Install with: pip install pypulseq")
+
+    if _original_plot is None:
+        _original_plot = getattr(_Seq, "plot", None)
+
+    # ── Replacement .plot() ──────────────────────────────────────────
+    def _seqeyes_plot(
+        self: object,
+        label: str = "",
+        show_blocks: bool = False,
+        time_range: Any = (0, float("inf")),
+        time_disp: str = "s",
+        grad_disp: str = "kHz/m",
+        **kwargs: Any,
+    ) -> None:
+        # Merge globals — per‑call args take precedence
+        sb = _defaults.get("show_blocks", show_blocks)
+        td = _defaults.get("time_disp", time_disp)
+        gd = _defaults.get("grad_disp", grad_disp)
+        tr = _defaults.get("time_range", time_range)
+        th = str(kwargs.pop("theme", _defaults.get("theme", "system")))
+
+        seq_text = _seq_to_text(self)
+        if not seq_text:
+            raise RuntimeError("Could not write .seq text from the pypulseq Sequence.")
+
+        from seqeyes._renderer import SeqEyesViewer
+
+        viewer = SeqEyesViewer(
+            seq_text, label=label, show_blocks=sb,
+            time_range=tr, time_disp=td, grad_disp=gd, theme=th,
+        )
+
+        if _in_jupyter():
+            from IPython.display import display
+            display(viewer)
+        else:
+            _open_in_browser(viewer)
+
+    # Preserve original as _plot_matplotlib
+    if _original_plot is not None and not hasattr(_Seq, "_plot_matplotlib"):
+        _Seq._plot_matplotlib = _original_plot  # type: ignore[attr-defined]
+
+    _Seq.plot = _seqeyes_plot  # type: ignore[attr-defined]
+
+    # _repr_html_ so bare ``seq`` auto‑renders in Jupyter
+    def _seq_repr_html_(self: object) -> str:
+        from seqeyes._renderer import SeqEyesViewer
+        return SeqEyesViewer(_seq_to_text(self))._repr_html_()
+
+    _Seq._repr_html_ = _seq_repr_html_  # type: ignore[attr-defined]
+
+
+def _in_jupyter() -> bool:
+    try:
+        from IPython import get_ipython
+        s = get_ipython()
+        return s is not None and ("ZMQ" in s.__class__.__name__ or "Shell" in s.__class__.__name__)
+    except ImportError:
+        return False
+
+
+def _open_in_browser(viewer: "SeqEyesViewer") -> None:  # noqa: F821
+    """Open the viewer in a native desktop pop‑up window (pywebview).
+
+    Spawns a subprocess so ``webview.start()`` runs on its own main
+    thread without blocking the calling script.  Falls back to the
+    system browser if pywebview is not installed.
+    """
+    html = viewer.to_html()
+
+    # Write HTML to a temp file — file:// URLs are more reliable with
+    # pywebview than inline html= on some backends.
+    p = os.path.join(tempfile.gettempdir(), "seqeyes_viewer.html")
+    Path(p).write_text(html, encoding="utf-8")
+    url = f"file:///{p.replace(os.sep, '/')}"
+
+    try:
+        import webview  # type: ignore[import-untyped]
+    except ImportError:
+        _fallback_browser(url)
+        return
+
+    # Run webview in a subprocess so it gets its own main thread.
+    # We shell out to a tiny inline script — this avoids multiprocessing
+    # "spawn" issues (re‑importing the parent script on Windows).
+    import subprocess
+    import sys
+
+    script = (
+        "import webview;"
+        f"webview.create_window(title='SeqEyes — Pulseq MRI Sequence Viewer',url={url!r},width=1280,height=800,resizable=True,easy_drag=False);"
+        "webview.start()"
+    )
+    try:
+        subprocess.Popen(
+            [sys.executable, "-c", script],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+        )
+    except Exception:
+        _fallback_browser(url)
+
+
+def _fallback_browser(url: str) -> None:
+    """Last resort: open the viewer in the system web browser."""
+    import webbrowser
+    webbrowser.open(url)
+
+
+def _seq_to_text(seq: object) -> str:
+    if hasattr(seq, "write"):
+        with tempfile.NamedTemporaryFile(mode="r", suffix=".seq", delete=False, encoding="utf-8") as f:
+            tp = f.name
+        try:
+            seq.write(tp)  # type: ignore[union-attr]
+            return Path(tp).read_text(encoding="utf-8")
+        finally:
+            try:
+                os.unlink(tp)
+            except OSError:
+                pass
+    return ""

seqeyes/_renderer.py

@@ -0,0 +1,236 @@
+"""
+_renderer.py — Jupyter HTML renderer for the SeqEyes interactive viewer.
+
+Generates a self‑contained HTML string that Jupyter displays inline via
+``_repr_html_()``, exactly the same mechanism Plotly uses.  The viewer is
+an iframe embedding the SeqEyes web UI with sequence data injected.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import os
+from pathlib import Path
+from typing import Optional
+
+
+# ── Paths ─────────────────────────────────────────────────────────────────
+_RESOURCES_DIR = Path(__file__).resolve().parent / "resources"
+_VIEWER_TEMPLATE_PATH = _RESOURCES_DIR / "viewer.html"
+
+# pulseq-bundle.js lives in the repo root; during dev we read it directly.
+# When installed as a package, a copy should be placed in resources/.
+_BUNDLE_CANDIDATES = [
+    _RESOURCES_DIR / "pulseq-bundle.js",
+    Path(__file__).resolve().parent.parent.parent.parent / "web" / "pulseq-bundle.js",
+    Path.cwd() / "web" / "pulseq-bundle.js",
+]
+
+
+def _find_bundle() -> str:
+    """Locate and read the pulseq-bundle.js file."""
+    for p in _BUNDLE_CANDIDATES:
+        if p.is_file():
+            return p.read_text(encoding="utf-8")
+    raise FileNotFoundError(
+        "pulseq-bundle.js not found.  "
+        "Build it with: npm run build:web  (from the repo root), "
+        "or copy it to python/src/seqeyes/resources/"
+    )
+
+
+def _read_viewer_template() -> str:
+    """Read the standalone viewer HTML template."""
+    if _VIEWER_TEMPLATE_PATH.is_file():
+        return _VIEWER_TEMPLATE_PATH.read_text(encoding="utf-8")
+    alt = Path.cwd() / "python" / "src" / "seqeyes" / "resources" / "viewer.html"
+    if alt.is_file():
+        return alt.read_text(encoding="utf-8")
+    raise FileNotFoundError(
+        f"Viewer template not found at {_VIEWER_TEMPLATE_PATH}. "
+        "Ensure the package is installed correctly."
+    )
+
+
+def _build_html(
+    seq_text: str,
+    *,
+    theme: Optional[str] = None,
+    inject_bundle: bool = True,
+    label: str = "",
+    show_blocks: bool = False,
+    time_range: tuple = (0, float("inf")),
+    time_disp: str = "s",
+    grad_disp: str = "kHz/m",
+) -> str:
+    """Assemble the complete viewer HTML.
+
+    Parameters
+    ----------
+    seq_text : str
+        Raw .seq file content.
+    theme : str or None
+        CSS theme class to apply to ``<body>``.
+    inject_bundle : bool
+        If True, inline the pulseq-bundle.js parser into the HTML.
+    label : str
+        Display label (injected as JS variable, not yet rendered).
+    show_blocks : bool
+        Initial block‑boundary visibility.
+    time_range : tuple[float, float]
+        Initial viewport range in seconds.
+    time_disp : str
+        Initial time display unit (``"s"``, ``"ms"``, ``"us"``).
+    grad_disp : str
+        Initial gradient display unit (``"Hz/m"``, ``"kHz/m"``,
+        ``"mT/m"``, ``"G/cm"``).
+    """
+    template = _read_viewer_template()
+    seq_b64 = base64.b64encode(seq_text.encode("utf-8")).decode("ascii")
+
+    # 1. Inject the pulseq-bundle.js
+    bundle_placeholder = "<!-- PULSEQ_BUNDLE_PLACEHOLDER -->"
+    if inject_bundle and bundle_placeholder in template:
+        bundle_js = _find_bundle()
+        template = template.replace(
+            bundle_placeholder,
+            f"<script>\n{bundle_js}\n</script>",
+        )
+    elif bundle_placeholder in template:
+        template = template.replace(bundle_placeholder, "")
+
+    # 2. Build options injection block (sequence data + display opts)
+    opts = [
+        f"window.SEQEYES_RAW_B64 = {json.dumps(seq_b64)};",
+        f"window.SEQEYES_LABEL = {json.dumps(label)};",
+        f"window.SEQEYES_SHOW_BLOCKS = {json.dumps(show_blocks)};",
+        f"window.SEQEYES_TIME_RANGE = {json.dumps(list(time_range))};",
+        f"window.SEQEYES_TIME_DISP = {json.dumps(time_disp)};",
+        f"window.SEQEYES_GRAD_DISP = {json.dumps(grad_disp)};",
+    ]
+    opts_block = "\n".join(opts)
+
+    data_placeholder = "/* SEQEYES_DATA_PLACEHOLDER */"
+    if data_placeholder in template:
+        template = template.replace(data_placeholder, opts_block)
+    else:
+        template = template.replace(
+            "</body>",
+            f"<script>{opts_block}</script>\n</body>",
+        )
+
+    # 3. Apply theme if specified
+    if theme:
+        template = template.replace(
+            "<body>",
+            f'<body class="theme-{theme}">',
+        )
+
+    return template
+
+
+class SeqEyesViewer:
+    """Interactive Pulseq sequence viewer for Jupyter notebook output.
+
+    Normally you don't create this directly — call ``seqeyes.set()``
+    once, then use ``seq.plot(...)`` on any ``pypulseq.Sequence``.
+
+    Parameters
+    ----------
+    seq_text : str
+        Raw .seq file content as a string.
+    label : str
+        Display label (not yet rendered on the viewer).
+    show_blocks : bool
+        Whether to show block‑boundary lines initially.
+    time_range : tuple[float, float]
+        Initial time viewport ``(start_sec, end_sec)``.  ``(0, inf)``
+        shows the whole sequence.
+    time_disp : str
+        Time axis unit — ``"s"``, ``"ms"``, or ``"us"``.
+    grad_disp : str
+        Gradient axis unit — ``"Hz/m"``, ``"kHz/m"``, ``"mT/m"``, ``"G/cm"``.
+    theme : str or None
+        Colour theme.
+    width : str
+        CSS width of the iframe (e.g. ``"100%"``).
+    height : str
+        CSS height of the iframe (e.g. ``"550px"``).
+    """
+
+    def __init__(
+        self,
+        seq_text: str,
+        *,
+        label: str = "",
+        show_blocks: bool = False,
+        time_range: tuple = (0, float("inf")),
+        time_disp: str = "s",
+        grad_disp: str = "kHz/m",
+        theme: Optional[str] = None,
+        width: str = "100%",
+        height: str = "550px",
+    ) -> None:
+        self._seq_text = seq_text
+        self._label = label
+        self._show_blocks = show_blocks
+        self._time_range = time_range
+        self._time_disp = time_disp
+        self._grad_disp = grad_disp
+        self._theme = theme
+        self._width = width
+        self._height = height
+
+    # ── Jupyter integration ───────────────────────────────────────────
+
+    def _repr_html_(self) -> str:
+        """Return an HTML iframe that Jupyter renders inline."""
+        html = _build_html(
+            self._seq_text,
+            theme=self._theme,
+            label=self._label,
+            show_blocks=self._show_blocks,
+            time_range=self._time_range,
+            time_disp=self._time_disp,
+            grad_disp=self._grad_disp,
+        )
+        b64 = base64.b64encode(html.encode("utf-8")).decode("ascii")
+        return (
+            f'<iframe src="data:text/html;base64,{b64}" '
+            f'width="{self._width}" height="{self._height}" '
+            f'frameborder="0" '
+            f'style="border:none;max-width:100%;overflow:hidden" '
+            f'title="SeqEyes Viewer">'
+            f"</iframe>"
+        )
+
+    def _ipython_display_(self) -> None:
+        """IPython display hook."""
+        from IPython.display import HTML, display
+
+        display(HTML(self._repr_html_()))
+
+    # ── Convenience ────────────────────────────────────────────────────
+
+    def show(self) -> "SeqEyesViewer":
+        """Display the viewer (useful in IPython when auto‑display is off)."""
+        from IPython.display import display
+
+        display(self)
+        return self
+
+    # ── Direct HTML access (for debugging / custom embedding) ──────────
+
+    def to_html(self, *, inject_bundle: bool = True) -> str:
+        """Return the full standalone HTML string (for saving to a file)."""
+        return _build_html(
+            self._seq_text,
+            theme=self._theme,
+            inject_bundle=inject_bundle,
+            label=self._label,
+            show_blocks=self._show_blocks,
+            time_range=self._time_range,
+            time_disp=self._time_disp,
+            grad_disp=self._grad_disp,
+        )