diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index 4b302d6..1052ba8 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -11,6 +11,7 @@ on:
permissions:
contents: write
+ id-token: write
jobs:
build:
@@ -71,10 +72,59 @@ jobs:
```
Requires MATLAB R2022a+. See [DEPLOY.md](matlab/DEPLOY.md) for details.
+ **Python:** Install from PyPI:
+ ```bash
+ pip install seqeyes-python
+ ```
+
## Changes
See [commits since last release](https://github.com/${{ github.repository }}/compare/${{ github.event.before }}...${{ github.ref_name }}).
files: |
seqeyes-web.vsix
seqeyes-*.mltbx
+ python/dist/*
generate_release_notes: true
+
+ python-build:
+ name: Build Python package
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.12'
+ cache: pip
+ cache-dependency-path: python/pyproject.toml
+
+ - name: Install build tools
+ run: |
+ python -m pip install --upgrade pip
+ pip install build
+
+ - name: Build wheel and sdist
+ run: cd python && python -m build
+
+ - name: Upload Python artifacts
+ uses: actions/upload-artifact@v4
+ with:
+ name: seqeyes-python-dist
+ path: python/dist/*
+
+ publish-pypi:
+ name: Publish to PyPI
+ needs: python-build
+ runs-on: ubuntu-latest
+ if: startsWith(github.ref, 'refs/tags/v')
+ steps:
+ - name: Download Python artifacts
+ uses: actions/download-artifact@v4
+ with:
+ name: seqeyes-python-dist
+ path: dist/
+
+ - name: Publish to PyPI
+ uses: pypa/gh-action-pypi-publish@release/v1
diff --git a/.github/workflows/python-tests.yml b/.github/workflows/python-tests.yml
new file mode 100644
index 0000000..2918c0c
--- /dev/null
+++ b/.github/workflows/python-tests.yml
@@ -0,0 +1,45 @@
+name: Python Package Tests
+
+on:
+ pull_request:
+ branches: [main, master]
+ push:
+ branches: [main, master, 'feature/**', 'fix/**']
+ workflow_dispatch:
+
+jobs:
+ test:
+ name: Python ${{ matrix.python-version }}
+ runs-on: ubuntu-latest
+ timeout-minutes: 15
+ strategy:
+ fail-fast: false
+ matrix:
+ python-version: ['3.10', '3.11', '3.12']
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v5
+
+ - name: Setup Python ${{ matrix.python-version }}
+ uses: actions/setup-python@v5
+ with:
+ python-version: ${{ matrix.python-version }}
+ cache: pip
+ cache-dependency-path: python/pyproject.toml
+
+ - name: Install package with test dependencies
+ run: |
+ python -m pip install --upgrade pip
+ pip install -e "./python[test,pypulseq]"
+
+ - name: Run tests
+ run: python -m pytest python/tests/ -v
+
+ - name: Upload test results
+ uses: actions/upload-artifact@v5
+ if: ${{ !cancelled() }}
+ with:
+ name: python-test-results-py${{ matrix.python-version }}
+ path: python/.pytest_results/
+ retention-days: 14
diff --git a/.gitignore b/.gitignore
index be14e4b..62e2b35 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,8 +8,11 @@ dist/
*.mltbx
*.asc
.vscode-test/
+.vscode/
test-results/
playwright-report/
performance-results/
matlab/pulseq-bundle.js
.DS_Store
+__pycache__/
+.pytest_cache/
\ No newline at end of file
diff --git a/.vscode/launch.json b/.vscode/launch.json
deleted file mode 100644
index 1d975cc..0000000
--- a/.vscode/launch.json
+++ /dev/null
@@ -1,30 +0,0 @@
-{
- "version": "0.2.0",
- "configurations": [
- {
- "name": "Run Extension",
- "type": "extensionHost",
- "request": "launch",
- "args": [
- "--extensionDevelopmentPath=${workspaceFolder}"
- ],
- "outFiles": [
- "${workspaceFolder}/out/**/*.js"
- ],
- "preLaunchTask": "${defaultBuildTask}"
- },
- {
- "name": "Extension Tests",
- "type": "extensionHost",
- "request": "launch",
- "args": [
- "--extensionDevelopmentPath=${workspaceFolder}",
- "--extensionTestsPath=${workspaceFolder}/out/test/suite/index"
- ],
- "outFiles": [
- "${workspaceFolder}/out/test/**/*.js"
- ],
- "preLaunchTask": "${defaultBuildTask}"
- }
- ]
-}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
deleted file mode 100644
index 9a4fd8e..0000000
--- a/.vscode/tasks.json
+++ /dev/null
@@ -1,24 +0,0 @@
-{
- "version": "2.0.0",
- "tasks": [
- {
- "type": "npm",
- "script": "watch",
- "problemMatcher": "$tsc-watch",
- "isBackground": true,
- "presentation": {
- "reveal": "never"
- },
- "group": {
- "kind": "build",
- "isDefault": true
- }
- },
- {
- "type": "npm",
- "script": "compile",
- "problemMatcher": "$tsc",
- "group": "build"
- }
- ]
-}
diff --git a/README.md b/README.md
index aa1b9e3..5fc8fe3 100644
--- a/README.md
+++ b/README.md
@@ -73,6 +73,41 @@ open('spiral_inout.seq') % or doubleβclick in Current Folder
All the same features as the browser & VS Code versions β 7 channels, kβspace viewer, themes, tooltips β rendered inside a native MATLAB figure. Requires R2022a+.
+## π Python Package
+
+Interactive Pulseq sequence viewer for Jupyter notebooks and Python scripts β a dropβin replacement for `pypulseq.Sequence.plot()`. Renders directly in notebook cell output or opens in your default browser.
+
+### Install
+
+```bash
+pip install seqeyes-python
+```
+
+For pypulseq integration:
+
+```bash
+pip install seqeyes-python[pypulseq]
+```
+
+### Usage
+
+```python
+import seqeyes
+
+# Enable SeqEyes (once per session) β seq.plot() is now interactive
+seqeyes.set(theme="dark", time_disp="ms")
+
+# Build your sequence with pypulseq as usual
+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
+
+# Restore matplotlib at any time
+seqeyes.reset()
+```
+
+All the same features as the other versions β interactive waveforms, kβspace viewer, themes, tooltips β rendered directly in Jupyter or your browser. Requires Python β₯ 3.9.
+
## Features
- **Custom editor for `.seq` files** β opens automatically on doubleβclick
diff --git a/package.json b/package.json
index 86d09b3..6e4d2fc 100644
--- a/package.json
+++ b/package.json
@@ -2,7 +2,7 @@
"name": "seqeyes-web",
"displayName": "SeqEyes",
"description": "Visualize Pulseq MRI sequences inside VS Code β inspect sequence diagrams, k-space trajectorieswith interactive user interface.",
- "version": "0.1.17",
+ "version": "0.2.0",
"publisher": "SeqEyesDeveloper",
"license": "MIT",
"icon": "images/logo.png",
diff --git a/python/README.md b/python/README.md
new file mode 100644
index 0000000..e6406ef
--- /dev/null
+++ b/python/README.md
@@ -0,0 +1,94 @@
+# SeqEyes β Interactive Pulseq MRI Sequence Viewer for Python
+
+**SeqEyes** is a lightweight Python package that provides interactive
+visualization of Pulseq (.seq) MRI sequences in Jupyter notebooks.
+It works as a dropβin replacement for `pypulseq.Sequence.plot()`,
+rendering an interactive viewer directly in Jupyter notebook cell
+output β just like Plotly.
+
+## Features
+
+- ποΈ **Interactive waveform viewer** β zoom, pan, perβchannel amplitude zoom
+- π **Tooltip** with block details (RF amplitude, gradient strength, ADC params)
+- πΊοΈ **3D kβspace trajectory viewer** β rotate, zoom, depthβsorted rendering
+- π¨ **8 colour themes** β system, light, dark, dracula, nord, and more
+- π **Unit conversion** β time (s / ms / Β΅s), gradient (Hz/m / mT/m / G/cm)
+- π **Minimap** with TR/TE overlay and viewport indicator
+- πΎ **Export to standalone HTML** β shareable, no Python needed
+- π **Dropβin pypulseq integration** β `seq.plot()` just works
+
+## Installation
+
+```bash
+pip install seqeyes-python
+```
+
+For pypulseq integration:
+```bash
+pip install seqeyes-python[pypulseq]
+```
+
+## Quick Start
+
+```python
+import seqeyes
+
+# Enable SeqEyes (once per session) β seq.plot() is now interactive
+seqeyes.set(theme="dark", time_disp="ms")
+
+# Build your sequence with pypulseq as usual
+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
+
+# Restore matplotlib at any time
+seqeyes.reset()
+```
+
+In a plain `.py` script (no Jupyter), `seq.plot()` opens the viewer
+in a desktop popβup window (requires `pywebview`) or falls back to
+your default browser.
+
+### Using without pypulseq
+
+```python
+from seqeyes import SeqEyesViewer
+
+with open('my_sequence.seq') as f:
+ viewer = SeqEyesViewer(f.read(), theme="dark")
+
+viewer # renders inline in Jupyter
+```
+
+## API Reference
+
+| Function | Description |
+|---|---|
+| `seqeyes.set(**kwargs)` | Enable SeqEyes and set global defaults (`theme`, `show_blocks`, `time_disp`, `grad_disp`, `time_range`) |
+| `seqeyes.reset()` | Restore matplotlib `seq.plot()` and clear all defaults |
+| `SeqEyesViewer(seq_text, ...)` | Lowβlevel viewer for raw `.seq` content (no pypulseq needed) |
+
+## Viewer Controls
+
+| Action | How |
+|---|---|
+| Zoom | Scroll wheel |
+| Pan | Click + drag |
+| Amplitude zoom (per channel) | Ctrl + scroll wheel |
+| Tooltip | Hover over waveform |
+| Toggle channels | Click legend labels |
+| KβSpace viewer | Click "KβSpace" button |
+| Rotate kβspace | Click + drag in panel |
+| Minimap navigation | Click on minimap strip |
+| Open another file | π Open button |
+
+## Requirements
+
+- Python β₯ 3.9
+- numpy β₯ 1.21
+- pypulseq β₯ 1.4 (optional, for `seq.plot()` integration)
+- pywebview β₯ 5 (optional, for native desktop popβup windows)
+
+## License
+
+MIT
diff --git a/python/examples/demo.ipynb b/python/examples/demo.ipynb
new file mode 100644
index 0000000..370aa9d
--- /dev/null
+++ b/python/examples/demo.ipynb
@@ -0,0 +1,394 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "id": "e697bb42",
+ "metadata": {},
+ "source": [
+ "# SeqEyes β Interactive Pulseq MRI Sequence Viewer\n",
+ "\n",
+ "Dropβin replacement for `pypulseq.Sequence.plot()`.\n",
+ "\n",
+ "```python\n",
+ "import seqeyes\n",
+ "seqeyes.set(theme=\"dark\") # enable + set defaults\n",
+ "\n",
+ "seq.plot() # interactive viewer inline\n",
+ "seq.plot(show_blocks=True) # perβcall overrides\n",
+ "seq.plot(time_range=(0, 0.05)) # zoom to first 50 ms\n",
+ "\n",
+ "seqeyes.reset() # back to matplotlib\n",
+ "```\n",
+ "\n",
+ "**Plain `.py` script?** `seq.plot()` opens your browser automatically."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 1,
+ "id": "699af581",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "d:\\MIniconda\\envs\\NUM\\Lib\\site-packages\\sigpy\\config.py:27: UserWarning: Importing cupy.cuda.cudnn failed. For more details, see the error stack below:\n",
+ "DLL load failed while importing cudnn: The specified module could not be found.\n",
+ " warnings.warn(\n"
+ ]
+ },
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "SeqEyes 0.1.0 β seq.plot() is now interactive!\n",
+ "GRE: 320 blocks | EPI: 390 blocks | Radial: 405 blocks\n"
+ ]
+ }
+ ],
+ "source": [
+ "import seqeyes\n",
+ "import numpy as np\n",
+ "import pypulseq as pp\n",
+ "\n",
+ "# ββ Enable SeqEyes (once per session) ββ\n",
+ "seqeyes.set(time_disp=\"ms\", grad_disp=\"kHz/m\")\n",
+ "print(f\"SeqEyes {seqeyes.__version__} β seq.plot() is now interactive!\")\n",
+ "\n",
+ "# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n",
+ "# 1. GRE (from pypulseq/examples/scripts/write_gre.py)\n",
+ "# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n",
+ "fov_gre = 256e-3; n_x_gre = 64; n_y_gre = 64\n",
+ "flip_gre = 10; slice_thickness = 3e-3; tr_gre = 12e-3; te_gre = 5e-3\n",
+ "\n",
+ "system_gre = pp.Opts(max_grad=28, grad_unit='mT/m', max_slew=150, slew_unit='T/m/s',\n",
+ " rf_ringdown_time=20e-6, rf_dead_time=100e-6, adc_dead_time=10e-6)\n",
+ "seq_gre = pp.Sequence(system_gre)\n",
+ "\n",
+ "rf, gz, _ = pp.make_sinc_pulse(flip_angle=np.deg2rad(flip_gre), duration=3e-3,\n",
+ " slice_thickness=slice_thickness, apodization=0.42,\n",
+ " time_bw_product=4, system=system_gre, return_gz=True,\n",
+ " delay=system_gre.rf_dead_time, use='excitation')\n",
+ "\n",
+ "delta_kx = 1 / fov_gre; delta_ky = 1 / fov_gre\n",
+ "gx = pp.make_trapezoid(channel='x', flat_area=n_x_gre * delta_kx, flat_time=3.2e-3, system=system_gre)\n",
+ "adc = pp.make_adc(num_samples=n_x_gre, duration=gx.flat_time, delay=gx.rise_time, system=system_gre)\n",
+ "gx_pre = pp.make_trapezoid(channel='x', area=-gx.area / 2, duration=1e-3, system=system_gre)\n",
+ "gz_reph = pp.make_trapezoid(channel='z', area=-gz.area / 2, duration=1e-3, system=system_gre)\n",
+ "gx_spoil = pp.make_trapezoid(channel='x', area=2 * n_x_gre * delta_kx, system=system_gre)\n",
+ "gz_spoil = pp.make_trapezoid(channel='z', area=4 / slice_thickness, system=system_gre)\n",
+ "phase_areas = (np.arange(n_y_gre) - n_y_gre / 2) * delta_ky\n",
+ "\n",
+ "te_delay = te_gre - (pp.calc_duration(gz, rf) - pp.calc_rf_center(rf)[0] - rf.delay) - pp.calc_duration(gx_pre) - pp.calc_duration(gx) / 2 - pp.eps\n",
+ "te_delay = np.ceil(te_delay / seq_gre.grad_raster_time) * seq_gre.grad_raster_time\n",
+ "tr_delay = tr_gre - pp.calc_duration(gz, rf) - pp.calc_duration(gx_pre) - pp.calc_duration(gx) - te_delay\n",
+ "tr_delay = np.ceil(tr_delay / seq_gre.grad_raster_time) * seq_gre.grad_raster_time\n",
+ "\n",
+ "rf_phase = 0; rf_inc = 0\n",
+ "for i_phase in range(n_y_gre):\n",
+ " rf.phase_offset = rf_phase / 180 * np.pi\n",
+ " adc.phase_offset = rf_phase / 180 * np.pi\n",
+ " rf_inc = divmod(rf_inc + 117, 360.0)[1]\n",
+ " rf_phase = divmod(rf_phase + rf_inc, 360.0)[1]\n",
+ " seq_gre.add_block(rf, gz)\n",
+ " gy_pre = pp.make_trapezoid(channel='y', area=phase_areas[i_phase], duration=pp.calc_duration(gx_pre), system=system_gre)\n",
+ " seq_gre.add_block(gx_pre, gy_pre, gz_reph)\n",
+ " seq_gre.add_block(pp.make_delay(te_delay))\n",
+ " seq_gre.add_block(gx, adc)\n",
+ " gy_pre.amplitude = -gy_pre.amplitude\n",
+ " seq_gre.add_block(pp.make_delay(tr_delay), gx_spoil, gy_pre, gz_spoil)\n",
+ "\n",
+ "# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n",
+ "# 2. EPI (from pypulseq/examples/scripts/write_epi.py)\n",
+ "# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n",
+ "fov_epi = 220e-3; n_x_epi = 64; n_y_epi = 64; n_slices = 3\n",
+ "\n",
+ "system_epi = pp.Opts(max_grad=32, grad_unit='mT/m', max_slew=130, slew_unit='T/m/s',\n",
+ " rf_ringdown_time=30e-6, rf_dead_time=100e-6)\n",
+ "seq_epi = pp.Sequence(system_epi)\n",
+ "\n",
+ "rf_epi, gz_epi, _ = pp.make_sinc_pulse(flip_angle=np.pi / 2, system=system_epi, duration=3e-3,\n",
+ " slice_thickness=slice_thickness, apodization=0.5,\n",
+ " time_bw_product=4, return_gz=True,\n",
+ " delay=system_epi.rf_dead_time, use='excitation')\n",
+ "\n",
+ "dkx = 1 / fov_epi; dky = 1 / fov_epi; k_width = n_x_epi * dkx\n",
+ "adc_dwell = 4e-6; adc_duration = n_x_epi * adc_dwell\n",
+ "gx_flat = np.ceil(adc_duration * 1e5) * 1e-5\n",
+ "gx_epi = pp.make_trapezoid(channel='x', system=system_epi, amplitude=k_width / adc_duration, flat_time=gx_flat)\n",
+ "adc_epi = pp.make_adc(num_samples=n_x_epi, duration=adc_duration,\n",
+ " delay=gx_epi.rise_time + gx_flat / 2 - (adc_duration - adc_dwell) / 2)\n",
+ "pre_time = 8e-4\n",
+ "gx_pre_epi = pp.make_trapezoid(channel='x', system=system_epi, area=-gx_epi.area / 2, duration=pre_time)\n",
+ "gz_reph_epi = pp.make_trapezoid(channel='z', system=system_epi, area=-gz_epi.area / 2, duration=pre_time)\n",
+ "gy_pre_epi = pp.make_trapezoid(channel='y', system=system_epi, area=-n_y_epi / 2 * dky, duration=pre_time)\n",
+ "gy_blip_dur = np.ceil(2 * np.sqrt(dky / system_epi.max_slew) / 10e-6) * 10e-6\n",
+ "gy_epi = pp.make_trapezoid(channel='y', system=system_epi, area=dky, duration=gy_blip_dur)\n",
+ "\n",
+ "for i_slice in range(n_slices):\n",
+ " rf_epi.freq_offset = gz_epi.amplitude * slice_thickness * (i_slice - (n_slices - 1) / 2)\n",
+ " seq_epi.add_block(rf_epi, gz_epi)\n",
+ " seq_epi.add_block(gx_pre_epi, gy_pre_epi, gz_reph_epi)\n",
+ " for _ in range(n_y_epi):\n",
+ " seq_epi.add_block(gx_epi, adc_epi)\n",
+ " seq_epi.add_block(gy_epi)\n",
+ " gx_epi.amplitude = -gx_epi.amplitude\n",
+ "\n",
+ "# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n",
+ "# 3. Radial GRE (from pypulseq/examples/scripts/write_radial_gre.py)\n",
+ "# βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ\n",
+ "fov_rad = 260e-3; n_x_rad = 64; flip_rad = 10; n_spokes = 60; n_dummy = 20\n",
+ "tr_rad = 20e-3; te_rad = 8e-3\n",
+ "\n",
+ "system_rad = pp.Opts(max_grad=28, grad_unit='mT/m', max_slew=120, slew_unit='T/m/s',\n",
+ " rf_ringdown_time=20e-6, rf_dead_time=100e-6, adc_dead_time=10e-6)\n",
+ "seq_rad = pp.Sequence(system_rad)\n",
+ "\n",
+ "rf_rad, gz_rad, _ = pp.make_sinc_pulse(apodization=0.5, duration=4e-3,\n",
+ " flip_angle=np.deg2rad(flip_rad),\n",
+ " slice_thickness=slice_thickness, system=system_rad,\n",
+ " time_bw_product=4, return_gz=True,\n",
+ " delay=system_rad.rf_dead_time, use='excitation')\n",
+ "\n",
+ "dkx_rad = 1 / fov_rad\n",
+ "gx_rad = pp.make_trapezoid(channel='x', flat_area=n_x_rad * dkx_rad, flat_time=6.4e-3 / 5, system=system_rad)\n",
+ "adc_rad = pp.make_adc(num_samples=n_x_rad, duration=gx_rad.flat_time, delay=gx_rad.rise_time, system=system_rad)\n",
+ "gx_pre_rad = pp.make_trapezoid(channel='x', area=-gx_rad.area / 2 - dkx_rad / 2, duration=2e-3, system=system_rad)\n",
+ "gz_reph_rad = pp.make_trapezoid(channel='z', area=-gz_rad.area / 2, duration=2e-3, system=system_rad)\n",
+ "gx_spoil_rad = pp.make_trapezoid(channel='x', area=0.5 * n_x_rad * dkx_rad, system=system_rad)\n",
+ "gz_spoil_rad = pp.make_trapezoid(channel='z', area=4 / slice_thickness, system=system_rad)\n",
+ "\n",
+ "te_delay_rad = te_rad - pp.calc_duration(gx_pre_rad) - gz_rad.fall_time - gz_rad.flat_time / 2 - pp.calc_duration(gx_rad) / 2\n",
+ "te_delay_rad = np.ceil(te_delay_rad / seq_rad.grad_raster_time) * seq_rad.grad_raster_time\n",
+ "tr_delay_rad = tr_rad - pp.calc_duration(gx_pre_rad) - pp.calc_duration(gz_rad) - pp.calc_duration(gx_rad) - te_delay_rad\n",
+ "tr_delay_rad = np.ceil(tr_delay_rad / seq_rad.grad_raster_time) * seq_rad.grad_raster_time\n",
+ "\n",
+ "spoke_angle = np.pi / n_spokes\n",
+ "rf_phase = 0; rf_inc = 0\n",
+ "for i_spoke in range(-n_dummy, n_spokes + 1):\n",
+ " rf_rad.phase_offset = rf_phase / 180 * np.pi\n",
+ " adc_rad.phase_offset = rf_phase / 180 * np.pi\n",
+ " rf_inc = divmod(rf_inc + 117, 360.0)[1]\n",
+ " rf_phase = divmod(rf_inc + rf_phase, 360.0)[1]\n",
+ " seq_rad.add_block(rf_rad, gz_rad)\n",
+ " phi = spoke_angle * (i_spoke - 1)\n",
+ " seq_rad.add_block(*pp.rotate(gx_pre_rad, gz_reph_rad, angle=phi, axis='z'))\n",
+ " seq_rad.add_block(pp.make_delay(te_delay_rad))\n",
+ " if i_spoke > 0:\n",
+ " seq_rad.add_block(*pp.rotate(gx_rad, adc_rad, angle=phi, axis='z'))\n",
+ " else:\n",
+ " seq_rad.add_block(*pp.rotate(gx_rad, angle=phi, axis='z'))\n",
+ " seq_rad.add_block(*pp.rotate(gx_spoil_rad, gz_spoil_rad, pp.make_delay(tr_delay_rad), angle=phi, axis='z'))\n",
+ "\n",
+ "print(f\"GRE: {len(seq_gre.block_events)} blocks | \"\n",
+ " f\"EPI: {len(seq_epi.block_events)} blocks | \"\n",
+ " f\"Radial: {len(seq_rad.block_events)} blocks\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "304160f9",
+ "metadata": {},
+ "source": [
+ "## 1. Gradient Echo β `write_gre.py`\n",
+ "\n",
+ "Classic Cartesian GRE with sinc excitation, phase encoding, and\n",
+ "gradient spoiling. 64Γ64 matrix, TE=5 ms, TR=12 ms."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 2,
+ "id": "9c2645c0",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stderr",
+ "output_type": "stream",
+ "text": [
+ "d:\\MIniconda\\envs\\NUM\\Lib\\site-packages\\IPython\\core\\display.py:447: UserWarning: Consider using IPython.display.IFrame instead\n",
+ " warnings.warn(\"Consider using IPython.display.IFrame instead\")\n"
+ ]
+ },
+ {
+ "data": {
+ "text/html": [
+ ""
+ ],
+ "text/plain": [
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "seq_gre.plot(time_range=(0, tr_gre), time_disp=\"ms\", grad_disp=\"kHz/m\", theme=\"dark\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "31cffaa6",
+ "metadata": {},
+ "source": [
+ "## 2. Echo Planar Imaging β `write_epi.py`\n",
+ "\n",
+ "Singleβshot EPI with blipped phase encoding, alternating readout\n",
+ "polarity. 64Γ64, 3 slices, 220 mm FOV."
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 3,
+ "id": "4fa512a7",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ ""
+ ],
+ "text/plain": [
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "seq_epi.plot(time_disp=\"ms\", grad_disp=\"kHz/m\", theme=\"dark\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "fdb2b647",
+ "metadata": {},
+ "source": [
+ "## 3. Radial GRE β `write_radial_gre.py`\n",
+ "\n",
+ "NonβCartesian radial trajectory with 60 spokes, rotated readout\n",
+ "gradients, and RF spoiling. Open the **KβSpace** panel!"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 4,
+ "id": "2750f1cf",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ ""
+ ],
+ "text/plain": [
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "seq_rad.plot(time_disp=\"ms\", grad_disp=\"kHz/m\", theme=\"dark\")"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "0dc32d72",
+ "metadata": {},
+ "source": [
+ "## Customize the view\n",
+ "\n",
+ "`seq.plot()` accepts the same arguments as pypulseq's original plot,\n",
+ "plus a `theme` keyword:\n",
+ "\n",
+ "| Argument | Default | Description |\n",
+ "|---|---|---|\n",
+ "| `show_blocks` | `False` | Show blockβboundary lines |\n",
+ "| `time_range` | `(0, inf)` | Zoom to `(start_sec, end_sec)` |\n",
+ "| `time_disp` | `\"s\"` | Time unit: `\"s\"`, `\"ms\"`, `\"us\"` |\n",
+ "| `grad_disp` | `\"kHz/m\"` | Gradient unit: `\"Hz/m\"`, `\"kHz/m\"`, `\"mT/m\"`, `\"G/cm\"` |\n",
+ "| `theme` | `\"system\"` | `\"light\"`, `\"dark\"`, `\"dracula\"`, `\"nord\"`, ... |"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 5,
+ "id": "a8ef3961",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/html": [
+ ""
+ ],
+ "text/plain": [
+ ""
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "# Zoom to first TR with block boundaries + custom units\n",
+ "seqeyes.set(show_blocks=True, time_disp=\"ms\", grad_disp=\"kHz/m\")\n",
+ "seq_gre.plot(time_range=(0, tr_gre), theme=\"dark\")\n",
+ "seqeyes.reset() # restore defaults"
+ ]
+ },
+ {
+ "cell_type": "markdown",
+ "id": "ec80c99c",
+ "metadata": {},
+ "source": [
+ "## Viewer Controls\n",
+ "\n",
+ "| Action | How |\n",
+ "|---|---|\n",
+ "| **Zoom** | Scroll wheel |\n",
+ "| **Pan** | Click + drag |\n",
+ "| **Amplitude zoom (per channel)** | Ctrl + scroll wheel |\n",
+ "| **Tooltip** | Hover over waveform |\n",
+ "| **Toggle channels** | Click legend labels |\n",
+ "| **Block boundaries** | Check \"Blocks\" in toolbar |\n",
+ "| **KβSpace 3D viewer** | Click \"KβSpace\" button |\n",
+ "| **Rotate kβspace** | Click + drag in panel |\n",
+ "| **Change time unit** | Dropdown (s / ms / Β΅s) |\n",
+ "| **Change gradient unit** | Dropdown (Hz/m / mT/m / G/cm) |\n",
+ "| **Change theme** | Dropdown in toolbar |\n",
+ "| **Open another .seq** | π Open button |\n",
+ "\n",
+ "## Plain `.py` script?\n",
+ "\n",
+ "In a standalone Python script (no Jupyter), `seq.plot()` opens the\n",
+ "viewer in your default web browser. See `examples/demo.py`."
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "NUM",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.11.13"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/python/examples/demo.py b/python/examples/demo.py
new file mode 100644
index 0000000..2ecbc40
--- /dev/null
+++ b/python/examples/demo.py
@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""
+demo.py β SeqEyes with 3 official pypulseq example sequences.
+Run: python demo.py
+Each ``seq.plot()`` opens an interactive viewer in your default browser.
+"""
+
+import seqeyes
+import numpy as np
+import pypulseq as pp
+
+# ββ Enable SeqEyes (once per session) βββββββββββββββββββββββββββββββββ
+seqeyes.set(time_disp="ms", grad_disp="kHz/m")
+print(f"SeqEyes {seqeyes.__version__} β seq.plot() is now interactive!")
+
+
+# ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+# 1. GRE (from pypulseq/examples/scripts/write_gre.py)
+# ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+fov_gre = 256e-3; n_x_gre = 64; n_y_gre = 64
+flip_gre = 10; slice_thickness = 3e-3; tr_gre = 12e-3; te_gre = 5e-3
+
+system_gre = pp.Opts(max_grad=28, grad_unit='mT/m', max_slew=150, slew_unit='T/m/s',
+ rf_ringdown_time=20e-6, rf_dead_time=100e-6, adc_dead_time=10e-6)
+seq_gre = pp.Sequence(system_gre)
+
+rf, gz, _ = pp.make_sinc_pulse(flip_angle=np.deg2rad(flip_gre), duration=3e-3,
+ slice_thickness=slice_thickness, apodization=0.42,
+ time_bw_product=4, system=system_gre, return_gz=True,
+ delay=system_gre.rf_dead_time, use='excitation')
+
+delta_kx = 1 / fov_gre; delta_ky = 1 / fov_gre
+gx = pp.make_trapezoid(channel='x', flat_area=n_x_gre * delta_kx, flat_time=3.2e-3, system=system_gre)
+adc = pp.make_adc(num_samples=n_x_gre, duration=gx.flat_time, delay=gx.rise_time, system=system_gre)
+gx_pre = pp.make_trapezoid(channel='x', area=-gx.area / 2, duration=1e-3, system=system_gre)
+gz_reph = pp.make_trapezoid(channel='z', area=-gz.area / 2, duration=1e-3, system=system_gre)
+gx_spoil = pp.make_trapezoid(channel='x', area=2 * n_x_gre * delta_kx, system=system_gre)
+gz_spoil = pp.make_trapezoid(channel='z', area=4 / slice_thickness, system=system_gre)
+phase_areas = (np.arange(n_y_gre) - n_y_gre / 2) * delta_ky
+
+te_delay = te_gre - (pp.calc_duration(gz, rf) - pp.calc_rf_center(rf)[0] - rf.delay) - pp.calc_duration(gx_pre) - pp.calc_duration(gx) / 2 - pp.eps
+te_delay = np.ceil(te_delay / seq_gre.grad_raster_time) * seq_gre.grad_raster_time
+tr_delay = tr_gre - pp.calc_duration(gz, rf) - pp.calc_duration(gx_pre) - pp.calc_duration(gx) - te_delay
+tr_delay = np.ceil(tr_delay / seq_gre.grad_raster_time) * seq_gre.grad_raster_time
+
+rf_phase = 0; rf_inc = 0
+for i_phase in range(n_y_gre):
+ rf.phase_offset = rf_phase / 180 * np.pi
+ adc.phase_offset = rf_phase / 180 * np.pi
+ rf_inc = divmod(rf_inc + 117, 360.0)[1]
+ rf_phase = divmod(rf_phase + rf_inc, 360.0)[1]
+ seq_gre.add_block(rf, gz)
+ gy_pre = pp.make_trapezoid(channel='y', area=phase_areas[i_phase], duration=pp.calc_duration(gx_pre), system=system_gre)
+ seq_gre.add_block(gx_pre, gy_pre, gz_reph)
+ seq_gre.add_block(pp.make_delay(te_delay))
+ seq_gre.add_block(gx, adc)
+ gy_pre.amplitude = -gy_pre.amplitude
+ seq_gre.add_block(pp.make_delay(tr_delay), gx_spoil, gy_pre, gz_spoil)
+
+print("1/3 GRE sequence β opening viewer ...")
+seq_gre.plot(time_range=(0, 0.05)) # zoom to first 50 ms
+
+
+# ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+# 2. EPI (from pypulseq/examples/scripts/write_epi.py)
+# ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+fov_epi = 220e-3; n_x_epi = 64; n_y_epi = 64; n_slices = 3
+
+system_epi = pp.Opts(max_grad=32, grad_unit='mT/m', max_slew=130, slew_unit='T/m/s',
+ rf_ringdown_time=30e-6, rf_dead_time=100e-6)
+seq_epi = pp.Sequence(system_epi)
+
+rf_epi, gz_epi, _ = pp.make_sinc_pulse(flip_angle=np.pi / 2, system=system_epi, duration=3e-3,
+ slice_thickness=slice_thickness, apodization=0.5,
+ time_bw_product=4, return_gz=True,
+ delay=system_epi.rf_dead_time, use='excitation')
+
+dkx = 1 / fov_epi; dky = 1 / fov_epi; k_width = n_x_epi * dkx
+adc_dwell = 4e-6; adc_duration = n_x_epi * adc_dwell
+gx_flat = np.ceil(adc_duration * 1e5) * 1e-5
+gx_epi = pp.make_trapezoid(channel='x', system=system_epi, amplitude=k_width / adc_duration, flat_time=gx_flat)
+adc_epi = pp.make_adc(num_samples=n_x_epi, duration=adc_duration,
+ delay=gx_epi.rise_time + gx_flat / 2 - (adc_duration - adc_dwell) / 2)
+pre_time = 8e-4
+gx_pre_epi = pp.make_trapezoid(channel='x', system=system_epi, area=-gx_epi.area / 2, duration=pre_time)
+gz_reph_epi = pp.make_trapezoid(channel='z', system=system_epi, area=-gz_epi.area / 2, duration=pre_time)
+gy_pre_epi = pp.make_trapezoid(channel='y', system=system_epi, area=-n_y_epi / 2 * dky, duration=pre_time)
+gy_blip_dur = np.ceil(2 * np.sqrt(dky / system_epi.max_slew) / 10e-6) * 10e-6
+gy_epi = pp.make_trapezoid(channel='y', system=system_epi, area=dky, duration=gy_blip_dur)
+
+for i_slice in range(n_slices):
+ rf_epi.freq_offset = gz_epi.amplitude * slice_thickness * (i_slice - (n_slices - 1) / 2)
+ seq_epi.add_block(rf_epi, gz_epi)
+ seq_epi.add_block(gx_pre_epi, gy_pre_epi, gz_reph_epi)
+ for _ in range(n_y_epi):
+ seq_epi.add_block(gx_epi, adc_epi)
+ seq_epi.add_block(gy_epi)
+ gx_epi.amplitude = -gx_epi.amplitude
+
+print("2/3 EPI sequence β opening viewer ...")
+seq_epi.plot(show_blocks=True) # show block boundaries
+
+
+# ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+# 3. Radial GRE (from pypulseq/examples/scripts/write_radial_gre.py)
+# ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+fov_rad = 260e-3; n_x_rad = 64; flip_rad = 10; n_spokes = 60; n_dummy = 20
+tr_rad = 20e-3; te_rad = 8e-3
+
+system_rad = pp.Opts(max_grad=28, grad_unit='mT/m', max_slew=120, slew_unit='T/m/s',
+ rf_ringdown_time=20e-6, rf_dead_time=100e-6, adc_dead_time=10e-6)
+seq_rad = pp.Sequence(system_rad)
+
+rf_rad, gz_rad, _ = pp.make_sinc_pulse(apodization=0.5, duration=4e-3,
+ flip_angle=np.deg2rad(flip_rad),
+ slice_thickness=slice_thickness, system=system_rad,
+ time_bw_product=4, return_gz=True,
+ delay=system_rad.rf_dead_time, use='excitation')
+
+dkx_rad = 1 / fov_rad
+gx_rad = pp.make_trapezoid(channel='x', flat_area=n_x_rad * dkx_rad, flat_time=6.4e-3 / 5, system=system_rad)
+adc_rad = pp.make_adc(num_samples=n_x_rad, duration=gx_rad.flat_time, delay=gx_rad.rise_time, system=system_rad)
+gx_pre_rad = pp.make_trapezoid(channel='x', area=-gx_rad.area / 2 - dkx_rad / 2, duration=2e-3, system=system_rad)
+gz_reph_rad = pp.make_trapezoid(channel='z', area=-gz_rad.area / 2, duration=2e-3, system=system_rad)
+gx_spoil_rad = pp.make_trapezoid(channel='x', area=0.5 * n_x_rad * dkx_rad, system=system_rad)
+gz_spoil_rad = pp.make_trapezoid(channel='z', area=4 / slice_thickness, system=system_rad)
+
+te_delay_rad = te_rad - pp.calc_duration(gx_pre_rad) - gz_rad.fall_time - gz_rad.flat_time / 2 - pp.calc_duration(gx_rad) / 2
+te_delay_rad = np.ceil(te_delay_rad / seq_rad.grad_raster_time) * seq_rad.grad_raster_time
+tr_delay_rad = tr_rad - pp.calc_duration(gx_pre_rad) - pp.calc_duration(gz_rad) - pp.calc_duration(gx_rad) - te_delay_rad
+tr_delay_rad = np.ceil(tr_delay_rad / seq_rad.grad_raster_time) * seq_rad.grad_raster_time
+
+spoke_angle = np.pi / n_spokes
+rf_phase = 0; rf_inc = 0
+for i_spoke in range(-n_dummy, n_spokes + 1):
+ rf_rad.phase_offset = rf_phase / 180 * np.pi
+ adc_rad.phase_offset = rf_phase / 180 * np.pi
+ rf_inc = divmod(rf_inc + 117, 360.0)[1]
+ rf_phase = divmod(rf_inc + rf_phase, 360.0)[1]
+ seq_rad.add_block(rf_rad, gz_rad)
+ phi = spoke_angle * (i_spoke - 1)
+ seq_rad.add_block(*pp.rotate(gx_pre_rad, gz_reph_rad, angle=phi, axis='z'))
+ seq_rad.add_block(pp.make_delay(te_delay_rad))
+ if i_spoke > 0:
+ seq_rad.add_block(*pp.rotate(gx_rad, adc_rad, angle=phi, axis='z'))
+ else:
+ seq_rad.add_block(*pp.rotate(gx_rad, angle=phi, axis='z'))
+ seq_rad.add_block(*pp.rotate(gx_spoil_rad, gz_spoil_rad, pp.make_delay(tr_delay_rad), angle=phi, axis='z'))
+
+print("3/3 Radial GRE sequence β opening viewer ...")
+seq_rad.plot(theme="dark") # overrides 'system' default from set()
+
+print("\nDone! 3 viewer tabs opened.")
diff --git a/python/pyproject.toml b/python/pyproject.toml
new file mode 100644
index 0000000..4de487a
--- /dev/null
+++ b/python/pyproject.toml
@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "seqeyes-python"
+version = "0.2.0"
+description = "Interactive Pulseq MRI sequence viewer for Jupyter β lightweight, beautiful, replaces seq.plot() in pypulseq."
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+ {name = "SeqEyes Developers"},
+]
+keywords = ["pulseq", "mri", "sequence", "visualization", "k-space", "gradient", "seqeyes"]
+classifiers = [
+ "Development Status :: 3 - Alpha",
+ "Intended Audience :: Science/Research",
+ "License :: OSI Approved :: MIT License",
+ "Programming Language :: Python :: 3",
+ "Programming Language :: Python :: 3.9",
+ "Programming Language :: Python :: 3.10",
+ "Programming Language :: Python :: 3.11",
+ "Programming Language :: Python :: 3.12",
+ "Topic :: Scientific/Engineering :: Medical Science Apps.",
+ "Topic :: Scientific/Engineering :: Visualization",
+ "Framework :: Jupyter",
+]
+requires-python = ">=3.9"
+dependencies = [
+ "numpy>=1.21",
+]
+
+[project.optional-dependencies]
+pypulseq = ["pypulseq>=1.4"]
+desktop = ["pywebview>=5"]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/bughht/seqeyes_plugin"
+Repository = "https://github.com/bughht/seqeyes_plugin"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/seqeyes"]
+artifacts = ["src/seqeyes/resources/*"]
+
+[tool.hatch.build.targets.sdist]
+artifacts = ["src/seqeyes/resources/*"]
diff --git a/python/src/seqeyes/__init__.py b/python/src/seqeyes/__init__.py
new file mode 100644
index 0000000..1cde2fe
--- /dev/null
+++ b/python/src/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"
diff --git a/python/src/seqeyes/_plot.py b/python/src/seqeyes/_plot.py
new file mode 100644
index 0000000..434aef8
--- /dev/null
+++ b/python/src/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 ""
diff --git a/python/src/seqeyes/_renderer.py b/python/src/seqeyes/_renderer.py
new file mode 100644
index 0000000..7400960
--- /dev/null
+++ b/python/src/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 ````.
+ 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 = ""
+ if inject_bundle and bundle_placeholder in template:
+ bundle_js = _find_bundle()
+ template = template.replace(
+ bundle_placeholder,
+ f"",
+ )
+ 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(
+ "",
+ f"\n",
+ )
+
+ # 3. Apply theme if specified
+ if theme:
+ template = template.replace(
+ "