brkraw-viewer 0.2.7__tar.gz

brkraw_viewer-0.2.7/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: brkraw-viewer
+Version: 0.2.7
+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.7/README.md

@@ -0,0 +1,151 @@
+<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.7/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "brkraw-viewer"
+version = "0.2.7"
+description = "BrkRaw scan viewer plugin for brkraw CLI."
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+  "brkraw>=0.5.0rc1",
+  "nibabel>=5.0",
+  "pillow>=10.0",
+]
+authors = [{name = "BrkRaw"}]
+license = {text = "MIT"}
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+]
+
+[project.entry-points."brkraw.cli"]
+viewer = "brkraw_viewer.plugin:register"
+
+[project.optional-dependencies]
+docs = [
+  "mkdocs-material>=9.5.0",
+]
+test = [
+  "pytest>=7.4",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+brkraw_viewer = ["assets/*.png", "assets/*.ico", "snippets/**/*.yaml"]

brkraw_viewer-0.2.7/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

brkraw_viewer-0.2.7/src/brkraw_viewer/__init__.py

@@ -0,0 +1,4 @@
+"""BrkRaw viewer plugin package."""
+
+__all__ = ["__version__"]
+__version__ = '0.2.7'

brkraw_viewer-0.2.7/src/brkraw_viewer/apps/config.py

@@ -0,0 +1,90 @@
+from __future__ import annotations
+
+import datetime as dt
+import logging
+import shutil
+import tkinter as tk
+from tkinter import messagebox, ttk
+from pathlib import Path
+
+from brkraw.core import config as config_core
+
+logger = logging.getLogger("brkraw.viewer")
+
+
+class ConfigTabMixin:
+    _config_text: tk.Text
+    _config_path_var: tk.StringVar
+
+    def _build_config_tab(self, config_tab: ttk.Frame) -> None:
+        config_tab.columnconfigure(0, weight=1)
+        config_tab.rowconfigure(1, weight=1)
+        config_bar = ttk.Frame(config_tab, padding=(6, 6))
+        config_bar.grid(row=0, column=0, sticky="ew")
+        ttk.Button(config_bar, text="Save", command=self._save_config_text).pack(side=tk.LEFT)
+        ttk.Button(config_bar, text="Backup", command=self._backup_config_text).pack(side=tk.LEFT, padx=(6, 0))
+        ttk.Button(config_bar, text="Reset", command=self._reset_config_text).pack(side=tk.LEFT, padx=(6, 0))
+        self._config_path_var = tk.StringVar(value="")
+        ttk.Label(config_bar, textvariable=self._config_path_var).pack(side=tk.LEFT, padx=(12, 0))
+
+        config_body = ttk.Frame(config_tab, padding=(6, 6))
+        config_body.grid(row=1, column=0, sticky="nsew")
+        config_body.columnconfigure(0, weight=1)
+        config_body.rowconfigure(0, weight=1)
+        self._config_text = tk.Text(config_body, wrap="none")
+        self._config_text.grid(row=0, column=0, sticky="nsew")
+        config_scroll = ttk.Scrollbar(config_body, orient="vertical", command=self._config_text.yview)
+        config_scroll.grid(row=0, column=1, sticky="ns")
+        self._config_text.configure(yscrollcommand=config_scroll.set)
+
+    def _load_config_text(self) -> None:
+        try:
+            paths = config_core.ensure_initialized(root=None, create_config=True, exist_ok=True)
+            self._config_path_var.set(str(paths.config_file))
+            content = paths.config_file.read_text(encoding="utf-8")
+        except Exception as exc:
+            logger.error("Failed to load config.yaml: %s", exc, exc_info=logger.isEnabledFor(logging.DEBUG))
+            self._config_path_var.set("")
+            self._config_text.delete("1.0", tk.END)
+            self._config_text.insert(tk.END, f"# Failed to load config.yaml: {exc}\n")
+            return
+        self._config_text.delete("1.0", tk.END)
+        self._config_text.insert(tk.END, content)
+
+    def _save_config_text(self) -> None:
+        try:
+            paths = config_core.ensure_initialized(root=None, create_config=True, exist_ok=True)
+            self._config_path_var.set(str(paths.config_file))
+            text = self._config_text.get("1.0", tk.END)
+            paths.config_file.write_text(text, encoding="utf-8")
+            logger.info("Saved config.yaml: %s", paths.config_file)
+        except Exception as exc:
+            logger.error("Failed to save config.yaml: %s", exc, exc_info=logger.isEnabledFor(logging.DEBUG))
+            messagebox.showerror("Save error", f"Failed to save config.yaml:\n{exc}")
+
+    def _backup_config_text(self) -> None:
+        try:
+            paths = config_core.ensure_initialized(root=None, create_config=True, exist_ok=True)
+            config_path = paths.config_file
+            self._config_path_var.set(str(config_path))
+            if not config_path.exists():
+                messagebox.showwarning("Backup", f"Config file not found:\n{config_path}")
+                return
+            ts = dt.datetime.now().strftime("%Y%m%d-%H%M%S")
+            backup_path = Path(f"{config_path}.bak-{ts}")
+            shutil.copy2(config_path, backup_path)
+            logger.info("Backed up config.yaml: %s", backup_path)
+            messagebox.showinfo("Backup", f"Created backup:\n{backup_path}")
+        except Exception as exc:
+            logger.error("Failed to back up config.yaml: %s", exc, exc_info=logger.isEnabledFor(logging.DEBUG))
+            messagebox.showerror("Backup error", f"Failed to back up config.yaml:\n{exc}")
+
+    def _reset_config_text(self) -> None:
+        try:
+            config_core.reset_config(root=None)
+            logger.info("Reset config.yaml to defaults.")
+        except Exception as exc:
+            logger.error("Failed to reset config.yaml: %s", exc, exc_info=logger.isEnabledFor(logging.DEBUG))
+            messagebox.showerror("Reset error", f"Failed to reset config.yaml:\n{exc}")
+            return
+        self._load_config_text()