MNutils 1.2.0__py3-none-any.whl

mnutils/fitting/__init__.py

@@ -0,0 +1,5 @@
+"""Spectral fitting, delegated to pyAMARES through a thin wrapper."""
+
+from . import AMARES
+
+__all__ = ["AMARES"]

mnutils/matlab/__init__.py

@@ -0,0 +1,13 @@
+"""MATLAB Engine helpers (requires the optional `matlabengine` dependency)."""
+
+from .setup_matlab import (
+    add_matlablatest_path,
+    connect_to_matlab,
+    setup_util_path,
+)
+
+__all__ = [
+    "add_matlablatest_path",
+    "connect_to_matlab",
+    "setup_util_path",
+]

mnutils/matlab/setup_matlab.py

@@ -0,0 +1,116 @@
+import os
+
+import matlab.engine
+from loguru import logger
+
+
+def connect_to_matlab() -> matlab.engine.MatlabEngine:
+    """Connect to an existing shared MATLAB session, or start a new one.
+
+    Make sure to only call this function once per session — a second call
+    to connect to the same shared engine raises an `EngineError`.
+
+    Returns
+    -------
+    matlab.engine.MatlabEngine
+        The connected (or newly started) MATLAB engine instance.
+    """
+    engines = matlab.engine.find_matlab()
+    if engines:
+        logger.debug(f"Found running shared MATLAB engines. Connecting to engine {engines[0]}")
+        try:
+            eng = matlab.engine.connect_matlab(engines[0])
+        except matlab.engine.EngineError as e:  # type: ignore
+            logger.error(f"EngineError while connecting to MATLAB engine {engines[0]}: {e}")
+            logger.error("This may be due to multiple connections. Only one connection is allowed.")
+            raise
+        except (RuntimeError, TypeError, OSError) as e:
+            logger.error(f"Failed to connect to MATLAB engine {engines[0]}: {e}")
+            raise
+    else:
+        logger.debug(
+            "No running MATLAB engine found. Starting a new MATLAB engine. "
+            "This may take a second..."
+        )
+        eng = matlab.engine.start_matlab()
+
+    if not isinstance(eng, matlab.engine.MatlabEngine):
+        raise TypeError(f"Expected eng to be of type matlab.engine.MatlabEngine, got {type(eng)}")
+    logger.debug("Connected to MATLAB engine successfully.")
+    return eng
+
+
+def setup_util_path(
+    eng: matlab.engine.MatlabEngine,
+    matlab_utils_path: str | None = os.environ.get("MATLAB_UTILS"),
+) -> None:
+    """Add the MATLAB utils path to the MATLAB engine's path, if not already present.
+
+    Parameters
+    ----------
+    eng : matlab.engine.MatlabEngine
+        MATLAB engine instance.
+    matlab_utils_path : str | None
+        Path to the MATLAB utils folder. Defaults to the `MATLAB_UTILS` environment
+        variable.
+    """
+    if matlab_utils_path and os.path.exists(matlab_utils_path):
+        logger.debug(f"Adding MATLAB utils path: {matlab_utils_path}")
+        currentMatlabPath = str(eng.path())
+        if matlab_utils_path not in currentMatlabPath.split(":"):
+            eng.addpath(matlab_utils_path)
+        else:
+            logger.debug(f"MATLAB utils path already exists: {matlab_utils_path}")
+    else:
+        logger.warning(f"MATLAB_UTILS path is not set or does not exist: {matlab_utils_path}")
+
+
+def add_matlablatest_path(eng: matlab.engine.MatlabEngine) -> None:
+    """Add the 'matlablatest' path to the MATLAB environment using `manage_paths`.
+
+    Parameters
+    ----------
+    eng : matlab.engine.MatlabEngine
+        MATLAB engine instance.
+
+    Raises
+    ------
+    ValueError
+        If the MATLAB engine instance is invalid, or no 'matlabfiles' paths
+        are found after adding 'matlablatest'.
+    RuntimeError
+        If the 'manage_paths' function is not available in MATLAB.
+    """
+    try:
+        if not isinstance(eng, matlab.engine.MatlabEngine):
+            raise ValueError("Invalid MATLAB engine instance provided.")
+
+        logger.debug("Attempting to add 'matlablatest' path using manage_paths...")
+
+        # Check if the 'manage_paths' function exists in MATLAB
+        if not eng.which("manage_paths"):
+            raise RuntimeError("'manage_paths' function not found in MATLAB environment.")
+
+        # Add the 'matlablatest' path
+        eng.manage_paths("matlablatest", True, nargout=0)
+
+        # Retrieve and log paths containing 'matlabfiles'
+        matlabPath = str(eng.path())
+        matlabfiles_paths = [p for p in matlabPath.split(":") if "matlabfiles" in p.lower()]
+        if not matlabfiles_paths:
+            matlab_sources = eng.eval("getenv('MATLAB_SOURCES')", nargout=1)
+            raise ValueError(
+                f"No 'matlabfiles' paths found after adding 'matlablatest'. "
+                f"Check if MATLAB_SOURCES is set correctly. Current value: {matlab_sources}"
+            )
+        logger.debug("Successfully added 'matlablatest' path.")
+
+    except ValueError as ve:
+        logger.error(f"ValueError: {ve}")
+        raise
+    except RuntimeError as re:
+        logger.error(f"RuntimeError: {re}")
+        raise
+    except (AttributeError, TypeError) as e:
+        logger.error(f"An unexpected error occurred: {e}")
+        raise

