seqeyes-python 0.4.1__tar.gz → 0.4.3__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. {seqeyes_python-0.4.1 → seqeyes_python-0.4.3}/PKG-INFO +31 -6
  2. {seqeyes_python-0.4.1 → seqeyes_python-0.4.3}/README.md +30 -5
  3. {seqeyes_python-0.4.1 → seqeyes_python-0.4.3}/pyproject.toml +1 -1
  4. {seqeyes_python-0.4.1 → seqeyes_python-0.4.3}/src/seqeyes/__init__.py +1 -1
  5. seqeyes_python-0.4.3/src/seqeyes/_renderer.py +320 -0
  6. seqeyes_python-0.4.3/src/seqeyes/resources/index.html +3135 -0
  7. {seqeyes_python-0.4.1 → seqeyes_python-0.4.3}/src/seqeyes/resources/pulseq-bundle.js +380 -37
  8. seqeyes_python-0.4.3/src/seqeyes/resources/styles.css +332 -0
  9. {seqeyes_python-0.4.1 → seqeyes_python-0.4.3}/src/seqeyes/resources/webview-bundle.js +627 -54
  10. seqeyes_python-0.4.3/tests/conftest.py +27 -0
  11. {seqeyes_python-0.4.1 → seqeyes_python-0.4.3}/tests/integration_test.py +5 -4
  12. {seqeyes_python-0.4.1 → seqeyes_python-0.4.3}/tests/test_plot.py +51 -31
  13. seqeyes_python-0.4.3/tests/test_renderer.py +224 -0
  14. seqeyes_python-0.4.1/src/seqeyes/_renderer.py +0 -294
  15. seqeyes_python-0.4.1/src/seqeyes/resources/seqeyes-labels.js +0 -448
  16. seqeyes_python-0.4.1/src/seqeyes/resources/viewer.html +0 -1748
  17. seqeyes_python-0.4.1/tests/conftest.py +0 -9
  18. seqeyes_python-0.4.1/tests/debug_full.html +0 -3530
  19. seqeyes_python-0.4.1/tests/debug_minimal.html +0 -281
  20. seqeyes_python-0.4.1/tests/debug_viewer.html +0 -3530
  21. seqeyes_python-0.4.1/tests/debug_viewer.py +0 -50
  22. seqeyes_python-0.4.1/tests/test_renderer.py +0 -120
  23. {seqeyes_python-0.4.1 → seqeyes_python-0.4.3}/.gitignore +0 -0
  24. {seqeyes_python-0.4.1 → seqeyes_python-0.4.3}/examples/demo.ipynb +0 -0
  25. {seqeyes_python-0.4.1 → seqeyes_python-0.4.3}/examples/demo.py +0 -0
  26. {seqeyes_python-0.4.1 → seqeyes_python-0.4.3}/src/seqeyes/_plot.py +0 -0
  27. {seqeyes_python-0.4.1 → seqeyes_python-0.4.3}/tests/test_ismrmrd_fixture.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: seqeyes-python
3
- Version: 0.4.1
3
+ Version: 0.4.3
4
4
  Summary: Interactive Pulseq MRI sequence viewer for Jupyter — lightweight, beautiful, replaces seq.plot() in pypulseq.
5
5
  Project-URL: Homepage, https://github.com/bughht/seqeyes_plugin
6
6
  Project-URL: Repository, https://github.com/bughht/seqeyes_plugin
@@ -38,17 +38,30 @@ It works as a drop‑in replacement for `pypulseq.Sequence.plot()`,
38
38
  rendering an interactive viewer directly in Jupyter notebook cell
39
39
  output — just like Plotly.
40
40
 
