effusive 0.1.1__py3-none-any.whl

effusive/__init__.py

@@ -0,0 +1 @@
+"""Effusive python package for the napari viewer."""

effusive/assets/__init__.py

@@ -0,0 +1,28 @@
+"""Effusive assets module.
+
+Contains SVG icons and other static assets used by the application.
+"""
+
+from pathlib import Path
+
+
+def load_svg(name: str) -> str:
+    """Load an SVG icon by name.
+
+    Parameters
+    ----------
+    name : str
+        Name of the SVG file (without .svg extension).
+
+    Returns
+    -------
+    str
+        Contents of the SVG file.
+
+    Raises
+    ------
+    FileNotFoundError
+        If the SVG file does not exist.
+    """
+    svg_path = Path(__file__).parent / f"{name}.svg"
+    return svg_path.read_text()

effusive/assets/aperture.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"/><path d="m14.31 8 5.74 9.94"/><path d="M9.69 8h11.48"/><path d="m7.38 12 5.74-9.94"/><path d="M9.69 16 3.95 6.06"/><path d="M14.31 16H2.83"/><path d="m16.62 12-5.74 9.94"/></svg>

effusive/assets/audio-waveform.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-audio-waveform-icon lucide-audio-waveform"><path d="M2 13a2 2 0 0 0 2-2V7a2 2 0 0 1 4 0v13a2 2 0 0 0 4 0V4a2 2 0 0 1 4 0v13a2 2 0 0 0 4 0v-4a2 2 0 0 1 2-2"/></svg>

effusive/assets/circle-check.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="12" cy="12" r="10"/>
+  <path d="m9 12 2 2 4-4"/>
+</svg>

effusive/assets/circle-x.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <circle cx="12" cy="12" r="10"/>
+  <path d="m15 9-6 6"/>
+  <path d="m9 9 6 6"/>
+</svg>

effusive/assets/cpu.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-cpu-icon lucide-cpu"><path d="M12 20v2"/><path d="M12 2v2"/><path d="M17 20v2"/><path d="M17 2v2"/><path d="M2 12h2"/><path d="M2 17h2"/><path d="M2 7h2"/><path d="M20 12h2"/><path d="M20 17h2"/><path d="M20 7h2"/><path d="M7 20v2"/><path d="M7 2v2"/><rect x="4" y="4" width="16" height="16" rx="2"/><rect x="8" y="8" width="8" height="8" rx="1"/></svg>

effusive/assets/hard-drive.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M10 16h.01"/><path d="M2.212 11.577a2 2 0 0 0-.212.896V18a2 2 0 0 0 2 2h16a2 2 0 0 0 2-2v-5.527a2 2 0 0 0-.212-.896L18.55 5.11A2 2 0 0 0 16.76 4H7.24a2 2 0 0 0-1.79 1.11z"/><path d="M21.946 12.013H2.054"/><path d="M6 16h.01"/></svg>

effusive/assets/layers.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M12.83 2.18a2 2 0 0 0-1.66 0L2.6 6.08a1 1 0 0 0 0 1.83l8.58 3.91a2 2 0 0 0 1.66 0l8.58-3.9a1 1 0 0 0 0-1.83z"/><path d="M2 12a1 1 0 0 0 .58.91l8.6 3.91a2 2 0 0 0 1.65 0l8.58-3.9A1 1 0 0 0 22 12"/><path d="M2 17a1 1 0 0 0 .58.91l8.6 3.91a2 2 0 0 0 1.65 0l8.58-3.9A1 1 0 0 0 22 17"/></svg>

effusive/assets/pause.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="14" y="4" width="4" height="16" rx="1"/><rect x="6" y="4" width="4" height="16" rx="1"/></svg>

effusive/assets/play.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polygon points="6 3 20 12 6 21 6 3"/></svg>

effusive/assets/sliders-horizontal.svg

@@ -0,0 +1,21 @@
+<svg
+  xmlns="http://www.w3.org/2000/svg"
+  width="24"
+  height="24"
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+>
+  <path d="M10 5H3" />
+  <path d="M12 19H3" />
+  <path d="M14 3v4" />
+  <path d="M16 17v4" />
+  <path d="M21 12h-9" />
+  <path d="M21 19h-5" />
+  <path d="M21 5h-7" />
+  <path d="M8 10v4" />
+  <path d="M8 12H3" />
+</svg>