mnutils/plotting/__init__.py

@@ -0,0 +1,38 @@
+"""Plotting for images and spectra, plus figure-saving helpers.
+
+Importing this package applies the MNUtils matplotlib defaults (sans-serif
+font stack, bold axis labels, constrained layout).
+"""
+
+import matplotlib.pyplot as plt
+
+from . import images, saving, spectra
+from .saving import (
+    DEFAULT_SAVE_PARAMS,
+    PAPER_SAVE_PARAMS,
+    POSTER_SAVE_PARAMS,
+    TALK_SAVE_PARAMS,
+    contexts,
+    save_current_figure,
+    save_figure,
+)
+
+plt.rcParams["font.family"] = "sans-serif"
+plt.rcParams["font.sans-serif"] = ["Helvetica", "Liberation Sans", "Arial", "sans-serif"]
+plt.rcParams["axes.labelweight"] = "bold"
+plt.rcParams["figure.constrained_layout.use"] = True
+
+__all__ = [
+    # modules
+    "images",
+    "saving",
+    "spectra",
+    # figure saving
+    "DEFAULT_SAVE_PARAMS",
+    "POSTER_SAVE_PARAMS",
+    "TALK_SAVE_PARAMS",
+    "PAPER_SAVE_PARAMS",
+    "contexts",
+    "save_figure",
+    "save_current_figure",
+]

mnutils/plotting/_widgets/__init__.py

@@ -0,0 +1,5 @@
+from .image_grid import ImageGridWidget
+from .mrsi_inspector import MRSIVoxelInspectorWidget
+from .slice_viewer import SliceViewerWidget
+
+__all__ = ["ImageGridWidget", "MRSIVoxelInspectorWidget", "SliceViewerWidget"]

mnutils/plotting/_widgets/_html.py

