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 CHANGED
@@ -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.0"
32
+ __version__ = "0.4.2"
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 = "Hz/m",
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
- Generates a self‑contained HTML string that Jupyter displays inline via
5
- ``_repr_html_()``, exactly the same mechanism Plotly uses. The viewer is
6
- an iframe embedding the SeqEyes web UI with sequence data injected.
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
- _VIEWER_TEMPLATE_PATH = _RESOURCES_DIR / "viewer.html"
21
-
22
- # pulseq-bundle.js lives in the repo root; during dev we read it directly.
23
- # When installed as a package, a copy should be placed in resources/.
24
- _BUNDLE_CANDIDATES = [
25
- _RESOURCES_DIR / "pulseq-bundle.js",
26
- Path(__file__).resolve().parent.parent.parent.parent / "web" / "pulseq-bundle.js",
27
- Path.cwd() / "web" / "pulseq-bundle.js",
28
- ]
29
- # The label-row module shared with the web renderers. build:web copies it into
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 _find_bundle() -> str:
41
- """Locate and read the pulseq-bundle.js file."""
42
- for p in _BUNDLE_CANDIDATES:
43
- if p.is_file():
44
- return p.read_text(encoding="utf-8")
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
- "pulseq-bundle.js not found. "
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 _find_labels_script() -> str:
53
- """Locate and read the label-row script (SeqEyesLabels)."""
54
- for p in _LABELS_SCRIPT_CANDIDATES:
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 _read_viewer_template() -> str:
65
- """Read the standalone viewer HTML template."""
66
- if _VIEWER_TEMPLATE_PATH.is_file():
67
- return _VIEWER_TEMPLATE_PATH.read_text(encoding="utf-8")
68
- alt = Path.cwd() / "python" / "src" / "seqeyes" / "resources" / "viewer.html"
69
- if alt.is_file():
70
- return alt.read_text(encoding="utf-8")
71
- raise FileNotFoundError(
72
- f"Viewer template not found at {_VIEWER_TEMPLATE_PATH}. "
73
- "Ensure the package is installed correctly."
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 _normalize_grad_disp(unit: str) -> str:
78
- """Return a viewer-supported gradient unit."""
79
- return unit if unit in _VALID_GRAD_UNITS else "Hz/m"
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 = "Hz/m",
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
- CSS theme class to apply to ``<body>``.
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 pulseq-bundle.js parser into the HTML.
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
- Display label (injected as JS variable, not yet rendered).
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 (``"Hz/m"``, ``"mT/m"``, ``"G/cm"``).
150
+ Initial gradient display unit (``"mT/m"``, the default, ``"Hz/m"``
151
+ or ``"G/cm"``).
113
152
  """
114
- template = _read_viewer_template()
115
- grad_disp = _normalize_grad_disp(grad_disp)
153
+ page = _read_resource("index.html")
116
154
  source_is_text = isinstance(sequence_source, str)
117
- source_bytes = sequence_source.encode("utf-8") if source_is_text else bytes(sequence_source)
118
- source_b64 = base64.b64encode(source_bytes).decode("ascii")
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
- template = template.replace(
158
- "</body>",
159
- f"<script>{opts_block}</script>\n</body>",
160
- )
161
-
162
- # 3. Apply theme if specified
163
- if theme:
164
- template = template.replace(
165
- "<body>",
166
- f'<body class="theme-{theme}">',
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
- return template
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
- Display label (not yet rendered on the viewer).
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
- shows the whole sequence.
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 — ``"Hz/m"``, ``"mT/m"``, or ``"G/cm"``.
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 = "Hz/m",
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,