41
+ The output is the [SeqEyes web app](https://bughht.github.io/seqeyes_plugin/)'s
42
+ own viewer, so it has the same features and fixes as the web app, VS Code and
43
+ MATLAB.
44
+
41
45
  ## Features
42
46
 
43
- - 🎛️ **Interactive waveform viewer** — zoom, pan, per‑channel amplitude zoom
47
+ - 🎛️ **Interactive waveform viewer** — zoom, pan, per‑channel amplitude zoom, reorderable rows
44
48
  - 📍 **Tooltip** with block details (RF amplitude, gradient strength, ADC params)
45
- - 🗺️ **3D k‑space trajectory viewer** — rotate, zoom, depth‑sorted rendering
46
- - 🎨 **8 colour themes** — system, light, dark, dracula, nord, and more
49
+ - 📏 **Measurement markers** — snap to waveform events, read values and Δt
50
+ - 🗺️ **3D k‑space trajectory viewer** — rotate, pan, zoom at the cursor
51
+ - 🔊 **Gradient spectrogram and sound** for the visible window
52
+ - 🧲 **PNS and acoustic resonances** from a Siemens ASC profile
53
+ - 🎨 **Themes** — system, One Light, One Dark, Dracula, Nord, GitHub Light, GitHub Dark
47
54
  - 📏 **Unit conversion** — time (s / ms / µs), gradient (Hz/m / mT/m / G/cm)
48
55
  - 📐 **Minimap** with TR/TE overlay and viewport indicator
49
56
  - 💾 **Export to standalone HTML** — shareable, no Python needed
50
57
  - 🔌 **Drop‑in pypulseq integration** — `seq.plot()` just works
51
58
 
59
+ In notebook output the viewer shows the sequence its cell passed in, so it has
60
+ no Open button or drag & drop, and the Bloch simulation is not available there.
61
+ The output frame cannot store anything, so settings changed in it are not
62
+ remembered; pass them to `seq.plot()` or `seqeyes.set()` instead. Each output
63
+ carries the whole viewer, about 1.3 MB plus the sequence.
64
+
52
65
  ## Installation
53
66
 
54
67
  ```bash
@@ -109,6 +122,16 @@ SeqEyesViewer.from_file("my_sequence.bseq", theme="dark")
109
122
  | `seqeyes.reset()` | Restore matplotlib `seq.plot()` and clear all defaults |
110
123
  | `SeqEyesViewer(source, ...)` | Low-level viewer for raw `.seq` text or `.bseq` bytes |
111
124
  | `SeqEyesViewer.from_file(path, ...)` | Open a local `.seq` or `.bseq` file without pypulseq |
125
+ | `viewer.to_html()` | The viewer as one self-contained HTML page |
126
+ | `viewer.to_html(inject_bundle=False)` | The same page referencing `styles.css`, `pulseq-bundle.js` and `webview-bundle.js` by relative URL, to serve next to copies of those files |
127
+
128
+ | Option | Values |
129
+ |---|---|
130
+ | `theme` | `"system"`, `"light"` (GitHub Light), `"dark"` (GitHub Dark), `"onelight"`, `"onedark"`, `"dracula"`, `"nord"`, `"githublight"`, `"github"` |
131
+ | `time_disp` | `"s"` (default), `"ms"`, `"us"` |
132
+ | `grad_disp` | `"mT/m"` (default), `"Hz/m"`, `"G/cm"` |
133
+ | `show_blocks` | show block boundaries |
134
+ | `time_range` | initial view `(start, end)` in seconds; the default `(0, inf)` keeps the viewer's first view (the first TR, when one is detected); an infinite end runs to the end of the sequence |
112
135
 
113
136
  ## Viewer Controls
114
137
 
@@ -119,10 +142,12 @@ SeqEyesViewer.from_file("my_sequence.bseq", theme="dark")
119
142
  | Amplitude zoom (per channel) | Ctrl + scroll wheel |
120
143
  | Tooltip | Hover over waveform |
121
144
  | Toggle channels | Click legend labels |
122
- | K‑Space viewer | Click "K‑Space" button |
145
+ | Reorder rows | Drag a channel's name, or right-click it |
146
+ | Measurement markers | Right-click the waveform → **Add marker** |
147
+ | K‑space, then spectrogram | The **K‑Space / Spectrum** toolbar button cycles the analysis panel |
123
148
  | Rotate k‑space | Click + drag in panel |
124
149
  | Minimap navigation | Click on minimap strip |
125
- | Open another file | 📂 Open button |
150
+ | PNS and acoustic bands | **Load ASC (PNS/Acoustic)** |
126
151
 
127
152
  ## Requirements
128
153
 
@@ -6,17 +6,30 @@ It works as a drop‑in replacement for `pypulseq.Sequence.plot()`,
6
6
  rendering an interactive viewer directly in Jupyter notebook cell
7
7
  output — just like Plotly.
8
8
 
9
+ The output is the [SeqEyes web app](https://bughht.github.io/seqeyes_plugin/)'s
10
+ own viewer, so it has the same features and fixes as the web app, VS Code and
11
+ MATLAB.
12
+
9
13
  ## Features
10
14
 
11
- - 🎛️ **Interactive waveform viewer** — zoom, pan, per‑channel amplitude zoom
15
+ - 🎛️ **Interactive waveform viewer** — zoom, pan, per‑channel amplitude zoom, reorderable rows
12
16
  - 📍 **Tooltip** with block details (RF amplitude, gradient strength, ADC params)
13
- - 🗺️ **3D k‑space trajectory viewer** — rotate, zoom, depth‑sorted rendering
14
- - 🎨 **8 colour themes** — system, light, dark, dracula, nord, and more
17
+ - 📏 **Measurement markers** — snap to waveform events, read values and Δt
18
+ - 🗺️ **3D k‑space trajectory viewer** — rotate, pan, zoom at the cursor
19
+ - 🔊 **Gradient spectrogram and sound** for the visible window
20
+ - 🧲 **PNS and acoustic resonances** from a Siemens ASC profile
21
+ - 🎨 **Themes** — system, One Light, One Dark, Dracula, Nord, GitHub Light, GitHub Dark
15
22
  - 📏 **Unit conversion** — time (s / ms / µs), gradient (Hz/m / mT/m / G/cm)
16
23
  - 📐 **Minimap** with TR/TE overlay and viewport indicator
17
24
  - 💾 **Export to standalone HTML** — shareable, no Python needed
18
25
  - 🔌 **Drop‑in pypulseq integration** — `seq.plot()` just works
19
26
 
27
+ In notebook output the viewer shows the sequence its cell passed in, so it has
28
+ no Open button or drag & drop, and the Bloch simulation is not available there.
29
+ The output frame cannot store anything, so settings changed in it are not
30
+ remembered; pass them to `seq.plot()` or `seqeyes.set()` instead. Each output
31
+ carries the whole viewer, about 1.3 MB plus the sequence.
32
+
20
33
  ## Installation
21
34
 
22
35
  ```bash
@@ -77,6 +90,16 @@ SeqEyesViewer.from_file("my_sequence.bseq", theme="dark")
77
90
  | `seqeyes.reset()` | Restore matplotlib `seq.plot()` and clear all defaults |
78
91
  | `SeqEyesViewer(source, ...)` | Low-level viewer for raw `.seq` text or `.bseq` bytes |
79
92
  | `SeqEyesViewer.from_file(path, ...)` | Open a local `.seq` or `.bseq` file without pypulseq |
93
+ | `viewer.to_html()` | The viewer as one self-contained HTML page |
94
+ | `viewer.to_html(inject_bundle=False)` | The same page referencing `styles.css`, `pulseq-bundle.js` and `webview-bundle.js` by relative URL, to serve next to copies of those files |
95
+
96
+ | Option | Values |
97
+ |---|---|
98
+ | `theme` | `"system"`, `"light"` (GitHub Light), `"dark"` (GitHub Dark), `"onelight"`, `"onedark"`, `"dracula"`, `"nord"`, `"githublight"`, `"github"` |
99
+ | `time_disp` | `"s"` (default), `"ms"`, `"us"` |
100
+ | `grad_disp` | `"mT/m"` (default), `"Hz/m"`, `"G/cm"` |
101
+ | `show_blocks` | show block boundaries |
102
+ | `time_range` | initial view `(start, end)` in seconds; the default `(0, inf)` keeps the viewer's first view (the first TR, when one is detected); an infinite end runs to the end of the sequence |
80
103
 
81
104
  ## Viewer Controls
82
105
 
@@ -87,10 +110,12 @@ SeqEyesViewer.from_file("my_sequence.bseq", theme="dark")
87
110
  | Amplitude zoom (per channel) | Ctrl + scroll wheel |
88
111
  | Tooltip | Hover over waveform |
89
112
  | Toggle channels | Click legend labels |
90
- | K‑Space viewer | Click "K‑Space" button |
113
+ | Reorder rows | Drag a channel's name, or right-click it |
114
+ | Measurement markers | Right-click the waveform → **Add marker** |
115
+ | K‑space, then spectrogram | The **K‑Space / Spectrum** toolbar button cycles the analysis panel |
91
116
  | Rotate k‑space | Click + drag in panel |
92
117
  | Minimap navigation | Click on minimap strip |
93
- | Open another file | 📂 Open button |
118
+ | PNS and acoustic bands | **Load ASC (PNS/Acoustic)** |
94
119
 
95
120
  ## Requirements
96
121
 
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "seqeyes-python"
7
- version = "0.4.1"
7
+ version = "0.4.3"
8
8
  description = "Interactive Pulseq MRI sequence viewer for Jupyter — lightweight, beautiful, replaces seq.plot() in pypulseq."
9
9
  readme = "README.md"
10
10
  license = {text = "MIT"}
@@ -29,4 +29,4 @@ from seqeyes._plot import set, reset
29
29
  from seqeyes._renderer import SeqEyesViewer
30
30
 
31
31
  __all__ = ["set", "reset", "SeqEyesViewer"]
32
- __version__ = "0.4.1"
32
+ __version__ = "0.4.3"
@@ -0,0 +1,320 @@
1
+ """
2
+ _renderer.py — Jupyter HTML renderer for the SeqEyes interactive viewer.
3
+
4
+ The viewer is the standalone SeqEyes page (``web/index.html``) run as the
5
+ ``python`` host: the sequence and the display options are injected ahead of
6
+ the page's own script, the way the MATLAB toolbox does it. Jupyter displays
7
+ it inline via ``_repr_html_()`` in a ``data:`` iframe, the same mechanism
8
+ Plotly uses; such a frame can fetch nothing, so the stylesheet and both
9
+ scripts are inlined.
10
+ """
11
+
12
+ from __future__ import annotations
13
+
14
+ import base64
15
+ import json
16
+ import math
17
+ import os
18
+ import re
19
+ from pathlib import Path
20
+ from typing import Any, List, Optional, Union
21
+
22
+
23
+ # ── Paths ─────────────────────────────────────────────────────────────────
24
+ _RESOURCES_DIR = Path(__file__).resolve().parent / "resources"
25
+ # ``npm run build:web`` copies the page and its assets into resources/; a
26
+ # source checkout (python/src/seqeyes/) can read them from web/ instead.
27
+ _WEB_DIR = Path(__file__).resolve().parent.parent.parent.parent / "web"
28
+
29
+ # The page's references to its assets, each present exactly once.
30
+ _STYLESHEET_TAG = '<link rel="stylesheet" href="styles.css">'
31
+ _PULSEQ_TAG = '<script src="pulseq-bundle.js"></script>'
32
+ _WEBVIEW_TAG = '<script src="webview-bundle.js"></script>'
33
+ _BODY_TAG = "<body>"
34
+
35
+ _VALID_GRAD_UNITS = {"Hz/m", "mT/m", "G/cm"}
36
+ # The two plain names Python has always accepted, resolved the way the page's
37
+ # own "system" theme resolves light and dark.
38
+ _THEME_ALIASES = {"light": "githublight", "dark": "github"}
39
+ SequenceSource = Union[str, bytes, bytearray, memoryview]
40
+
41
+
42
+ def _read_resource(name: str) -> str:
43
+ """Read one of the page's files from resources/, or from web/ in a checkout."""
44
+ for directory in (_RESOURCES_DIR, _WEB_DIR):
45
+ path = directory / name
46
+ if path.is_file():
47
+ return path.read_text(encoding="utf-8")
48
+ raise FileNotFoundError(
49
+ f"{name} not found in {_RESOURCES_DIR}. "
50
+ "Build it with: npm run build:web (from the repo root)."
51
+ )
52
+
53
+
54
+ def _normalize_grad_disp(unit: str) -> str:
55
+ """Return a viewer-supported gradient unit."""
56
+ return unit if unit in _VALID_GRAD_UNITS else "mT/m"
57
+
58
+
59
+ def _page_theme(theme: Optional[str]) -> Optional[str]:
60
+ """Map a Python theme name to one of the page's theme names."""
61
+ if not theme:
62
+ return None
63
+ return _THEME_ALIASES.get(str(theme), str(theme))
64
+
65
+
66
+ def _finite_or_none(value: Any) -> Optional[float]:
67
+ try:
68
+ number = float(value)
69
+ except (TypeError, ValueError):
70
+ return None
71
+ return number if math.isfinite(number) else None
72
+
73
+
74
+ def _time_range_option(time_range: Any) -> List[Optional[float]]:
75
+ """Seconds, with None for an open end; ``[0, None]`` keeps the page's first view."""
76
+ try:
77
+ start, end = time_range
78
+ except (TypeError, ValueError):
79
+ return [0.0, None]
80
+ return [_finite_or_none(start), _finite_or_none(end)]
81
+
82
+
83
+ def _script_json(value: Any) -> str:
84
+ """JSON for an inline script, with no character the HTML parser acts on."""
85
+ return (
86
+ json.dumps(value, allow_nan=False, separators=(",", ":"))
87
+ .replace("<", "\\u003c")
88
+ .replace(">", "\\u003e")
89
+ .replace("&", "\\u0026")
90
+ )
91
+
92
+
93
+ def _inline_script(source: str) -> str:
94
+ # A literal "</script" would end the element early; "<\/" means the same in JS.
95
+ return "<script>\n" + re.sub(r"</(?=script)", r"<\\/", source, flags=re.IGNORECASE) + "\n</script>"
96
+
97
+
98
+ def _inline_style(source: str) -> str:
99
+ # Likewise for "</style"; "\/" is an escaped "/" in CSS.
100
+ return "<style>\n" + re.sub(r"</(?=style)", r"<\\/", source, flags=re.IGNORECASE) + "\n</style>"
101
+
102
+
103
+ def _replace_tags(page: str, replacements: dict) -> str:
104
+ """Replace each tag, which must occur exactly once, in a single pass."""
105
+ for tag in replacements:
106
+ if page.count(tag) != 1:
107
+ raise ValueError(f"index.html no longer has exactly one {tag!r}")
108
+ pattern = "|".join(re.escape(tag) for tag in replacements)
109
+ return re.sub(pattern, lambda match: replacements[match.group(0)], page)
110
+
111
+
112
+ def _build_html(
113
+ sequence_source: SequenceSource,
114
+ *,
115
+ theme: Optional[str] = None,
116
+ inject_bundle: bool = True,
117
+ label: str = "",
118
+ show_blocks: bool = False,
119
+ time_range: tuple = (0, float("inf")),
120
+ time_disp: str = "s",
121
+ grad_disp: str = "mT/m",
122
+ ) -> str:
123
+ """Assemble the complete viewer HTML.
124
+
125
+ Parameters
126
+ ----------
127
+ sequence_source : str or bytes-like
128
+ Raw text ``.seq`` content or binary ``.bseq`` bytes.
129
+ theme : str or None
130
+ Viewer theme: ``"system"``, ``"light"``, ``"dark"``, or one of the
131
+ page's themes (``"onelight"``, ``"onedark"``, ``"dracula"``,
132
+ ``"nord"``, ``"githublight"``, ``"github"``). None uses the page's
133
+ remembered or system theme.
134
+ inject_bundle : bool
135
+ If True, inline the stylesheet and both scripts so the page is
136
+ self-contained. If False, keep the page's relative references to
137
+ ``styles.css``, ``pulseq-bundle.js`` and ``webview-bundle.js``, for a
138
+ page served next to copies of those files.
139
+ label : str
140
+ Sequence file name: names exported files, and titles the page when
141
+ the sequence defines no ``Name``.
142
+ show_blocks : bool
143
+ Initial block‑boundary visibility.
144
+ time_range : tuple[float, float]
145
+ Initial viewport range in seconds. ``(0, inf)`` keeps the viewer's
146
+ own first view; an infinite end means the end of the sequence.
147
+ time_disp : str
148
+ Initial time display unit (``"s"``, ``"ms"``, ``"us"``).
149
+ grad_disp : str
150
+ Initial gradient display unit (``"mT/m"``, the default, ``"Hz/m"``
151
+ or ``"G/cm"``).
152
+ """
153
+ page = _read_resource("index.html")
154
+ source_is_text = isinstance(sequence_source, str)
155
+ file_name = label or ("sequence.seq" if source_is_text else "sequence.bseq")
156
+ if source_is_text:
157
+ preload = {"text": sequence_source, "fileName": file_name}
158
+ else:
159
+ source_b64 = base64.b64encode(bytes(sequence_source)).decode("ascii")
160
+ preload = {"base64": source_b64, "fileName": file_name}
161
+ page_theme = _page_theme(theme)
162
+ options = {
163
+ "theme": page_theme,
164
+ "timeUnit": time_disp,
165
+ "gradUnit": _normalize_grad_disp(grad_disp),
166
+ "showBlocks": bool(show_blocks),
167
+ "timeRange": _time_range_option(time_range),
168
+ }
169
+ # Runs before both bundles and the page's own script, which read these.
170
+ host_script = (
171
+ "<script>"
172
+ 'window._SEQEYES_HOST="python";'
173
+ f"window._SEQEYES_PRELOAD={_script_json(preload)};"
174
+ f"window._SEQEYES_OPTIONS={_script_json(options)};"
175
+ "</script>\n"
176
+ )
177
+
178
+ replacements = {_PULSEQ_TAG: host_script + _PULSEQ_TAG}
179
+ if inject_bundle:
180
+ replacements = {
181
+ _STYLESHEET_TAG: _inline_style(_read_resource("styles.css")),
182
+ _PULSEQ_TAG: host_script + _inline_script(_read_resource("pulseq-bundle.js")),
183
+ _WEBVIEW_TAG: _inline_script(_read_resource("webview-bundle.js")),
184
+ }
185
+ # Themed from the first paint; the page's script then applies the same choice.
186
+ if page_theme and page_theme != "system" and re.fullmatch(r"[\w-]+", page_theme):
187
+ replacements[_BODY_TAG] = f'<body class="theme-{page_theme}">'
188
+ return _replace_tags(page, replacements)
189
+
190
+
191
+ class SeqEyesViewer:
192
+ """Interactive Pulseq sequence viewer for Jupyter notebook output.
193
+
194
+ Normally you don't create this directly — call ``seqeyes.set()``
195
+ once, then use ``seq.plot(...)`` on any ``pypulseq.Sequence``.
196
+
197
+ Parameters
198
+ ----------
199
+ sequence_source : str or bytes-like
200
+ Raw text ``.seq`` content or binary ``.bseq`` bytes.
201
+ label : str
202
+ Sequence file name: names exported files, and titles the viewer when
203
+ the sequence defines no ``Name``.
204
+ show_blocks : bool
205
+ Whether to show block‑boundary lines initially.
206
+ time_range : tuple[float, float]
207
+ Initial time viewport ``(start_sec, end_sec)``. ``(0, inf)``
208
+ keeps the viewer's own first view (the first TR when one is found).
209
+ time_disp : str
210
+ Time axis unit — ``"s"``, ``"ms"``, or ``"us"``.
211
+ grad_disp : str
212
+ Gradient axis unit — ``"mT/m"`` (default), ``"Hz/m"``, or ``"G/cm"``.
213
+ theme : str or None
214
+ Colour theme: ``"system"``, ``"light"``, ``"dark"``, ``"onelight"``,
215
+ ``"onedark"``, ``"dracula"``, ``"nord"``, ``"githublight"`` or
216
+ ``"github"``.
217
+ width : str
218
+ CSS width of the iframe (e.g. ``"100%"``).
219
+ height : str
220
+ CSS height of the iframe (e.g. ``"550px"``).
221
+ """
222
+
223
+ def __init__(
224
+ self,
225
+ sequence_source: SequenceSource,
226
+ *,
227
+ label: str = "",
228
+ show_blocks: bool = False,
229
+ time_range: tuple = (0, float("inf")),
230
+ time_disp: str = "s",
231
+ grad_disp: str = "mT/m",
232
+ theme: Optional[str] = None,
233
+ width: str = "100%",
234
+ height: str = "550px",
235
+ ) -> None:
236
+ if not isinstance(sequence_source, (str, bytes, bytearray, memoryview)):
237
+ raise TypeError("sequence_source must be .seq text or .bseq bytes")
238
+ self._sequence_source = sequence_source
239
+ self._label = label
240
+ self._show_blocks = show_blocks
241
+ self._time_range = time_range
242
+ self._time_disp = time_disp
243
+ self._grad_disp = _normalize_grad_disp(grad_disp)
244
+ self._theme = theme
245
+ self._width = width
246
+ self._height = height
247
+
248
+ @classmethod
249
+ def from_file(cls, path: Union[str, os.PathLike[str]], **kwargs: Any) -> "SeqEyesViewer":
250
+ """Create a viewer from a local ``.seq`` or ``.bseq`` file."""
251
+ source_path = Path(path)
252
+ if source_path.suffix.lower() not in {".seq", ".bseq"}:
253
+ raise ValueError("SeqEyesViewer.from_file() expects a .seq or .bseq file")
254
+ if not source_path.is_file():
255
+ raise FileNotFoundError(source_path)
256
+ kwargs.setdefault("label", source_path.name)
257
+ source: SequenceSource = (
258
+ source_path.read_text(encoding="utf-8")
259
+ if source_path.suffix.lower() == ".seq"
260
+ else source_path.read_bytes()
261
+ )
262
+ return cls(source, **kwargs)
263
+
264
+ # ── Jupyter integration ───────────────────────────────────────────
265
+
266
+ def _repr_html_(self) -> str:
267
+ """Return an HTML iframe that Jupyter renders inline."""
268
+ html = _build_html(
269
+ self._sequence_source,
270
+ theme=self._theme,
271
+ label=self._label,
272
+ show_blocks=self._show_blocks,
273
+ time_range=self._time_range,
274
+ time_disp=self._time_disp,
275
+ grad_disp=self._grad_disp,
276
+ )
277
+ b64 = base64.b64encode(html.encode("utf-8")).decode("ascii")
278
+ return (
279
+ f'<iframe src="data:text/html;base64,{b64}" '
280
+ f'width="{self._width}" height="{self._height}" '
281
+ f'frameborder="0" '
282
+ f'style="border:none;max-width:100%;overflow:hidden" '
283
+ f'title="SeqEyes Viewer">'
284
+ f"</iframe>"
285
+ )
286
+
287
+ def _ipython_display_(self) -> None:
288
+ """IPython display hook."""
289
+ from IPython.display import HTML, display
290
+
291
+ display(HTML(self._repr_html_()))
292
+
293
+ # ── Convenience ────────────────────────────────────────────────────
294
+
295
+ def show(self) -> "SeqEyesViewer":
296
+ """Display the viewer (useful in IPython when auto‑display is off)."""
297
+ from IPython.display import display
298
+
299
+ display(self)
300
+ return self
301
+
302
+ # ── Direct HTML access (for debugging / custom embedding) ──────────
303
+
304
+ def to_html(self, *, inject_bundle: bool = True) -> str:
305
+ """Return the full standalone HTML string (for saving to a file).
306
+
307
+ With ``inject_bundle=False`` the page references ``styles.css``,
308
+ ``pulseq-bundle.js`` and ``webview-bundle.js`` by relative URL
309
+ instead of inlining them, so it works only next to copies of them.
310
+ """
311
+ return _build_html(
312
+ self._sequence_source,
313
+ theme=self._theme,
314
+ inject_bundle=inject_bundle,
315
+ label=self._label,
316
+ show_blocks=self._show_blocks,
317
+ time_range=self._time_range,
318
+ time_disp=self._time_disp,
319
+ grad_disp=self._grad_disp,
320
+ )