brkraw-viewer 0.2.5__py3-none-any.whl

brkraw_viewer/registry.py

@@ -0,0 +1,258 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional, Tuple, Mapping
+import json
+import logging
+import zipfile
+import datetime as dt
+
+from brkraw.apps.loader import BrukerLoader
+from brkraw.core.fs import DatasetFS
+from brkraw.dataclasses.study import Study
+
+from .frames.viewer_config import registry_path
+
+logger = logging.getLogger("brkraw.viewer")
+
+
+@dataclass(frozen=True)
+class RegistryEntry:
+    path: str
+    basename: str
+    study: Dict[str, Any]
+    num_scans: int
+    kind: str
+    added_at: str
+    last_seen: str
+
+    def as_dict(self) -> Dict[str, Any]:
+        return {
+            "path": self.path,
+            "basename": self.basename,
+            "study": _json_safe(self.study),
+            "num_scans": self.num_scans,
+            "kind": self.kind,
+            "added_at": self.added_at,
+            "last_seen": self.last_seen,
+        }
+
+
+def _now_iso() -> str:
+    from datetime import datetime, timezone
+
+    return datetime.now(timezone.utc).isoformat()
+
+
+def normalize_path(path: Path) -> str:
+    path = path.expanduser()
+    try:
+        return str(path.resolve())
+    except FileNotFoundError:
+        return str(path)
+
+
+def _ensure_registry_path(root: Optional[Path] = None) -> Path:
+    reg_path = registry_path(root)
+    reg_path.parent.mkdir(parents=True, exist_ok=True)
+    if not reg_path.exists():
+        reg_path.write_text("", encoding="utf-8")
+    return reg_path
+
+
+def load_registry(root: Optional[Path] = None) -> List[Dict[str, Any]]:
+    reg_path = registry_path(root)
+    if not reg_path.exists():
+        return []
+    entries: List[Dict[str, Any]] = []
+    for line in reg_path.read_text(encoding="utf-8").splitlines():
+        text = line.strip()
+        if not text:
+            continue
+        try:
+            payload = json.loads(text)
+        except json.JSONDecodeError:
+            logger.warning("Skipping invalid registry line: %s", text)
+            continue
+        if isinstance(payload, dict):
+            entries.append(payload)
+    return entries
+
+
+def write_registry(entries: Iterable[Dict[str, Any]], root: Optional[Path] = None) -> None:
+    reg_path = _ensure_registry_path(root)
+    lines = [json.dumps(_json_safe(entry), ensure_ascii=True) for entry in entries]
+    reg_path.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
+
+
+def _discover_study_paths(path: Path) -> List[Path]:
+    fs = DatasetFS.from_path(path)
+    studies = Study.discover(fs)
+    if not studies:
+        return []
+    if len(studies) == 1:
+        study = studies[0]
+        return [fs.root / study.relroot if study.relroot else fs.root]
+    if fs._mode == "dir":
+        return [fs.root / study.relroot if study.relroot else fs.root for study in studies]
+    raise ValueError("Multiple studies found in archive; extract or point to a single study.")
+
+
+def _discover_dataset_paths(path: Path) -> List[Path]:
+    logger.info("Scanning for datasets under %s", path)
+    if _is_archive(path):
+        logger.debug("Found archive dataset: %s", path)
+        return [path]
+    if path.is_dir():
+        direct = _discover_study_paths(path)
+        if direct:
+            logger.info("Found study dataset: %s", path)
+            return direct
+        discovered: List[Path] = []
+        for child in sorted(path.iterdir()):
+            if child.name.startswith("."):
+                continue
+            if _is_archive(child):
+                logger.debug("Found archive dataset: %s", child)
+                discovered.append(child)
+                continue
+            if child.is_dir():
+                try:
+                    studies = _discover_study_paths(child)
+                except ValueError as exc:
+                    logger.warning("Skipping %s: %s", child, exc)
+                    continue
+                if studies:
+                    for study in studies:
+                        logger.info("Found study dataset: %s", study)
+                discovered.extend(studies)
+        logger.info("Discovery complete: %d dataset(s) under %s", len(discovered), path)
+        return discovered
+    return []
+
+
+def _is_archive(path: Path) -> bool:
+    return path.is_file() and zipfile.is_zipfile(path)
+
+
+def _load_study_info(loader: BrukerLoader) -> Dict[str, Any]:
+    info: Dict[str, Any] = {}
+    try:
+        subject = loader.subject
+        if isinstance(subject, dict):
+            study = subject.get("Study", {})
+            if isinstance(study, dict):
+                info = dict(study)
+    except Exception:
+        info = {}
+    return info
+
+
+def _json_safe(value: Any) -> Any:
+    if value is None or isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, dict):
+        return {str(k): _json_safe(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_json_safe(v) for v in value]
+    if isinstance(value, dt.datetime):
+        return value.date().isoformat()
+    if isinstance(value, dt.date):
+        return value.isoformat()
+    return str(value)
+
+
+def build_entry(path: Path) -> RegistryEntry:
+    norm = normalize_path(path)
+    basename = path.name
+    kind = "archive" if _is_archive(path) else "study"
+    loader = BrukerLoader(path)
+    study_info = _load_study_info(loader)
+    num_scans = len(loader.avail)
+    timestamp = _now_iso()
+    return RegistryEntry(
+        path=norm,
+        basename=basename,
+        study=study_info,
+        num_scans=num_scans,
+        kind=kind,
+        added_at=timestamp,
+        last_seen=timestamp,
+    )
+
+
+def _merge_entries(
+    existing: Dict[str, Dict[str, Any]],
+    new_entries: Iterable[RegistryEntry],
+) -> Tuple[Dict[str, Dict[str, Any]], int]:
+    added = 0
+    for entry in new_entries:
+        current = existing.get(entry.path)
+        if current is None:
+            existing[entry.path] = entry.as_dict()
+            added += 1
+        else:
+            updated = dict(current)
+            updated.update(entry.as_dict())
+            updated["added_at"] = current.get("added_at", entry.added_at)
+            existing[entry.path] = updated
+    return existing, added
+
+
+def register_paths(paths: Iterable[Path], root: Optional[Path] = None) -> List[RegistryEntry]:
+    entries: List[RegistryEntry] = []
+    for raw in paths:
+        expanded = raw.expanduser()
+        if not expanded.exists():
+            raise FileNotFoundError(expanded)
+        logger.debug("Registering dataset path: %s", expanded)
+        try:
+            dataset_paths = _discover_dataset_paths(expanded)
+        except ValueError as exc:
+            raise exc
+        if not dataset_paths:
+            raise ValueError(f"No Paravision study found under {expanded}")
+        for study_path in dataset_paths:
+            logger.info("Building registry entry: %s", study_path)
+            entries.append(build_entry(study_path))
+    existing = {entry["path"]: entry for entry in load_registry(root)}
+    merged, _ = _merge_entries(existing, entries)
+    write_registry(merged.values(), root=root)
+    return entries
+
+
+def unregister_paths(paths: Iterable[Path], root: Optional[Path] = None) -> int:
+    normalized = {normalize_path(path) for path in paths}
+    entries = load_registry(root)
+    kept = [entry for entry in entries if entry.get("path") not in normalized]
+    removed = len(entries) - len(kept)
+    write_registry(kept, root=root)
+    return removed
+
+
+def registry_status(root: Optional[Path] = None) -> List[Dict[str, Any]]:
+    entries = load_registry(root)
+    for entry in entries:
+        path = entry.get("path", "")
+        entry["missing"] = not Path(str(path)).exists()
+    return entries
+
+
+def resolve_entry_value(entry: Mapping[str, Any], key: str) -> str:
+    if key == "basename":
+        return str(entry.get("basename", ""))
+    if key == "path":
+        return str(entry.get("path", ""))
+    if key == "num_scans":
+        return str(entry.get("num_scans", ""))
+    if key == "kind":
+        return str(entry.get("kind", ""))
+    if key == "missing":
+        return "Yes" if entry.get("missing") else "No"
+    if key.startswith("Study."):
+        study = entry.get("study", {})
+        if isinstance(study, dict):
+            field = key.split(".", 1)[1]
+            return str(study.get(field, ""))
+    return str(entry.get(key, ""))

brkraw_viewer/snippets/context_map/basic.yaml

@@ -0,0 +1,4 @@
+Protocol:
+  type: mapping
+  values:
+    "<Protocol>": "<Mapped>"

brkraw_viewer/snippets/context_map/enum-map.yaml

@@ -0,0 +1,5 @@
+SubjectType:
+  type: mapping
+  values:
+    "biped": "human"
+    "quadruped": "animal"

brkraw_viewer/snippets/rule/basic.yaml

@@ -0,0 +1,10 @@
+info_spec:
+  - name: example
+    use: example.yaml
+    when:
+      Method:
+        sources:
+          - file: method
+            key: Method
+    if:
+      eq: ["$Method", "<METHOD>"]

brkraw_viewer/snippets/rule/when-contains.yaml

@@ -0,0 +1,10 @@
+metadata_spec:
+  - name: example-metadata
+    use: metadata.yaml
+    when:
+      Protocol:
+        sources:
+          - file: acqp
+            key: ACQ_protocol_name
+    if:
+      contains: ["$Protocol", "<TAG>"]

brkraw_viewer/snippets/spec/basic.yaml

@@ -0,0 +1,5 @@
+Protocol:
+  sources:
+    - file: acqp
+      key: ACQ_protocol_name
+  transform: strip_jcamp_string

brkraw_viewer/snippets/spec/list-source.yaml

@@ -0,0 +1,5 @@
+EchoTimes:
+  sources:
+    - file: method
+      key: PVM_EchoTime
+  transform: to_list

brkraw_viewer/snippets/spec/with-default.yaml

@@ -0,0 +1,5 @@
+FlipAngle:
+  sources:
+    - file: method
+      key: PVM_FlipAngle
+  default: 0

brkraw_viewer/utils/__init__.py

@@ -0,0 +1,2 @@
+"""Small helper utilities for the viewer."""
+

brkraw_viewer/utils/orientation.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import numpy as np
+import nibabel as nib
+
+
+def reorient_to_ras(data: np.ndarray, affine: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    data = np.asarray(data)
+    affine = np.asarray(affine, dtype=float)
+
+    ornt = nib.orientations.io_orientation(affine)
+    ras_ornt = np.array([[0, 1], [1, 1], [2, 1]])  # RAS
+    transform = nib.orientations.ornt_transform(ornt, ras_ornt)
+    new_data = nib.orientations.apply_orientation(data, transform)
+    new_affine = affine @ nib.orientations.inv_ornt_aff(transform, data.shape)
+    return new_data, new_affine
+

brkraw_viewer-0.2.5.dist-info/METADATA

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: brkraw-viewer
+Version: 0.2.5
+Summary: BrkRaw scan viewer plugin for brkraw CLI.
+Author: BrkRaw
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: brkraw>=0.5.0rc1
+Requires-Dist: nibabel>=5.0
+Requires-Dist: pillow>=10.0
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=7.4; extra == "test"
+
+<h1 align="left">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brkraw-viewer-logo-dark.svg">
+    <img alt="BrkRaw Viewer" src="docs/assets/brkraw-viewer-logo-light.svg" width="410">
+  </picture>
+</h1>
+
+BrkRaw Viewer is an interactive dataset viewer implemented as a
+separate CLI plugin for the `brkraw` command.
+
+The viewer is intentionally maintained outside the BrkRaw core to
+enable independent development and community contributions around
+user-facing interfaces.
+
+---
+
+## Scope and intent
+
+BrkRaw Viewer is designed for **interactive inspection** of Bruker
+Paravision datasets. It focuses on quick exploration and validation
+rather than data conversion or analysis.
+
+The goal is to provide practical, researcher-focused features that are
+useful in everyday workflows, such as quick dataset triage, metadata
+checks, and lightweight visual QC.
+
+Typical use cases include:
+
+- Browsing studies, scans, and reconstructions
+- Verifying scan and reconstruction IDs
+- Inspecting acquisition metadata before conversion
+- Lightweight visual sanity checks
+
+All data conversion and reproducible workflows are handled by the
+BrkRaw CLI and Python API.
+
+---
+
+## Why these features exist
+
+**Viewer**
+The Viewer tab makes it easy to confirm the right scan and orientation before
+running a larger workflow.
+
+**Registry**
+The Registry reduces repeated filesystem navigation and lets you re-open the
+current session with a single menu action.
+
+**Extensions/hooks**
+Extensions allow modality-specific panels (MRS, BIDS, etc.) to live outside the
+core viewer so the default install stays lightweight.
+
+---
+
+## Design goal: shared extensibility
+
+brkraw-viewer keeps the BrkRaw design philosophy: extend the ecosystem
+without changing core logic. The viewer uses the same rules/spec/layout
+system as the CLI and Python API, and it exposes UI extensions via the
+`brkraw.viewer.hook` entry point so new tabs can be added with standalone
+packages. Viewer hooks can coexist with converter hooks and CLI hooks,
+so modality-specific logic can flow from conversion into UI without
+patching the viewer itself.
+
+---
+
+## UI direction
+
+The default viewer targets a **tkinter-based** implementation.
+
+This choice is intentional: we want a lightweight tool that can be
+used directly on scanner consoles or constrained environments with
+minimal dependencies.
+
+More modern GUI frameworks are welcome, but should be developed as
+separate CLI extensions to keep the default viewer small and easy to
+install.
+
+---
+
+## Viewer hooks
+
+Viewer extensions are implemented as hooks discovered through
+`brkraw.viewer.hook`. Each hook can register a new tab and provide
+dataset callbacks, enabling feature panels to live outside the core
+viewer while staying compatible with BrkRaw rules, specs, and converter
+hooks. See `docs/dev/hooks.md` for the hook interface and entry point
+setup.
+
+---
+
+## Installation
+
+For development and testing, install in editable mode:
+
+    pip install -e .
+
+---
+
+## Usage
+
+Launch the viewer via the BrkRaw CLI:
+
+    brkraw viewer /path/to/bruker/study
+
+Optional arguments allow opening a specific scan or slice:
+
+    brkraw viewer /path/to/bruker/study \
+        --scan 3 \
+        --reco 1
+
+The viewer can also open `.zip` or Paravision-exported `.PvDatasets`
+archives using `Load` (folder or archive file).
+
+---
+
+## Update
+
+Recent updates:
+
+- Open folders or archives (`.zip` / `.PvDatasets`)
+- Viewer: `Space` (`raw/scanner/subject_ras`), nibabel RAS display, click-to-set `X/Y/Z`, optional crosshair + zoom,
+  slicepack/frame sliders only when needed
+- Info: rule + spec selection (installed or file), parameter search, lazy Viewer refresh on tab focus
+- Registry: add the current session from the `+` menu when a dataset is loaded
+- Convert: BrkRaw layout engine, template + suffix defaults from `~/.brkraw/config.yaml`, keys browser (click to add),
+  optional config `layout_entries`
+- Config: edit `~/.brkraw/config.yaml` in-app; basic focus/icon UX
+
+This update keeps dependencies minimal and preserves compatibility with
+the core BrkRaw rule/spec/hook system.
+
+---
+
+## Contributing
+
+We welcome contributions related to:
+
+- New viewer hooks that add modality-specific panels or workflows
+- Alternative UI implementations delivered as separate CLI extensions
+- fMRI/MRS/BIDS-focused visualization or QC helpers built on hooks
+- Multi-dataset session management and registry enhancements
+- Performance and memory improvements for large datasets
+
+Contributions should prefer designs where new hooks extend the viewer
+implicitly through shared BrkRaw abstractions, and where richer UIs are
+provided as optional CLI extensions rather than increasing the default
+dependency footprint.
+
+If you are interested in contributing, please start a discussion or
+open an issue describing your use case and goals.

brkraw_viewer-0.2.5.dist-info/RECORD

@@ -0,0 +1,28 @@
+brkraw_viewer/__init__.py,sha256=0-N1hhUaTQikf7pDU65gb6LyYAd3zqXCzPH4H7Se-uE,84
+brkraw_viewer/plugin.py,sha256=hwmRF9x20j8EbSk6m8f1sB7cXCBKLhV5NWic545tuQc,4004
+brkraw_viewer/registry.py,sha256=fvLve_dbc4pBKr_akZN87oI9OJJP1Zm39KsO1ZHxH0M,8350
+brkraw_viewer/apps/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+brkraw_viewer/apps/config.py,sha256=1y_1j-PePQ38jfM9OcVgeViUz6MtcvvEH5vOzWRDS_0,4412
+brkraw_viewer/apps/convert.py,sha256=Uq0BhTaDTtZN-7XUEbycXnUF7Fi5-EvxxLgqI0Ly59s,73707
+brkraw_viewer/apps/hooks.py,sha256=o12A5exietCdGLss9Ia2I7-83Bs6P3XV3iKaQsgUdEc,872
+brkraw_viewer/apps/viewer.py,sha256=lSHxtW6fy2WHG_jworgQqK9Ta7TVdj7CtIxiwxziab8,219026
+brkraw_viewer/assets/icon.ico,sha256=QUW0dBcnKbNO7MLh58PeLosoveBasMzlHt8UuH6xmKs,372
+brkraw_viewer/assets/icon.png,sha256=Ag-rdTHDnN_LKI6TxRRrP2OWzqoEKFQR0mrxmmcQZkI,769
+brkraw_viewer/frames/__init__.py,sha256=j0U2uMfovQBYuAC3ZzJlN7ilIxcp9J5KQXQm425fNCA,45
+brkraw_viewer/frames/params_panel.py,sha256=AoNskdln3bX_0x00s6f2BuWaDZhZI8_ARnswj_ykQwM,2949
+brkraw_viewer/frames/viewer_canvas.py,sha256=j8RnE-oWqEbsYnQxL1OQP6OAybi4U9s1xFgPuuxEGZ4,13456
+brkraw_viewer/frames/viewer_config.py,sha256=CMQzB_Naexio6WRWLZYTM67rQ-XY51cFOrXuWlddHtQ,3283
+brkraw_viewer/snippets/context_map/basic.yaml,sha256=GoHvSueX7-5ViFS-cwv12rjah9jf_4mHYUh54sRPJtk,65
+brkraw_viewer/snippets/context_map/enum-map.yaml,sha256=LlX-fKt3XOxQmeuY8NQQyjvxCHkHHvqNGhUJuOPMApw,86
+brkraw_viewer/snippets/rule/basic.yaml,sha256=Qy16CDa0Yc0AB2cWzxrnh0dxN-Yc5dDQMhBUUYWOiK4,183
+brkraw_viewer/snippets/rule/when-contains.yaml,sha256=89CQv6AcaAWdHO0xfyB6om0qPXgivLtDqDl6TbmhYSU,213
+brkraw_viewer/snippets/spec/basic.yaml,sha256=1bhSHRcshvDNL8eIoMbGj5KxlbXsVeQbQivExDc9RP8,99
+brkraw_viewer/snippets/spec/list-source.yaml,sha256=toqz2vEjpxV11Q4Sfkn7fPjaxuXYsQqQDSCygQnU680,86
+brkraw_viewer/snippets/spec/with-default.yaml,sha256=Dvx-LdErlwF0dnP_ocFQzR68eQUGoC0zB2s_BWVhNgk,79
+brkraw_viewer/utils/__init__.py,sha256=syfKEnHaaFrSNCiPTAIHbZpVrEEfllA9qV1XrD_GCj8,46
+brkraw_viewer/utils/orientation.py,sha256=GulLdN5HtF1IjQLfFYSAJiGSSCzCK3AnSZ8HM-DRn8g,596
+brkraw_viewer-0.2.5.dist-info/METADATA,sha256=xwH8n4Y_3Gr56sN8jBkCO8ndSAGcrFdqa4DcJlXfSEs,5403
+brkraw_viewer-0.2.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+brkraw_viewer-0.2.5.dist-info/entry_points.txt,sha256=zd9043V-472NISOxavHd2f4Er7SH_CSSRkDl_Bq7jyY,52
+brkraw_viewer-0.2.5.dist-info/top_level.txt,sha256=pyOwjVrot5Cg6GSh3jbhMag2coTkKAlCT3-c20RuC-M,14
+brkraw_viewer-0.2.5.dist-info/RECORD,,

brkraw_viewer-0.2.5.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

brkraw_viewer-0.2.5.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[brkraw.cli]
+viewer = brkraw_viewer.plugin:register

brkraw_viewer-0.2.5.dist-info/top_level.txt

@@ -0,0 +1 @@
+brkraw_viewer