bsplot 0.0.2__py3-none-any.whl

bsplot/__init__.py

@@ -0,0 +1,23 @@
+from os.path import abspath, dirname, join
+
+__version__ = "0.0.2"
+
+ROOT = abspath(dirname(__file__))
+datadir = join(ROOT, "data")
+
+from . import volume, anat, animate, brain, colors, data, figure, streamlines, style, timeseries, surface, templates, utils
+from .surface import vol_to_mesh, LabeledMeshes, project_vol_to_surf, plot_surf
+from .brain import glass_brain
+from .volume import plot_slice, apply_brain_mask
+from .colors import explore_colormaps
+from .bioicons import (
+    BioIcons,
+    plot_icon,
+    plot_icons_grid,
+    IconAnnotation,
+    search_icons,
+    list_categories,
+    list_licenses,
+)
+
+style.use("tvbo")

bsplot/anat.py

@@ -0,0 +1,55 @@
+"""Backwards compatibility module. Use bsplot.volume instead."""
+
+import warnings
+import inspect
+
+# Only warn if imported directly by user code, not by bsplot's __init__.py
+_stack = inspect.stack()
+if len(_stack) >= 2:
+    _caller_filename = _stack[1].filename
+    if "bsplot/__init__.py" not in _caller_filename and "bsplot\\__init__.py" not in _caller_filename:
+        warnings.warn(
+            "bsplot.anat is deprecated, use bsplot.volume instead. "
+            "Also note that plot_img has been renamed to plot_slice.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+del _stack, inspect
+
+from bsplot.volume import (
+    get_center_of_mass,
+    get_cut_coords,
+    get_com_slice_index,
+    get_slice_index,
+    get_world_coords,
+    get_view_index,
+    get_plane_indices,
+    plot_slice,
+    plot_img,
+    translate_com,
+    get_com_view,
+    plot_img_on_bg,
+    plot_brain_schematics,
+    get_world_extent,
+    plot_image_extent,
+    apply_brain_mask,
+)
+
+__all__ = [
+    "get_center_of_mass",
+    "get_cut_coords",
+    "get_com_slice_index",
+    "get_slice_index",
+    "get_world_coords",
+    "get_view_index",
+    "get_plane_indices",
+    "plot_slice",
+    "plot_img",
+    "translate_com",
+    "get_com_view",
+    "plot_img_on_bg",
+    "plot_brain_schematics",
+    "get_world_extent",
+    "plot_image_extent",
+    "apply_brain_mask",
+]

bsplot/animate.py

@@ -0,0 +1,194 @@
+"""Composable animation utilities for 4D neuroimaging data (matplotlib-only).
+
+The core abstraction is :class:`AnimationComposer`, which manages a shared
+timeline and lets you plug in per-axis animation callbacks. All higher-level
+patterns (single view, multi-view, multi-image comparison) can be expressed
+via this composer and a small generic helper.
+"""
+
+import matplotlib.pyplot as plt
+import nibabel as nib
+import numpy as np
+from matplotlib.animation import FuncAnimation
+
+
+class AnimationComposer:
+    """Composable multi-axes animation helper (matplotlib-only).
+
+    This class lets you register per-axis update functions that are called for
+    every frame with the same frame index, so you can build complex, modular
+    animations across several axes.
+
+    Each registered callback should have the signature::
+
+        func(frame_index: int, ax: matplotlib.axes.Axes) -> list[Artist] | Artist | None
+
+    and is expected to draw on the provided axis.
+    """
+
+    def __init__(self, fig, axes, n_frames, interval=100, blit=False):
+        """Create a new AnimationComposer.
+
+        Parameters
+        ----------
+        fig : matplotlib.figure.Figure
+            Parent figure for the animation.
+        axes : Axes or sequence of Axes
+            One or more axes to animate.
+        n_frames : int
+            Number of frames (time points).
+        interval : int, default 100
+            Delay between frames in milliseconds.
+        blit : bool, default False
+            Whether to use blitting.
+        """
+
+        self.fig = fig
+        if hasattr(axes, "__iter__") and not isinstance(axes, (list, tuple)):
+            self.axes = list(axes)
+        elif hasattr(axes, "__iter__"):
+            self.axes = list(axes)
+        else:
+            self.axes = [axes]
+
+        self.n_frames = int(n_frames)
+        self.interval = interval
+        self.blit = blit
+        self._callbacks = []  # list of (ax, func)
+
+    def add_axis_animation(self, ax, func):
+        """Register an animation callback for a given axis.
+
+        Parameters
+        ----------
+        ax : matplotlib.axes.Axes
+            Axis that ``func`` will draw on.
+        func : callable
+            Function with signature ``func(frame_index: int, ax)`` that returns
+            a Matplotlib Artist or a list of Artists (optional).
+        """
+
+        if ax not in self.axes:
+            self.axes.append(ax)
+        self._callbacks.append((ax, func))
+
+    def _update(self, frame):
+        artists = []
+        for ax, func in self._callbacks:
+            res = func(frame, ax)
+            if res is None:
+                continue
+            if isinstance(res, (list, tuple)):
+                artists.extend(res)
+            else:
+                artists.append(res)
+        return artists
+
+    def to_animation(self):
+        """Create and return the underlying FuncAnimation object."""
+
+        anim = FuncAnimation(
+            self.fig,
+            self._update,
+            frames=self.n_frames,
+            interval=self.interval,
+            blit=self.blit,
+        )
+        return anim
+
+
+def _ensure_4d(img_4d):
+    """Load and validate a 4D NIfTI-like image."""
+    if isinstance(img_4d, str):
+        img_4d = nib.load(img_4d)
+    if len(img_4d.shape) != 4:
+        raise ValueError(f"Expected 4D image, got shape {img_4d.shape}")
+    return img_4d
+
+
+def _global_scale_kwargs(img_4d, threshold=0, **plot_kwargs):
+    """Compute global vmin/vmax across time, unless user provided scaling.
+
+    Returns a dict with optional ``vmin``/``vmax`` to forward into ``plot_img``.
+    """
+    if "vmin" in plot_kwargs or "norm" in plot_kwargs:
+        return {}
+
+    data_4d = img_4d.get_fdata()
+    if threshold > 0:
+        masked = np.where(np.abs(data_4d) <= threshold, np.nan, data_4d)
+        vmin = np.nanmin(masked)
+        vmax = np.nanmax(masked)
+    else:
+        nonzero = data_4d[data_4d != 0]
+        vmin = np.nanmin(nonzero) if nonzero.size else np.nanmin(data_4d)
+        vmax = np.nanmax(data_4d)
+
+    contains_negative = np.any(data_4d < 0)
+    if contains_negative:
+        vmax_abs = max(abs(vmin), abs(vmax))
+        vmin, vmax = -vmax_abs, vmax_abs
+
+    return {"vmin": vmin, "vmax": vmax}
+
+
+def animate_axes(fig, axes, n_frames, update_fn, context=None, interval=100, blit=False):
+    """Convenience wrapper to build an animation over one or many axes.
+
+    This captures the common pattern used in the docs: one timeline, multiple
+    axes, and a single user-defined ``update_fn`` that can branch on the axis
+    index and/or shared ``context``.
+
+    Parameters
+    ----------
+    fig : matplotlib.figure.Figure
+        Parent figure for the animation.
+    axes : Axes or sequence of Axes
+        Axes to animate. Can be a single axis, a list/tuple, or any iterable
+        of axes as returned by ``plt.subplots``.
+    n_frames : int
+        Number of frames in the animation.
+    update_fn : callable
+        Function with signature::
+
+            update_fn(frame: int, ax, axis_idx: int, context: dict | None)
+
+        It should draw the desired state for the given ``frame`` on ``ax`` and
+        return a Matplotlib Artist or list of Artists (or ``None``).
+    context : dict or None, optional
+        Arbitrary, user-defined state shared across axes and frames.
+    interval : int, default 100
+        Delay between frames in milliseconds.
+    blit : bool, default False
+        Whether to use blitting.
+
+    Returns
+    -------
+    matplotlib.animation.FuncAnimation
+        The constructed animation object.
+    """
+
+    # Normalize axes into a flat list
+    if hasattr(axes, "__iter__") and not isinstance(axes, (list, tuple)):
+        axes_list = list(axes)
+    elif hasattr(axes, "__iter__"):
+        axes_list = list(axes)
+    else:
+        axes_list = [axes]
+
+    composer = AnimationComposer(fig, axes_list, n_frames=n_frames, interval=interval, blit=blit)
+
+    for axis_idx, ax in enumerate(axes_list):
+
+        def make_cb(idx_):
+            def _cb(frame, ax_cb):
+                return update_fn(frame, ax_cb, idx_, context)
+
+            return _cb
+
+        composer.add_axis_animation(ax, make_cb(axis_idx))
+
+    return composer.to_animation()
+
+
+