seqeyes-python 0.4.1__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/_renderer.py +138 -112
- seqeyes/resources/index.html +3179 -0
- seqeyes/resources/pulseq-bundle.js +1 -1
- seqeyes/resources/styles.css +332 -0
- seqeyes/resources/webview-bundle.js +593 -43
- {seqeyes_python-0.4.1.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.1.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.1.dist-info/RECORD +0 -10
seqeyes/__init__.py
CHANGED
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(
|
|
@@ -97,77 +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
150
|
Initial gradient display unit (``"mT/m"``, the default, ``"Hz/m"``
|
|
113
151
|
or ``"G/cm"``).
|
|
114
152
|
"""
|
|
115
|
-
|
|
116
|
-
grad_disp = _normalize_grad_disp(grad_disp)
|
|
153
|
+
page = _read_resource("index.html")
|
|
117
154
|
source_is_text = isinstance(sequence_source, str)
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
# 1. Inject the pulseq-bundle.js
|
|
122
|
-
bundle_placeholder = "<!-- PULSEQ_BUNDLE_PLACEHOLDER -->"
|
|
123
|
-
if inject_bundle and bundle_placeholder in template:
|
|
124
|
-
bundle_js = _find_bundle()
|
|
125
|
-
template = template.replace(
|
|
126
|
-
bundle_placeholder,
|
|
127
|
-
f"<script>\n{bundle_js}\n</script>",
|
|
128
|
-
)
|
|
129
|
-
elif bundle_placeholder in template:
|
|
130
|
-
template = template.replace(bundle_placeholder, "")
|
|
131
|
-
|
|
132
|
-
labels_placeholder = "<!-- LABELS_SCRIPT_PLACEHOLDER -->"
|
|
133
|
-
if inject_bundle and labels_placeholder in template:
|
|
134
|
-
template = template.replace(
|
|
135
|
-
labels_placeholder,
|
|
136
|
-
f"<script>\n{_find_labels_script()}\n</script>",
|
|
137
|
-
)
|
|
138
|
-
elif labels_placeholder in template:
|
|
139
|
-
template = template.replace(labels_placeholder, "")
|
|
140
|
-
|
|
141
|
-
# 2. Build options injection block (sequence data + display opts)
|
|
142
|
-
opts = [
|
|
143
|
-
f"window.SEQEYES_RAW_B64 = {json.dumps(source_b64)};",
|
|
144
|
-
f"window.SEQEYES_SOURCE_KIND = {json.dumps('text' if source_is_text else 'bytes')};",
|
|
145
|
-
f"window.SEQEYES_SOURCE_NAME = {json.dumps(label)};",
|
|
146
|
-
f"window.SEQEYES_LABEL = {json.dumps(label)};",
|
|
147
|
-
f"window.SEQEYES_SHOW_BLOCKS = {json.dumps(show_blocks)};",
|
|
148
|
-
f"window.SEQEYES_TIME_RANGE = {json.dumps(list(time_range))};",
|
|
149
|
-
f"window.SEQEYES_TIME_DISP = {json.dumps(time_disp)};",
|
|
150
|
-
f"window.SEQEYES_GRAD_DISP = {json.dumps(grad_disp)};",
|
|
151
|
-
]
|
|
152
|
-
opts_block = "\n".join(opts)
|
|
153
|
-
|
|
154
|
-
data_placeholder = "/* SEQEYES_DATA_PLACEHOLDER */"
|
|
155
|
-
if data_placeholder in template:
|
|
156
|
-
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}
|
|
157
158
|
else:
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
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
|
+
)
|
|
169
177
|
|
|
170
|
-
|
|
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)
|
|
171
189
|
|
|
172
190
|
|
|
173
191
|
class SeqEyesViewer:
|
|
@@ -181,18 +199,21 @@ class SeqEyesViewer:
|
|
|
181
199
|
sequence_source : str or bytes-like
|
|
182
200
|
Raw text ``.seq`` content or binary ``.bseq`` bytes.
|
|
183
201
|
label : str
|
|
184
|
-
|
|
202
|
+
Sequence file name: names exported files, and titles the viewer when
|
|
203
|
+
the sequence defines no ``Name``.
|
|
185
204
|
show_blocks : bool
|
|
186
205
|
Whether to show block‑boundary lines initially.
|
|
187
206
|
time_range : tuple[float, float]
|
|
188
207
|
Initial time viewport ``(start_sec, end_sec)``. ``(0, inf)``
|
|
189
|
-
|
|
208
|
+
keeps the viewer's own first view (the first TR when one is found).
|
|
190
209
|
time_disp : str
|
|
191
210
|
Time axis unit — ``"s"``, ``"ms"``, or ``"us"``.
|
|
192
211
|
grad_disp : str
|
|
193
212
|
Gradient axis unit — ``"mT/m"`` (default), ``"Hz/m"``, or ``"G/cm"``.
|
|
194
213
|
theme : str or None
|
|
195
|
-
Colour theme
|
|
214
|
+
Colour theme: ``"system"``, ``"light"``, ``"dark"``, ``"onelight"``,
|
|
215
|
+
``"onedark"``, ``"dracula"``, ``"nord"``, ``"githublight"`` or
|
|
216
|
+
``"github"``.
|
|
196
217
|
width : str
|
|
197
218
|
CSS width of the iframe (e.g. ``"100%"``).
|
|
198
219
|
height : str
|
|
@@ -281,7 +302,12 @@ class SeqEyesViewer:
|
|
|
281
302
|
# ── Direct HTML access (for debugging / custom embedding) ──────────
|
|
282
303
|
|
|
283
304
|
def to_html(self, *, inject_bundle: bool = True) -> str:
|
|
284
|
-
"""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
|
+
"""
|
|
285
311
|
return _build_html(
|
|
286
312
|
self._sequence_source,
|
|
287
313
|
theme=self._theme,
|