effusive/assets/square.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect width="18" height="18" x="3" y="3" rx="2"/></svg>

effusive/assets/triangle-alert.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="m21.73 18-8-14a2 2 0 0 0-3.46 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/>
+  <path d="M12 9v4"/>
+  <path d="M12 17h.01"/>
+</svg>

effusive/bids.py

@@ -0,0 +1,390 @@
+"""Helpers for Effusive's BIDS-like storage mode.
+
+This module centralises validation and filename construction for the planned
+fUSI-BIDS layout so the napari UI and later MATLAB runtime code can share the
+same naming rules.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import platformdirs
+
+FUSI_DATATYPE = "fusi"
+"""Datatype folder for regular recordings."""
+
+ANGIO_DATATYPE = "angio"
+"""Datatype folder for z-stack exports."""
+
+FUSI_RECORDING_SUFFIXES = ("iq", "pwd", "rf", "rftimestamps", "seq.mat")
+"""Basename suffixes reserved by one fUSI recording stem."""
+
+VALID_BIDS_LABEL_RE = re.compile(r"^[A-Za-z0-9]+$")
+"""Allowed entity-label pattern for the v1 BIDS-like mode."""
+
+BIDS_META_SIDECAR_PATH = (
+    Path(platformdirs.user_cache_dir("effusive")) / "cf_bids_meta.json"
+)
+"""Per-recording metadata sidecar for live updates to the MATLAB worker.
+
+Written by Python at record-start; read by `cfPrepareStorageSpecForSave` to pick up
+subject/session/task/acq/proc/run values that may have changed since VSX launched.
+"""
+
+
+def write_bids_meta_sidecar(
+    task: str,
+    acq: str,
+    proc: str,
+    run: int,
+    subject: str = "",
+    session: str = "",
+) -> None:
+    """Write per-recording BIDS metadata to the shared sidecar file.
+
+    Parameters
+    ----------
+    task : str
+        Task label without the `task-` prefix.
+    acq : str
+        Acquisition label without the `acq-` prefix.
+    proc : str
+        Processing label without the `proc-` prefix.
+    run : int
+        Exact run index to use for the next recording.
+    subject : str, optional
+        Subject label without the `sub-` prefix.
+    session : str, optional
+        Session label without the `ses-` prefix.
+    """
+    BIDS_META_SIDECAR_PATH.parent.mkdir(parents=True, exist_ok=True)
+    BIDS_META_SIDECAR_PATH.write_text(
+        json.dumps(
+            {
+                "task": task,
+                "acq": acq,
+                "proc": proc,
+                "run": int(run),
+                "subject": subject,
+                "session": session,
+            }
+        )
+    )
+
+
+def validate_bids_label(value: str, field_name: str, required: bool = False) -> str:
+    """Validate one BIDS entity label.
+
+    Parameters
+    ----------
+    value : str
+        Raw entity-label text.
+    field_name : str
+        Human-readable field name used in error messages.
+    required : bool, default: False
+        Whether an empty value should be rejected.
+
+    Returns
+    -------
+    str
+        Stripped label text when valid.
+
+    Raises
+    ------
+    ValueError
+        Raised when the value is empty for a required field or contains
+        characters outside `[A-Za-z0-9]+`.
+    """
+    cleaned = value.strip()
+    if not cleaned:
+        if required:
+            raise ValueError(f"{field_name} is required.")
+        return ""
+    if VALID_BIDS_LABEL_RE.fullmatch(cleaned) is None:
+        raise ValueError(f"{field_name} must match [A-Za-z0-9]+.")
+    return cleaned
+
+
+def required_bids_fields(datatype: str) -> tuple[str, ...]:
+    """Return the required entity names for a datatype.
+
+    Parameters
+    ----------
+    datatype : str
+        Recording datatype, typically `fusi` or `angio`.
+
+    Returns
+    -------
+    tuple of str
+        Required entity names for the requested datatype.
+    """
+    if datatype == FUSI_DATATYPE:
+        return ("subject", "session", "task")
+    if datatype == ANGIO_DATATYPE:
+        return ("subject", "session")
+    raise ValueError(f"Unsupported BIDS datatype: {datatype}.")
+
+
+def validate_bids_entities(
+    *,
+    datatype: str,
+    subject: str,
+    session: str,
+    task: str = "",
+    acq: str = "",
+    proc: str = "",
+) -> dict[str, str]:
+    """Validate a set of entity values for one datatype.
+
+    Parameters
+    ----------
+    datatype : str
+        Recording datatype, typically `fusi` or `angio`.
+    subject : str
+        Subject label without the `sub-` prefix.
+    session : str
+        Session label without the `ses-` prefix.
+    task : str, optional
+        Task label without the `task-` prefix.
+    acq : str, optional
+        Acquisition label without the `acq-` prefix.
+    proc : str, optional
+        Processing label without the `proc-` prefix.
+
+    Returns
+    -------
+    dict of str to str
+        Validated entity values keyed by entity name.
+
+    Raises
+    ------
+    ValueError
+        Raised when any required or optional label is invalid.
+    """
+    required = set(required_bids_fields(datatype))
+    return {
+        "subject": validate_bids_label(subject, "Subject", "subject" in required),
+        "session": validate_bids_label(session, "Session", "session" in required),
+        "task": validate_bids_label(task, "Task", "task" in required),
+        "acq": validate_bids_label(acq, "Acq", False),
+        "proc": validate_bids_label(proc, "Proc", False),
+    }
+
+
+def format_run(run: int) -> str:
+    """Format a run index for the BIDS-like entity string.
+
+    Parameters
+    ----------
+    run : int
+        Positive run index.
+
+    Returns
+    -------
+    str
+        Zero-padded run label body such as `01`.
+
+    Raises
+    ------
+    ValueError
+        Raised when `run` is not positive.
+    """
+    if run < 1:
+        raise ValueError("Run must be >= 1.")
+    return f"{run:02d}"
+
+
+def build_bids_dir(root: Path, subject: str, session: str, datatype: str) -> Path:
+    """Build the datatype directory for one BIDS-like recording.
+
+    Parameters
+    ----------
+    root : Path
+        Storage root directory.
+    subject : str
+        Subject label without the `sub-` prefix.
+    session : str
+        Session label without the `ses-` prefix.
+    datatype : str
+        Datatype folder name, typically `fusi` or `angio`.
+
+    Returns
+    -------
+    Path
+        Datatype directory path below `root`.
+    """
+    subject_label = validate_bids_label(subject, "Subject", required=True)
+    session_label = validate_bids_label(session, "Session", required=True)
+    return Path(root) / f"sub-{subject_label}" / f"ses-{session_label}" / datatype
+
+
+def build_bids_stem(
+    *,
+    subject: str,
+    session: str,
+    task: str = "",
+    acq: str = "",
+    run: int | None = None,
+    proc: str = "",
+    datatype: str = FUSI_DATATYPE,
+) -> str:
+    """Build a BIDS-like filename stem without suffix or extension.
+
+    Parameters
+    ----------
+    subject : str
+        Subject label without the `sub-` prefix.
+    session : str
+        Session label without the `ses-` prefix.
+    task : str, optional
+        Task label without the `task-` prefix.
+    acq : str, optional
+        Acquisition label without the `acq-` prefix.
+    run : int, optional
+        Run index. When omitted, the stem is built without a `run-` entity.
+    proc : str, optional
+        Processing label without the `proc-` prefix.
+    datatype : str, default: `fusi`
+        Recording datatype, used only to validate required fields.
+
+    Returns
+    -------
+    str
+        Filename stem up to, but not including, the suffix.
+    """
+    entities = validate_bids_entities(
+        datatype=datatype,
+        subject=subject,
+        session=session,
+        task=task,
+        acq=acq,
+        proc=proc,
+    )
+    parts = [f"sub-{entities['subject']}", f"ses-{entities['session']}"]
+    if entities["task"]:
+        parts.append(f"task-{entities['task']}")
+    if entities["acq"]:
+        parts.append(f"acq-{entities['acq']}")
+    if entities["proc"]:
+        parts.append(f"proc-{entities['proc']}")
+    if run is not None:
+        parts.append(f"run-{format_run(run)}")
+    return "_".join(parts)
+
+
+def check_bids_run_collision(
+    root: Path,
+    *,
+    datatype: str,
+    subject: str,
+    session: str,
+    task: str = "",
+    acq: str = "",
+    run: int,
+    proc: str = "",
+) -> bool:
+    """Return True if any file with the expected BIDS stem already exists.
+
+    Parameters
+    ----------
+    root : Path
+        Storage root directory.
+    datatype : str
+        Datatype folder name, typically `fusi` or `angio`.
+    subject : str
+        Subject label without the `sub-` prefix.
+    session : str
+        Session label without the `ses-` prefix.
+    task : str, optional
+        Task label without the `task-` prefix.
+    acq : str, optional
+        Acquisition label without the `acq-` prefix.
+    run : int
+        Manual run index to check for collision.
+    proc : str, optional
+        Processing label without the `proc-` prefix.
+
+    Returns
+    -------
+    bool
+        True when at least one file matching `<stem>_*` exists.
+    """
+    bids_dir = build_bids_dir(root, subject, session, datatype)
+    stem = build_bids_stem(
+        subject=subject,
+        session=session,
+        task=task,
+        acq=acq,
+        run=run,
+        proc=proc,
+        datatype=datatype,
+    )
+    if not bids_dir.is_dir():
+        return False
+
+    if datatype == FUSI_DATATYPE:
+        return any(
+            (bids_dir / f"{stem}_{suffix}").exists()
+            for suffix in FUSI_RECORDING_SUFFIXES
+        )
+
+    return any(bids_dir.glob(f"{stem}_*"))
+
+
+def build_bids_preview_path(
+    root: Path,
+    *,
+    datatype: str,
+    subject: str,
+    session: str,
+    task: str = "",
+    acq: str = "",
+    run: int | None = None,
+    proc: str = "",
+    suffix: str = "pwd",
+    extension: str = ".ext",
+) -> Path:
+    """Build a full preview path for UI display.
+
+    Parameters
+    ----------
+    root : Path
+        Storage root directory.
+    datatype : str
+        Datatype folder name, typically `fusi` or `angio`.
+    subject : str
+        Subject label without the `sub-` prefix.
+    session : str
+        Session label without the `ses-` prefix.
+    task : str, optional
+        Task label without the `task-` prefix.
+    acq : str, optional
+        Acquisition label without the `acq-` prefix.
+    run : int, optional
+        Run index for the preview stem.
+    proc : str, optional
+        Processing label without the `proc-` prefix.
+    suffix : str, default: `pwd`
+        Output suffix token without the leading underscore.
+    extension : str, default: `.ext`
+        Filename extension shown in the preview.
+
+    Returns
+    -------
+    Path
+        Full preview path including one representative filename.
+    """
+    bids_dir = build_bids_dir(root, subject, session, datatype)
+    stem = build_bids_stem(
+        subject=subject,
+        session=session,
+        task=task,
+        acq=acq,
+        run=run,
+        proc=proc,
+        datatype=datatype,
+    )
+    return bids_dir / f"{stem}_{suffix}{extension}"

effusive/cli.py

@@ -0,0 +1,42 @@
+"""Effusive command-line entry point.
+
+Opens a napari viewer with live B-mode and PDI layers and a control dock widget. The
+MATLAB worker subprocess is not started automatically: click the play button in the
+sidebar after configuring acquisition parameters.
+
+Usage:
+
+```bash
+effusive
+```
+"""
+
+from __future__ import annotations
+
+import napari
+from qtpy.QtWidgets import QApplication
+
+from effusive import config as cf_config
+from effusive.napari import worker as worker_module
+from effusive.napari.plugin import make_main_widget
+
+
+def main() -> None:
+    """Run the Effusive napari viewer."""
+    viewer = napari.Viewer(title="Effusive")
+    widget = make_main_widget(viewer)
+    viewer.window.add_dock_widget(widget, name="Effusive", area="right")
+
+    # widget._config is kept live by command handlers and panel connections;
+    # saving it here requires no Qt object access so it works even after teardown.
+    app = QApplication.instance()
+    assert app is not None
+    app.aboutToQuit.connect(lambda: cf_config.save_config(widget._config))
+
+    napari.run()
+
+    worker_module.stop_acquisition(widget, from_close=True)
+
+
+if __name__ == "__main__":
+    main()