seqeyes-python 0.4.0__py3-none-any.whl → 0.4.2__py3-none-any.whl
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.
- seqeyes/__init__.py +1 -1
- seqeyes/_plot.py +1 -1
- seqeyes/_renderer.py +143 -116
- seqeyes/resources/index.html +3179 -0
- seqeyes/resources/pulseq-bundle.js +11 -4
- seqeyes/resources/styles.css +332 -0
- seqeyes/resources/webview-bundle.js +1770 -47
- {seqeyes_python-0.4.0.dist-info → seqeyes_python-0.4.2.dist-info}/METADATA +31 -6
- seqeyes_python-0.4.2.dist-info/RECORD +10 -0
- {seqeyes_python-0.4.0.dist-info → seqeyes_python-0.4.2.dist-info}/WHEEL +1 -1
- seqeyes/resources/seqeyes-labels.js +0 -448
- seqeyes/resources/viewer.html +0 -1748
- seqeyes_python-0.4.0.dist-info/RECORD +0 -10
seqeyes/__init__.py
CHANGED
seqeyes/_plot.py
CHANGED
|
@@ -120,7 +120,7 @@ def _ensure_patched() -> None:
|
|
|
120
120
|
show_blocks: bool = False,
|
|
121
121
|
time_range: Any = (0, float("inf")),
|
|
122
122
|
time_disp: str = "s",
|
|
123
|
-
grad_disp: str = "
|
|
123
|
+
grad_disp: str = "mT/m",
|
|
124
124
|
**kwargs: Any,
|
|
125
125
|
) -> None:
|
|
126
126
|
# Merge globals — per‑call args take precedence
|
seqeyes/_renderer.py
CHANGED
|
@@ -1,82 +1,112 @@
|
|
|
1
1
|
"""
|
|
2
2
|
_renderer.py — Jupyter HTML renderer for the SeqEyes interactive viewer.
|
|
3
3
|
|
|
4
|
-
|
|
5
|
-
``
|
|
6
|
-
|
|
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.
|
|
7
10
|
"""
|
|
8
11
|
|
|
9
12
|
from __future__ import annotations
|
|
10
13
|
|
|
11
14
|
import base64
|
|
12
15
|
import json
|
|
16
|
+
import math
|
|
13
17
|
import os
|
|
18
|
+
import re
|
|
14
19
|
from pathlib import Path
|
|
15
|
-
from typing import Any, Optional, Union
|
|
20
|
+
from typing import Any, List, Optional, Union
|
|
16
21
|
|
|
17
22
|
|
|
18
23
|
# ── Paths ─────────────────────────────────────────────────────────────────
|
|
19
24
|
_RESOURCES_DIR = Path(__file__).resolve().parent / "resources"
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
# resources/; a source checkout can read it from the webview assets instead.
|
|
31
|
-
_LABELS_SCRIPT_CANDIDATES = [
|
|
32
|
-
_RESOURCES_DIR / "seqeyes-labels.js",
|
|
33
|
-
Path(__file__).resolve().parent.parent.parent.parent / "src" / "editor" / "webview" / "assets" / "labels.js",
|
|
34
|
-
Path.cwd() / "src" / "editor" / "webview" / "assets" / "labels.js",
|
|
35
|
-
]
|
|
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
|
+
|
|
36
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"}
|
|
37
39
|
SequenceSource = Union[str, bytes, bytearray, memoryview]
|
|
38
40
|
|
|
39
41
|
|
|
40
|
-
def
|
|
41
|
-
"""
|
|
42
|
-
for
|
|
43
|
-
|
|
44
|
-
|
|
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")
|
|
45
48
|
raise FileNotFoundError(
|
|
46
|
-
"
|
|
47
|
-
"Build it with: npm run build:web (from the repo root)
|
|
48
|
-
"or copy it to python/src/seqeyes/resources/"
|
|
49
|
+
f"{name} not found in {_RESOURCES_DIR}. "
|
|
50
|
+
"Build it with: npm run build:web (from the repo root)."
|
|
49
51
|
)
|
|
50
52
|
|
|
51
53
|
|
|
52
|
-
def
|
|
53
|
-
"""
|
|
54
|
-
|
|
55
|
-
if p.is_file():
|
|
56
|
-
return p.read_text(encoding="utf-8")
|
|
57
|
-
raise FileNotFoundError(
|
|
58
|
-
"seqeyes-labels.js not found. "
|
|
59
|
-
"Build it with: npm run build:web (from the repo root), "
|
|
60
|
-
"or copy src/editor/webview/assets/labels.js to python/src/seqeyes/resources/seqeyes-labels.js"
|
|
61
|
-
)
|
|
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"
|
|
62
57
|
|
|
63
58
|
|
|
64
|
-
def
|
|
65
|
-
"""
|
|
66
|
-
if
|
|
67
|
-
return
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
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")
|
|
74
90
|
)
|
|
75
91
|
|
|
76
92
|
|
|
77
|
-
def
|
|
78
|
-
"""
|
|
79
|
-
return
|
|
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)
|
|
80
110
|
|
|
81
111
|
|
|
82
112
|
def _build_html(
|
|
@@ -88,7 +118,7 @@ def _build_html(
|
|
|
88
118
|
show_blocks: bool = False,
|
|
89
119
|
time_range: tuple = (0, float("inf")),
|
|
90
120
|
time_disp: str = "s",
|
|
91
|
-
grad_disp: str = "
|
|
121
|
+
grad_disp: str = "mT/m",
|
|
92
122
|
) -> str:
|
|
93
123
|
"""Assemble the complete viewer HTML.
|
|
94
124
|
|
|
@@ -97,76 +127,65 @@ def _build_html(
|
|
|
97
127
|
sequence_source : str or bytes-like
|
|
98
128
|
Raw text ``.seq`` content or binary ``.bseq`` bytes.
|
|
99
129
|
theme : str or None
|
|
100
|
-
|
|
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.
|
|
101
134
|
inject_bundle : bool
|
|
102
|
-
If True, inline the
|
|
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.
|
|
103
139
|
label : str
|
|
104
|
-
|
|
140
|
+
Sequence file name: names exported files, and titles the page when
|
|
141
|
+
the sequence defines no ``Name``.
|
|
105
142
|
show_blocks : bool
|
|
106
143
|
Initial block‑boundary visibility.
|
|
107
144
|
time_range : tuple[float, float]
|
|
108
|
-
Initial viewport range in seconds.
|
|
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.
|
|
109
147
|
time_disp : str
|
|
110
148
|
Initial time display unit (``"s"``, ``"ms"``, ``"us"``).
|
|
111
149
|
grad_disp : str
|
|
112
|
-
Initial gradient display unit (``"
|
|
150
|
+
Initial gradient display unit (``"mT/m"``, the default, ``"Hz/m"``
|
|
151
|
+
or ``"G/cm"``).
|
|
113
152
|
"""
|
|
114
|
-
|
|
115
|
-
grad_disp = _normalize_grad_disp(grad_disp)
|
|
153
|
+
page = _read_resource("index.html")
|
|
116
154
|
source_is_text = isinstance(sequence_source, str)
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
# 1. Inject the pulseq-bundle.js
|
|
121
|
-
bundle_placeholder = "<!-- PULSEQ_BUNDLE_PLACEHOLDER -->"
|
|
122
|
-
if inject_bundle and bundle_placeholder in template:
|
|
123
|
-
bundle_js = _find_bundle()
|
|
124
|
-
template = template.replace(
|
|
125
|
-
bundle_placeholder,
|
|
126
|
-
f"<script>\n{bundle_js}\n</script>",
|
|
127
|
-
)
|
|
128
|
-
elif bundle_placeholder in template:
|
|
129
|
-
template = template.replace(bundle_placeholder, "")
|
|
130
|
-
|
|
131
|
-
labels_placeholder = "<!-- LABELS_SCRIPT_PLACEHOLDER -->"
|
|
132
|
-
if inject_bundle and labels_placeholder in template:
|
|
133
|
-
template = template.replace(
|
|
134
|
-
labels_placeholder,
|
|
135
|
-
f"<script>\n{_find_labels_script()}\n</script>",
|
|
136
|
-
)
|
|
137
|
-
elif labels_placeholder in template:
|
|
138
|
-
template = template.replace(labels_placeholder, "")
|
|
139
|
-
|
|
140
|
-
# 2. Build options injection block (sequence data + display opts)
|
|
141
|
-
opts = [
|
|
142
|
-
f"window.SEQEYES_RAW_B64 = {json.dumps(source_b64)};",
|
|
143
|
-
f"window.SEQEYES_SOURCE_KIND = {json.dumps('text' if source_is_text else 'bytes')};",
|
|
144
|
-
f"window.SEQEYES_SOURCE_NAME = {json.dumps(label)};",
|
|
145
|
-
f"window.SEQEYES_LABEL = {json.dumps(label)};",
|
|
146
|
-
f"window.SEQEYES_SHOW_BLOCKS = {json.dumps(show_blocks)};",
|
|
147
|
-
f"window.SEQEYES_TIME_RANGE = {json.dumps(list(time_range))};",
|
|
148
|
-
f"window.SEQEYES_TIME_DISP = {json.dumps(time_disp)};",
|
|
149
|
-
f"window.SEQEYES_GRAD_DISP = {json.dumps(grad_disp)};",
|
|
150
|
-
]
|
|
151
|
-
opts_block = "\n".join(opts)
|
|
152
|
-
|
|
153
|
-
data_placeholder = "/* SEQEYES_DATA_PLACEHOLDER */"
|
|
154
|
-
if data_placeholder in template:
|
|
155
|
-
template = template.replace(data_placeholder, opts_block)
|
|
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}
|
|
156
158
|
else:
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
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
|
+
)
|
|
168
177
|
|
|
169
|
-
|
|
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)
|
|
170
189
|
|
|
171
190
|
|
|
172
191
|
class SeqEyesViewer:
|
|
@@ -180,18 +199,21 @@ class SeqEyesViewer:
|
|
|
180
199
|
sequence_source : str or bytes-like
|
|
181
200
|
Raw text ``.seq`` content or binary ``.bseq`` bytes.
|
|
182
201
|
label : str
|
|
183
|
-
|
|
202
|
+
Sequence file name: names exported files, and titles the viewer when
|
|
203
|
+
the sequence defines no ``Name``.
|
|
184
204
|
show_blocks : bool
|
|
185
205
|
Whether to show block‑boundary lines initially.
|
|
186
206
|
time_range : tuple[float, float]
|
|
187
207
|
Initial time viewport ``(start_sec, end_sec)``. ``(0, inf)``
|
|
188
|
-
|
|
208
|
+
keeps the viewer's own first view (the first TR when one is found).
|
|
189
209
|
time_disp : str
|
|
190
210
|
Time axis unit — ``"s"``, ``"ms"``, or ``"us"``.
|
|
191
211
|
grad_disp : str
|
|
192
|
-
Gradient axis unit — ``"
|
|
212
|
+
Gradient axis unit — ``"mT/m"`` (default), ``"Hz/m"``, or ``"G/cm"``.
|
|
193
213
|
theme : str or None
|
|
194
|
-
Colour theme
|
|
214
|
+
Colour theme: ``"system"``, ``"light"``, ``"dark"``, ``"onelight"``,
|
|
215
|
+
``"onedark"``, ``"dracula"``, ``"nord"``, ``"githublight"`` or
|
|
216
|
+
``"github"``.
|
|
195
217
|
width : str
|
|
196
218
|
CSS width of the iframe (e.g. ``"100%"``).
|
|
197
219
|
height : str
|
|
@@ -206,7 +228,7 @@ class SeqEyesViewer:
|
|
|
206
228
|
show_blocks: bool = False,
|
|
207
229
|
time_range: tuple = (0, float("inf")),
|
|
208
230
|
time_disp: str = "s",
|
|
209
|
-
grad_disp: str = "
|
|
231
|
+
grad_disp: str = "mT/m",
|
|
210
232
|
theme: Optional[str] = None,
|
|
211
233
|
width: str = "100%",
|
|
212
234
|
height: str = "550px",
|
|
@@ -280,7 +302,12 @@ class SeqEyesViewer:
|
|
|
280
302
|
# ── Direct HTML access (for debugging / custom embedding) ──────────
|
|
281
303
|
|
|
282
304
|
def to_html(self, *, inject_bundle: bool = True) -> str:
|
|
283
|
-
"""Return the full standalone HTML string (for saving to a file).
|
|
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
|
+
"""
|
|
284
311
|
return _build_html(
|
|
285
312
|
self._sequence_source,
|
|
286
313
|
theme=self._theme,
|