@@ -0,0 +1,34 @@
+import json
+import uuid
+from typing import Any
+
+
+def render_html(js: str, css: str, data: dict[str, Any]) -> str:
+    """Build a self-contained HTML/JS output embedding `data` for a widget's JS.
+
+    Deliberately not the ipywidgets/anywidget comm protocol: every widget in
+    this package is one-way (all data is baked in at construction, no
+    Python-side callback is ever needed after display), so there's nothing
+    to gain from a live model-sync channel -- and mystmd's execution engine
+    doesn't support it anyway (it has no registered `jupyter.widget` comm
+    target, so `widget-state+json` never gets captured into a static build,
+    only a dangling `widget-view+json` reference). A plain HTML/JS output
+    has no such dependency: it works identically in a live kernel, in myst's
+    live preview, and in a static `myst build --html` site. See
+    `docs/diary/2026-08-14-anywidget-slice-viewer.md` for the measurements.
+
+    `js` must define a function `renderWidget(data, el)` in module scope --
+    called directly by the trailing line below, so no `export` is involved --
+    and read every value it needs from `data`.
+    """
+    container_id = f"mnutils-widget-{uuid.uuid4().hex}"
+    # `</script>` inside the JSON payload would terminate the script block early.
+    data_json = json.dumps(data).replace("<", "\\u003c")
+    return f"""\
+<div id="{container_id}"></div>
+<style>{css}</style>
+<script type="module">
+{js}
+renderWidget({data_json}, document.getElementById("{container_id}"));
+</script>
+"""

mnutils/plotting/_widgets/_shared/__init__.py

@@ -0,0 +1,50 @@
+"""Shared frontend assets for MNUtils plotting widgets.
+
+Every widget's browser code is the concatenation of a common layer
+(``dom.js`` / ``theme.css``) and the widget's own ``<name>.js`` / ``<name>.css``.
+Because there is no JS bundler in this project, the sharing happens in Python:
+:func:`load_esm` / :func:`load_css` read both files and join them into a single
+source string that feeds `_widgets._html.render_html`.
+
+The shared JS is deliberately ``import``/``export``-free so it can sit in the
+same module scope as the widget's own ``renderWidget``.
+"""
+
+import pathlib
+
+_SHARED = pathlib.Path(__file__).parent
+
+
+def load_esm(widget_js: pathlib.Path) -> str:
+    """Return the shared JS helpers concatenated ahead of a widget's own JS.
+
+    Parameters
+    ----------
+    widget_js : pathlib.Path
+        Path to the widget's ``<name>.js`` (owns the ``renderWidget`` entry
+        point that `render_html` calls).
+
+    Returns
+    -------
+    str
+        Combined ESM source: ``dom.js`` followed by the widget's module.
+    """
+    shared = (_SHARED / "dom.js").read_text(encoding="utf-8")
+    return shared + "\n" + widget_js.read_text(encoding="utf-8")
+
+
+def load_css(widget_css: pathlib.Path) -> str:
+    """Return the shared theme concatenated ahead of a widget's own CSS.
+
+    Parameters
+    ----------
+    widget_css : pathlib.Path
+        Path to the widget's ``<name>.css`` (widget-specific / layout classes).
+
+    Returns
+    -------
+    str
+        Combined stylesheet: ``theme.css`` followed by the widget's overrides.
+    """
+    shared = (_SHARED / "theme.css").read_text(encoding="utf-8")
+    return shared + "\n" + widget_css.read_text(encoding="utf-8")

mnutils/plotting/_widgets/_shared/dom.js

