Metadata-Version: 2.4
Name: seqeyes-python
Version: 0.2.10
Summary: Interactive Pulseq MRI sequence viewer for Jupyter — lightweight, beautiful, replaces seq.plot() in pypulseq.
Project-URL: Homepage, https://github.com/bughht/seqeyes_plugin
Project-URL: Repository, https://github.com/bughht/seqeyes_plugin
Author: SeqEyes Developers
License: MIT
Keywords: gradient,k-space,mri,pulseq,seqeyes,sequence,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Jupyter
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Requires-Dist: numpy>=1.21
Provides-Extra: desktop
Requires-Dist: pywebview>=5; extra == 'desktop'
Provides-Extra: pypulseq
Requires-Dist: pypulseq>=1.4; extra == 'pypulseq'
Provides-Extra: test
Requires-Dist: pytest>=7; extra == 'test'
Description-Content-Type: text/markdown

# SeqEyes — Interactive Pulseq MRI Sequence Viewer for Python

**SeqEyes** is a lightweight Python package that provides interactive
visualization of Pulseq text (`.seq`) and binary (`.bseq`) 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
```

Open either supported file format directly:

```python
from seqeyes import SeqEyesViewer

SeqEyesViewer.from_file("my_sequence.seq", theme="dark")
SeqEyesViewer.from_file("my_sequence.bseq", theme="dark")
```

## 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(source, ...)` | Low-level viewer for raw `.seq` text or `.bseq` bytes |
| `SeqEyesViewer.from_file(path, ...)` | Open a local `.seq` or `.bseq` file without pypulseq |

## 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
