pmi-viewer 1.0.0__tar.gz

pmi_viewer-1.0.0/.gitignore

@@ -0,0 +1 @@
+/.idea

pmi_viewer-1.0.0/LICENSE.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026-present Edwin Bennink <H.E.Bennink@umcutrecht.nl>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

pmi_viewer-1.0.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.5
+Name: pmi-viewer
+Version: 1.0.0
+Project-URL: Documentation, https://github.com/umcu-isi/pmi-viewer#readme
+Project-URL: Issues, https://github.com/umcu-isi/pmi-viewer/issues
+Project-URL: Source, https://github.com/umcu-isi/pmi-viewer
+Author-email: Edwin Bennink <H.E.Bennink@umcutrecht.nl>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.8
+Requires-Dist: matplotlib>=3.11.1
+Requires-Dist: numpy>=2.5.1
+Requires-Dist: pyside6>=6.11.2
+Description-Content-Type: text/markdown
+
+# pmi-viewer
+
+[![PyPI - Version](https://img.shields.io/pypi/v/pmi-viewer.svg)](https://pypi.org/project/pmi-viewer)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pmi-viewer.svg)](https://pypi.org/project/pmi-viewer)
+
+-----
+
+`pmi-viewer` is a simple medical image viewer for 2D and 3D NumPy arrays. It supports scrolling through images in
+orthogonal directions and adjusting the display range, similar to other medical image viewers.
+
+In a notebook environment, the viewer is displayed in a new output cell (ipympl required). In other environments, it
+opens in a Qt window.
+
+## Installation
+
+```console
+pip install pmi-viewer
+```
+
+## Usage
+
+```python
+import numpy as np
+from pmi_viewer import view
+
+image = np.random.rand(32, 128, 128)
+view(image, orientation='sag', spacing=(0.7, 0.7, 2.4), title="Random values")
+```
+
+## License
+
+`pmi-viewer` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

pmi_viewer-1.0.0/README.md

@@ -0,0 +1,32 @@
+# pmi-viewer
+
+[![PyPI - Version](https://img.shields.io/pypi/v/pmi-viewer.svg)](https://pypi.org/project/pmi-viewer)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pmi-viewer.svg)](https://pypi.org/project/pmi-viewer)
+
+-----
+
+`pmi-viewer` is a simple medical image viewer for 2D and 3D NumPy arrays. It supports scrolling through images in
+orthogonal directions and adjusting the display range, similar to other medical image viewers.
+
+In a notebook environment, the viewer is displayed in a new output cell (ipympl required). In other environments, it
+opens in a Qt window.
+
+## Installation
+
+```console
+pip install pmi-viewer
+```
+
+## Usage
+
+```python
+import numpy as np
+from pmi_viewer import view
+
+image = np.random.rand(32, 128, 128)
+view(image, orientation='sag', spacing=(0.7, 0.7, 2.4), title="Random values")
+```
+
+## License
+
+`pmi-viewer` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

pmi_viewer-1.0.0/pyproject.toml

@@ -0,0 +1,65 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pmi-viewer"
+dynamic = ["version"]
+description = ''
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+keywords = []
+authors = [
+  { name = "Edwin Bennink", email = "H.E.Bennink@umcutrecht.nl" },
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.8",
+  "Programming Language :: Python :: 3.9",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Implementation :: PyPy",
+]
+dependencies = [
+  "numpy>=2.5.1",
+  "pyside6>=6.11.2",
+  "matplotlib>=3.11.1",
+]
+
+[project.urls]
+Documentation = "https://github.com/umcu-isi/pmi-viewer#readme"
+Issues = "https://github.com/umcu-isi/pmi-viewer/issues"
+Source = "https://github.com/umcu-isi/pmi-viewer"
+
+[tool.hatch.version]
+path = "src/pmi_viewer/__about__.py"
+
+[tool.hatch.envs.types]
+extra-dependencies = [
+  "mypy>=1.0.0",
+]
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:src/pmi_viewer tests}"
+
+[tool.coverage.run]
+source_pkgs = ["pmi_viewer", "tests"]
+branch = true
+parallel = true
+omit = [
+  "src/pmi_viewer/__about__.py",
+]
+
+[tool.coverage.paths]
+pmi_viewer = ["src/pmi_viewer", "*/pmi-viewer/src/pmi_viewer"]
+tests = ["tests", "*/pmi-viewer/tests"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]

pmi_viewer-1.0.0/src/pmi_viewer/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2026-present Edwin Bennink <H.E.Bennink@umcutrecht.nl>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "1.0.0"

pmi_viewer-1.0.0/src/pmi_viewer/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-FileCopyrightText: 2026-present Edwin Bennink <H.E.Bennink@umcutrecht.nl>
+#
+# SPDX-License-Identifier: MIT
+
+from .viewer import view

pmi_viewer-1.0.0/src/pmi_viewer/viewer.py

@@ -0,0 +1,296 @@
+import sys
+from collections import deque
+from typing import Optional, Tuple, Sequence, Literal
+from warnings import warn
+
+import numpy as np
+from PySide6.QtWidgets import QMainWindow, QApplication
+
+# Try to activate interactive plotting for notebooks. This has to be done before importing matplotlib.
+# If ipython is not available (ModuleNotFoundError) or the 'run_line_magic' function does not exist for the
+# interpreter (AttributeError) then we're probably not running from a notebook.
+_is_notebook = False
+try:
+    from IPython import get_ipython
+    ip = get_ipython()
+    ip.run_line_magic("matplotlib", "widget")  # Requires ipympl. Raises a RuntimeError if it is not available.
+    _is_notebook = True
+except (ModuleNotFoundError, AttributeError):
+    pass  # Not a notebook.
+except RuntimeError:
+    warn("ipympl is required for interactive visualization in notebooks. The notebook server (JupyterLab or similar) "
+         "needs to be restarted.")
+
+# Switch to the Qt backend if we're not in a notebook. This has to be done before importing pyplot.
+import matplotlib
+if not _is_notebook:
+    matplotlib.use('qtagg')
+
+import matplotlib.pyplot as plt
+from matplotlib.widgets import Slider
+from matplotlib.backends.backend_qtagg import FigureCanvasQTAgg
+
+
+__all__ = ['StackViewer', 'view']
+
+
+# This queue keeps references to StackViewer objects, because once the garbage collector cleaned them up,
+# interaction no longer works.
+_viewers = deque(maxlen=32)
+
+
+# DICOM defines the linear VOI LUT as:
+#     y = ((x - (c - 0.5)) / (w-1) + 0.5) * (ymax- ymin) + ymin,
+# where c = window center, w = window width, and (ymin, ymax) is the output range, e.g. (0, 255).
+# This is a bit odd, because if we choose (ymin, ymax) = (0, 1), then:
+#     0 = ((vmin - (c - 0.5)) / (w - 1) + 0.5)
+#     1 = ((vmax - (c - 0.5)) / (w - 1) + 0.5)
+# Which means that:
+#     w = vmax - vmin + 1
+#     c = 0.5 * (vmin + vmax + 1)
+
+def _range_to_window(vmin: float | int, vmax: float | int) -> Tuple[float, float]:
+    """
+    Converts a display range (vmin, vmax) into a window level and window width according to the DICOM standard.
+    """
+    wl = 0.5 * (vmax + vmin + 1)
+    ww = vmax - vmin + 1
+
+    return wl, ww
+
+
+def _window_to_range(wl: float | int, ww: float | int) -> Tuple[float, float]:
+    """
+    Converts a window level and window width into a display range (vmin, vmax) according to the DICOM standard.
+    """
+    vmin = wl - 0.5 * ww
+    vmax = wl + 0.5 * ww - 1
+
+    return vmin, vmax
+
+
+# Adapted from https://matplotlib.org/3.5.3/gallery/event_handling/image_slices_viewer.html
+class StackViewer:
+    """
+    A 3D image stack viewer.
+
+    :param data: A 2D or 3D Numpy array in LPS orientation and row-major ordering.
+    :param ax: A matplotlib Axes.
+    :param orientation: 'ax' or 'cor' or 'sag'. Defaults to 'ax'
+    :param spacing: An optional list, tuple or Numpy array with the (x, y, z) spacing.
+    :param slider_ax: An optional matplotlib Axes for the stack slider.
+    """
+    def __init__(self, data: np.ndarray, ax: plt.Axes, orientation: Optional[str] = None, spacing: Optional[Sequence[float] | np.ndarray] = None, slider_ax: Optional[plt.Axes] = None):
+        self.ax = ax
+        self.fig = ax.figure
+
+        if orientation and data.ndim < 3:
+            orientation = None
+            warn("Orientation is ignored for {data.ndim}-dimensional data.")
+        self.orientation = orientation or 'ax'
+
+        if data.ndim == 2:
+            self.data = np.expand_dims(data, axis=0)  # Convert 2D data to 3D by adding a dimension.
+        elif data.ndim == 3:
+            self.data = data
+        else:
+            raise ValueError(f"Cannot handle {data.ndim}-dimensional data.")
+
+        self.nz, self.ny, self.nx = self.data.shape  # Get the number of slices in the 3D stack, and the height and width.
+
+        if spacing is None:
+            spacing = [1, 1, 1]
+
+        # Set aspect ratio and initial position in the stack (starting at index=1).
+        origin: Optional[Literal['upper', 'lower']]
+        if self.orientation == 'ax':
+            origin = 'upper'
+            aspect = spacing[1] / spacing[0]
+            self.slices, h, w = self.nz, self.ny, self.nx
+        elif self.orientation == 'cor':
+            origin = 'lower'
+            aspect = spacing[2] / spacing[0]
+            self.slices, h, w = self.ny, self.nz, self.nx
+        elif self.orientation == 'sag':
+            origin = 'lower'
+            aspect = spacing[2] / spacing[1]
+            self.slices, h, w = self.nx, self.nz, self.ny
+        else:
+            raise ValueError(f"Invalid orientation: {self.orientation}.")
+        self.index = self.slices // 2 + 1
+
+        # Calculate the initial window level and width based on the min and max data value.
+        vmin = float(data.min())
+        vmax = float(data.max())
+        self.wl, self.ww = _range_to_window(vmin, vmax)
+
+        # Show the image.
+        self.im = self.ax.imshow(self.get_slice(), cmap='gray', origin=origin, aspect=aspect, vmin=vmin, vmax=vmax)
+
+        # Show the orientation labels.
+        self._show_orientation_labels(w, h)
+
+        # Show the W/L and stack index annotations.
+        self.update_annotation()
+
+        # Add the optional stack slider.
+        if slider_ax:
+            self.slider = Slider(
+                slider_ax,
+                "",
+                1,
+                self.slices,
+                valinit=self.index,
+                valstep=1,
+                orientation="vertical",
+            )
+            slider_ax.invert_yaxis()
+            self.slider.poly.set_visible(False)
+            self.slider.on_changed(self.set_index)
+        else:
+            self.slider = None
+
+        # Initialize helper variables for the W/L callbacks.
+        self._window_init = (self.wl, self.ww)
+        self._coord_init = (0, 0)
+
+        # Connect callback functions.
+        self.fig.canvas.mpl_connect('scroll_event', self._on_scroll)
+        self.fig.canvas.mpl_connect('button_press_event', self._on_button_press)
+        self.fig.canvas.mpl_connect('motion_notify_event', self._on_motion)
+
+        # If true then scrolling while the mouse is over the canvas will not move the entire webpage.
+        self.fig.canvas.capture_scroll = True
+
+    def _show_orientation_labels(self, w: int, h: int):
+        # Show the orientation annotations. Don't make any assumptions on the orientation of the y-axis for 2D images.
+        if self.orientation in ('ax', 'cor'):
+            self.ax.text(0.05 * w, 0.50 * h, 'R', weight='bold', color='orange', va='center', ha='center')
+            self.ax.text(0.95 * w, 0.50 * h, 'L', weight='bold', color='orange', va='center', ha='center')
+        elif self.orientation == 'sag':
+            self.ax.text(0.05 * w, 0.50 * h, 'A', weight='bold', color='orange', va='center', ha='center')
+            self.ax.text(0.95 * w, 0.50 * h, 'P', weight='bold', color='orange', va='center', ha='center')
+        if self.slices > 1:
+            if self.orientation in ('sag', 'cor'):
+                self.ax.text(0.50 * w, 0.05 * h, 'I', weight='bold', color='orange', va='center', ha='center')
+                self.ax.text(0.50 * w, 0.95 * h, 'S', weight='bold', color='orange', va='center', ha='center')
+            elif self.orientation == 'ax':
+                self.ax.text(0.50 * w, 0.05 * h, 'A', weight='bold', color='orange', va='center', ha='center')
+                self.ax.text(0.50 * w, 0.95 * h, 'P', weight='bold', color='orange', va='center', ha='center')
+
+    def get_slice(self):
+        if self.orientation == 'ax':
+            return self.data[self.index - 1]
+        elif self.orientation == 'cor':
+            return self.data[:, self.index - 1]
+        elif self.orientation == 'sag':
+            return self.data[:, :, self.index - 1]
+        else:
+            raise ValueError(f"Invalid orientation: {self.orientation}.")
+
+    def update_annotation(self):
+        self.ax.set_xlabel(f'WL: {self.wl:.4g} WW: {self.ww:.4g}')
+        self.ax.set_ylabel(f'{self.index} of {self.slices}')
+
+    def set_index(self, index: int | float):
+        index = int(np.clip(index, 1, self.slices))
+
+        if self.slider and self.slider.val != index:
+            self.slider.set_val(index)
+
+        if self.index != index:
+            self.index = index
+            self.update()
+
+    def update(self):
+        self.im.set_data(self.get_slice())
+        self.update_annotation()
+        self.fig.canvas.draw_idle()
+
+    def _on_scroll(self, event: plt.MouseEvent):
+        if event.button == 'up':
+            self.set_index(self.index - 1)
+        else:
+            self.set_index(self.index + 1)
+
+    def _on_button_press(self, event: plt.MouseEvent):
+        if event.button == 1:
+            self._window_init = (self.wl, self.ww)
+            self._coord_init = (event.x, event.y)
+
+    def _on_motion(self, event: plt.MouseEvent):
+        if event.button != 1:
+            return  # Left button is not pressed.
+        if event.inaxes != self.ax:
+            return  # Not inside the image (but e.g. on the scrollbar).
+        if self.fig.canvas.toolbar and self.fig.canvas.toolbar.mode:
+            return  # A toolbar tool is active (e.g. zoom or drag).
+
+        dx = event.x - self._coord_init[0]
+        dy = event.y - self._coord_init[1]
+
+        sensitivity = self._window_init[1] / 500
+        self.wl = self._window_init[0] + sensitivity * dy
+        self.ww = max(self._window_init[1] + sensitivity * dx, 2)
+
+        vmin, vmax = _window_to_range(self.wl, self.ww)
+        self.im.set_clim(vmin=vmin, vmax=vmax)
+        self.update()
+
+
+def view(data: np.ndarray, orientation: Optional[str] = None, spacing:Optional[Sequence[float] | np.ndarray] = None, title:Optional[str] = None):
+    """
+    Shows the given 2D or 3D image stack in a scrollable viewer.
+
+    :param data: A 2D or 3D Numpy array in LPS orientation and row-major ordering.
+    :param orientation: 'ax' or 'cor' or 'sag' (3D data only). Defaults to 'ax'.
+    :param spacing: An optional list, tuple or Numpy array with the (x, y, z) spacing.
+    :param title: An optional figure title.
+    """
+    # Create a matplotlib figure and a layout with 2 columns.
+    if _is_notebook:
+        fig = plt.figure()
+    else:
+        fig = matplotlib.figure.Figure()
+
+    gs = fig.add_gridspec(
+        1, 2,
+        width_ratios=[20, 1],
+        wspace=0.05
+    )
+
+    # Add an Axes for the image.
+    ax = fig.add_subplot(gs[0, 0])
+    if _is_notebook and title:
+        ax.set_title(title)
+
+    # Add an Axes for the slider.
+    if data.ndim > 2:
+        slider_ax = fig.add_subplot(gs[0, 1])
+    else:
+        slider_ax = None
+
+    # Create the viewer.
+    viewer = StackViewer(data, ax, orientation=orientation, spacing=spacing, slider_ax=slider_ax)
+
+    if _is_notebook:
+        # Store the viewer's reference to prevent GC cleanup.
+        _viewers.append(viewer)
+
+        # Show the figure in a new notebook cell.
+        plt.show()
+    else:
+        # Show the figure in a new Qt Window. This should also work from PyCharm with “Show plots in tool window”
+        # enabled.
+        app = QApplication.instance()
+        if app is None:
+            app = QApplication(sys.argv)
+        window = QMainWindow()
+        window.setWindowTitle(title or "Viewer")
+        canvas = FigureCanvasQTAgg(fig)
+        window.setCentralWidget(canvas)
+        window.resize(800, 600)
+        window.show()
+        window.raise_()
+        window.activateWindow()
+        app.exec()

pmi_viewer-1.0.0/tests/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2026-present Edwin Bennink <H.E.Bennink@umcutrecht.nl>
+#
+# SPDX-License-Identifier: MIT