@@ -0,0 +1,124 @@
+/**
+ * Shared frontend helpers for MNUtils plotting widgets.
+ *
+ * This module intentionally uses NO `import`/`export` statements: the Python
+ * asset loader (`_shared/__init__.py::load_esm`) concatenates it *ahead* of a
+ * widget's own `<name>.js`, so both end up in one module scope and every
+ * widget can call these helpers directly.
+ */
+
+/** Decode a base64 string (as produced by Python's base64.b64encode) to bytes. */
+function b64ToBytes(b64) {
+  return Uint8Array.from(atob(b64), (c) => c.charCodeAt(0));
+}
+
+/**
+ * Inflate a zlib stream produced by Python's `zlib.compress`.
+ *
+ * Uses the platform's own DecompressionStream, so decompressing the spectra
+ * buffer costs no JS dependency. `zlib.compress` emits the zlib wrapper, which
+ * is what the "deflate" format expects ("deflate-raw" would be the headerless
+ * variant).
+ */
+async function inflate(bytes) {
+  const stream = new Blob([bytes]).stream().pipeThrough(new DecompressionStream("deflate"));
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+/**
+ * Convert one IEEE-754 half-precision bit pattern to a JS number.
+ *
+ * Spectra travel as float16 to halve the payload. They are decoded a single
+ * voxel at a time rather than a whole grid at a time, so this stays cheap and
+ * there is no reason to depend on `Float16Array` (only Baseline 2025, and
+ * these widgets have to render on whatever browser opens the docs page).
+ */
+function halfToFloat(half) {
+  const sign = (half & 0x8000) ? -1 : 1;
+  const exponent = (half & 0x7c00) >> 10;
+  const fraction = half & 0x03ff;
+  if (exponent === 0) return sign * Math.pow(2, -14) * (fraction / 1024);
+  if (exponent === 0x1f) return fraction ? NaN : sign * Infinity;
+  return sign * Math.pow(2, exponent - 15) * (1 + fraction / 1024);
+}
+
+/** Clamp `value` into the inclusive [lo, hi] range. */
+function clamp(value, lo, hi) {
+  return Math.min(hi, Math.max(lo, value));
+}
+
+/** Build a `<div class="mnu-bar">` control row from a list of child elements. */
+function makeBar(...children) {
+  const bar = document.createElement("div");
+  bar.className = "mnu-bar";
+  bar.append(...children);
+  return bar;
+}
+
+/** Build a `<div class="mnu-grp">` grouping a related set of controls. */
+function makeGroup(...children) {
+  const grp = document.createElement("div");
+  grp.className = "mnu-grp";
+  grp.append(...children);
+  return grp;
+}
+
+/**
+ * Build a labeled slice slider: `<span class="mnu-lbl">` + `<input
+ * type="range" class="mnu-slider">` + `<span class="mnu-readout">`, wired so
+ * moving the slider calls `onInput(index)` and updates the readout text via
+ * `formatReadout(index)`.
+ */
+function makeSliceSlider({ min, max, value, step = 1, label, formatReadout, onInput }) {
+  const lbl = document.createElement("span");
+  lbl.className = "mnu-lbl";
+  lbl.textContent = label;
+
+  const slider = document.createElement("input");
+  slider.type = "range";
+  slider.className = "mnu-slider";
+  slider.min = String(min);
+  slider.max = String(max);
+  slider.step = String(step);
+  slider.value = String(value);
+  slider.disabled = max <= min;
+
+  const readout = document.createElement("span");
+  readout.className = "mnu-readout";
+  readout.textContent = formatReadout(value);
+
+  slider.addEventListener("input", () => {
+    const idx = Number(slider.value);
+    readout.textContent = formatReadout(idx);
+    onInput(idx);
+  });
+
+  return { lbl, slider, readout };
+}
+
+/**
+ * Build a pill-shaped checkbox: a `<label class="mnu-toggle">` wrapping an
+ * `<input type="checkbox">` and its text, wired so ticking it calls
+ * `onChange(checked)`.
+ *
+ * A label-wrapped checkbox rather than a styled button: it stays a real
+ * checkbox for assistive technology and for keyboard users, and the whole
+ * pill becomes the hit target because the input sits inside the label.
+ */
+function makeToggle({ label, checked = false, onChange }) {
+  const toggle = document.createElement("label");
+  toggle.className = "mnu-toggle";
+
+  const input = document.createElement("input");
+  input.type = "checkbox";
+  input.checked = checked;
+
+  const text = document.createElement("span");
+  text.textContent = label;
+
+  input.addEventListener("change", () => onChange(input.checked));
+  toggle.append(input, text);
+
+  return { toggle, input };
+}
+

mnutils/plotting/_widgets/_shared/theme.css

@@ -0,0 +1,140 @@
+/* =========================================================================
+   MNUtils shared widget theme.
+   Concatenated ahead of each widget's own <name>.css by the Python asset
+   loader (_shared/__init__.py::load_css). Holds the `--mnu-*` design tokens
+   (light + dark) and the invariant `mnu-*` chrome shared by every widget.
+   Widget-specific / layout classes live in the widget's own CSS and override
+   these defaults (concatenated afterwards, so they win at equal specificity).
+   ========================================================================= */
+
+:root {
+  --mnu-bg: #ffffff;
+  --mnu-panel: #fafafa;
+  --mnu-border: #e0e0e0;
+  --mnu-border-soft: #eeeeee;
+  --mnu-fg: #333333;
+  --mnu-fg-strong: #111111;
+  --mnu-muted: #666666;
+  --mnu-muted-2: #888888;
+  --mnu-label: #444444;
+  --mnu-accent: #0055aa;
+  --mnu-accent-strong: #004488;
+  --mnu-shadow: rgba(0, 0, 0, 0.05);
+  --mnu-focus-ring: rgba(100, 150, 200, 0.15);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --mnu-bg: #1e1e1e;
+    --mnu-panel: #252526;
+    --mnu-border: #3c3c3c;
+    --mnu-border-soft: #333333;
+    --mnu-fg: #d4d4d4;
+    --mnu-fg-strong: #f0f0f0;
+    --mnu-muted: #a0a0a0;
+    --mnu-muted-2: #8a8a8a;
+    --mnu-label: #c8c8c8;
+    --mnu-accent: #4ea1ff;
+    --mnu-accent-strong: #3b82d6;
+    --mnu-shadow: rgba(0, 0, 0, 0.35);
+    --mnu-focus-ring: rgba(120, 170, 220, 0.25);
+  }
+}
+
+/* =========================================
+   Container & control-bar chrome, shared by every widget.
+   ========================================= */
+.mnu-viewer {
+  display: flex;
+  flex-direction: column;
+  font-family: system-ui, -apple-system, sans-serif;
+  color: var(--mnu-fg);
+  background: var(--mnu-bg);
+  border: 1px solid var(--mnu-border);
+  border-radius: 8px;
+  box-shadow: 0 4px 12px var(--mnu-shadow);
+  overflow: hidden;
+}
+
+.mnu-panel {
+  position: relative;
+  background: var(--mnu-panel);
+  border-bottom: 1px solid var(--mnu-border-soft);
+}
+
+.mnu-bar {
+  display: flex;
+  align-items: center;
+  gap: 0.6em;
+  padding: 0.5em 0.7em;
+  background: var(--mnu-bg);
+}
+
+.mnu-grp {
+  display: flex;
+  align-items: center;
+  gap: 0.6em;
+}
+
+.mnu-lbl {
+  font-size: 0.8em;
+  font-weight: 600;
+  color: var(--mnu-label);
+}
+
+.mnu-readout {
+  font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
+  font-size: 0.8em;
+  color: var(--mnu-muted);
+  min-width: 5em;
+  text-align: right;
+}
+
+.mnu-slider {
+  flex: 1;
+  accent-color: var(--mnu-accent);
+}
+
+.mnu-slider:focus-visible {
+  outline: 2px solid var(--mnu-focus-ring);
+}
+
+/* Pill checkbox for a control bar, built by `dom.js::makeToggle`. */
+.mnu-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.45em;
+  padding: 0.25em 0.7em;
+  border: 1px solid var(--mnu-border);
+  border-radius: 999px;
+  background: var(--mnu-panel);
+  font-size: 0.8em;
+  font-weight: 600;
+  color: var(--mnu-label);
+  line-height: 1.4;
+  opacity: 0.75;
+  cursor: pointer;
+  user-select: none;
+  transition:
+    opacity 0.12s ease,
+    border-color 0.12s ease;
+}
+
+.mnu-toggle:hover,
+.mnu-toggle:focus-within {
+  opacity: 1;
+}
+
+.mnu-toggle:has(input:checked) {
+  opacity: 1;
+  border-color: var(--mnu-accent);
+}
+
+.mnu-toggle input {
+  width: 1.1em;
+  height: 1.1em;
+  margin: 0;
+  accent-color: var(--mnu-accent);
+  cursor: pointer;
+}
+