MNutils 1.2.2__tar.gz → 1.2.3__tar.gz

{mnutils-1.2.2 → mnutils-1.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: MNutils
-Version: 1.2.2
+Version: 1.2.3
 Summary: Utility functions for multinuclear MR data processing
 Keywords: mri,mrs,xarray,spectroscopy,nmr
 Author: Sebastian Bauer

{mnutils-1.2.2 → mnutils-1.2.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "MNutils"
-version = "1.2.2"
+version = "1.2.3"
 description = "Utility functions for multinuclear MR data processing"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -69,6 +69,7 @@ build-backend = "uv_build"
 dev = [
     "ipykernel>=7.1.0",
     "ipywidgets>=8.1.7",
+    "python-dotenv",
     "nbmake>=1.5.5",
     "pytest>=8.4.1",
     "ruff>=0.9.0",

{mnutils-1.2.2 → mnutils-1.2.3}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "MNutils"
-version = "1.2.2"
+version = "1.2.3"
 
 authors = [
     {name = "Sebastian Bauer", email = "28663646+bastigw@users.noreply.github.com"}
@@ -65,6 +65,7 @@ dev = [
     # --- Notebooks ---
     "ipykernel>=7.1.0",
     "ipywidgets>=8.1.7",
+    "python-dotenv",
     # --- Testing ---
     "nbmake>=1.5.5",
     "pytest>=8.4.1",

{mnutils-1.2.2 → mnutils-1.2.3}/src/mnutils/GESeries.py

@@ -5,7 +5,6 @@ from functools import cached_property
 from pathlib import Path
 
 import h5py
-import nibabel as nib
 import numpy as np
 import numpy.typing as npt
 import pandas as pd
@@ -96,13 +95,16 @@ class NiiBase:
             else:
                 affine = self.nii.affine
 
-        # Image data is to be oriented the following
-        orientated_data = nib.orientations.apply_orientation(
-            new_data, nib.orientations.axcodes2ornt(("P", "L", "S"))
-        )
+        # new_data's axes already match the index space `affine` describes (e.g. spec's own
+        # (i, j, k) grid, scaled by create_MRSI_affine()) -- no reorientation is warranted here.
+        # A previous version of this method applied a hardcoded apply_orientation(..., ("P", "L",
+        # "S")) permute+flip unconditionally, silently decoupling the stored array from the affine
+        # it was paired with (e.g. RAW_exp's data ending up several voxels from where its own
+        # affine said it was).
+        image_data = np.asarray(new_data)
 
         new_nii = self.nii.__class__(
-            orientated_data,  # pyright: ignore[reportArgumentType]
+            image_data,  # pyright: ignore[reportArgumentType]
             affine=affine.copy(),
             header=self.nii.header,
             extra=self.nii.extra,
@@ -146,6 +148,10 @@ class NiiBase:
             except ValueError as e:
                 logger.error(f"Error applying mask: {e}. Displaying unmasked images.")
 
+        kwargs.setdefault(
+            "zooms",
+            nifti.get_display_zooms(self, orientation=orientation, display_plane=display_plane),
+        )
         plotting.images.display_images(images, **kwargs)
 
     def overlay_on_T1(
@@ -745,13 +751,12 @@ class MRSISeries(RawMRISeries):
         # Round voxel sizes to 3 decimal places to avoid floating point issues
         new_affine[0:3, 0:3] = np.round(new_affine[0:3, 0:3], 3)
 
-        # Offset x and y by centre offset
-        # The shift is important as we want to make sure the overlay is in the correct position
-        # The correct shift is the following
+        # Offset x and y by centre offset.
+        # Both affines use the standard NIfTI convention (index i's *center* sits at
+        # world = voxel_size * i + translation), and both describe the same field of view at
+        # different resolutions, so their voxel-0 centers differ by exactly half the voxel-size
+        # change: new_translation = old_translation + (new_voxel - old_voxel) / 2.
         shift = (np.diag(new_affine[:3]) - np.diag(self.nii.affine[:3])).round(3) / 2
-        # However this creates the correct FOV but the overlay is not in the correct position
-        # For a correct shift we need to add an additonal half voxel
-        shift += np.array([new_affine[0, 0], new_affine[1, 1], 0]) / 2
         logger.trace(
             f"Calculated shift for new affine: {shift}. "
             f"Original affine translation: {self.nii.affine[:3, 3]}"

{mnutils-1.2.2 → mnutils-1.2.3}/src/mnutils/plotting/_widgets/image_grid.js

@@ -150,7 +150,11 @@ function renderWidget(data, el) {
 
   // The frames' aspect ratio decides how wide the panels want to be, and so
   // how wide the whole widget is allowed to grow (see --mnu-panel-w-cap).
-  // Only measurable once a frame has decoded, hence the load handler.
+  // Only measurable once a frame has decoded, hence the load handler. When
+  // `zooms` was passed to `display_images`, the frame itself was already
+  // rendered at a physically-correct pixel size (see image_grid.py /
+  // images.py), so naturalWidth/naturalHeight already *is* the physical
+  // ratio -- no separate correction needed here.
   const syncAspect = () => {
     const img = images.find((candidate) => candidate.naturalWidth);
     if (img) viewer.style.setProperty("--mnu-aspect", String(img.naturalWidth / img.naturalHeight));

{mnutils-1.2.2 → mnutils-1.2.3}/src/mnutils/plotting/images.py

@@ -241,6 +241,7 @@ def display_images(
     vmax: float | None = None,
     v_percentile: float = 1.0,
     zeros_as_nan: bool = False,
+    zooms: tuple[float, float] | None = None,
     **kwargs,
 ) -> None:
     """Display a grid of 2D/3D/4D images, with a slice slider for 3D/4D input.
@@ -283,6 +284,13 @@ def display_images(
         default 1.0.
     zeros_as_nan : bool, optional
         If True, treat zero values as NaN for display, by default False.
+    zooms : tuple[float, float], optional
+        Physical (row, col) voxel edge lengths of the displayed slice, e.g.
+        from `utils.nifti.get_display_zooms`. When given, panels are rendered
+        with an aspect ratio that matches real anatomy instead of one square
+        pixel per voxel; the through-plane spacing is irrelevant since only
+        one 2D slice is ever on screen at a time. Defaults to the pixel-count
+        aspect ratio (square voxels) when omitted.
     **kwargs
         Accepted and ignored: axis parameters such as `aspect`, `xlabel` or
         `xticks` have no Axes to apply to. Kept so existing call sites keep
@@ -393,6 +401,7 @@ def display_images(
         vmin=vmin,
         vmax=vmax,
         per_panel_bounds=colorbar_mode == "each",
+        pixel_aspect=None if zooms is None else zooms[1] / zooms[0],
     )
     ipy_display(
         ImageGridWidget(
@@ -437,6 +446,26 @@ class _Layer(NamedTuple):
     alpha: float = 1.0
 
 
+def _stretch_to_pixel_aspect(array: npt.NDArray, pixel_aspect: float) -> npt.NDArray:
+    """Nearest-neighbour-upscale one axis so the raster's own pixels are voxel-shaped.
+
+    `pixel_aspect` is physical col-spacing / row-spacing. Only ever upscales
+    -- the smaller-per-mm axis grows to match the other -- so no resolution is
+    lost on either axis, unlike scaling both to a common isotropic spacing.
+    Nearest-neighbour (voxel duplication) rather than interpolation: this is a
+    display-only raster, not the analysis data, and duplication is what keeps
+    a hard voxel edge hard instead of blurring it.
+    """
+    rows, cols = array.shape[:2]
+    row_scale = max(1.0, 1.0 / pixel_aspect)
+    col_scale = max(1.0, pixel_aspect)
+    new_rows, new_cols = max(1, round(rows * row_scale)), max(1, round(cols * col_scale))
+    if (new_rows, new_cols) == (rows, cols):
+        return array
+    resized = PIL.Image.fromarray(array).resize((new_cols, new_rows), PIL.Image.NEAREST)
+    return np.asarray(resized)
+
+
 def _render_frames(
     layers: Sequence[_Layer],
     jobs: Sequence[tuple[int, ...]],
@@ -444,6 +473,7 @@ def _render_frames(
     quality: int,
     lossless: bool = False,
     keep_alpha: bool = False,
+    pixel_aspect: float | None = None,
     max_workers: int = 8,
 ) -> list[bytes]:
     """Render a batch of colormapped rasters to WebP bytes, one per job.
@@ -476,6 +506,11 @@ def _render_frames(
     small hard-edged images, where the ringing shows and the payload argument
     disappears. `keep_alpha` carries the colormap's "bad" pixels (NaN) through
     as transparent instead of flattening them onto a baked-in background.
+    `pixel_aspect`, when given, upscales one axis of the composite (see
+    `_stretch_to_pixel_aspect`) so the frame's own dimensions already encode
+    the physical voxel aspect ratio -- the browser then needs no separate
+    aspect correction and stays on the same natural-size sizing path as the
+    unscaled case.
 
     WebP encoding releases the GIL, so frames are encoded on a thread pool.
     """
@@ -510,6 +545,8 @@ def _render_frames(
             ) // 255
 
         assert composite is not None, "at least one layer is required"
+        if pixel_aspect is not None:
+            composite = _stretch_to_pixel_aspect(composite, pixel_aspect)
         if keep_alpha:
             return _encode_webp(composite, "RGBA", quality=quality, lossless=lossless)
         return _encode_webp(
@@ -541,6 +578,7 @@ def _render_image_grid_frames(
     vmin: float | None,
     vmax: float | None,
     per_panel_bounds: bool,
+    pixel_aspect: float | None = None,
     quality: int = GRID_FRAME_QUALITY,
     max_workers: int = 8,
 ) -> tuple[list[list[bytes]], list[list[tuple[float, float]]]]:
@@ -579,6 +617,7 @@ def _render_image_grid_frames(
         quality=quality,
         lossless=images.shape[0] * images.shape[1] <= GRID_LOSSLESS_MAX_PIXELS,
         keep_alpha=True,
+        pixel_aspect=pixel_aspect,
         max_workers=max_workers,
     )
     return [rendered[s * num_images : (s + 1) * num_images] for s in range(n_slices)], bounds

{mnutils-1.2.2 → mnutils-1.2.3}/src/mnutils/testing/_spectra.py

@@ -22,9 +22,15 @@ from loguru import logger
 from numpy.typing import ArrayLike
 
 _TEMPLATE_URL = "https://raw.githubusercontent.com/neurolabusc/niivue-images/main/chris_t1.nii.gz"
+# Same subject, same repo/license as _TEMPLATE_URL -- a real 2D-acquired proton-density scan, kept
+# at its native (anisotropic) voxel size rather than resampled, so it's the fixture that actually
+# exercises display_images' zooms aspect correction (issue #35). See write_template_pd.
+_TEMPLATE_PD_URL = (
+    "https://raw.githubusercontent.com/neurolabusc/niivue-images/main/chris_PD.nii.gz"
+)
 _TEMPLATE_ATTRIBUTION = (
-    "T1 anatomical fixtures are resampled from Chris Rorden's 'chris_t1', part of the "
-    "niivue-images sample set (https://github.com/neurolabusc/niivue-images), licensed "
+    "T1 and PD anatomical fixtures are resampled from Chris Rorden's 'chris_t1'/'chris_PD', part "
+    "of the niivue-images sample set (https://github.com/neurolabusc/niivue-images), licensed "
     "CC BY-NC 4.0 (https://creativecommons.org/licenses/by-nc/4.0/) -- non-commercial use only."
 )
 
@@ -184,13 +190,13 @@ def grid_own_affine(
 def rescale_affine_xy(affine: np.ndarray, old_matrix_xy: int, new_matrix_xy: int) -> np.ndarray:
     """Same affine, x/y voxel size rescaled for a different in-plane matrix.
 
-    `GESeries.MRSISeries.create_MRSI_affine()` derives `RAW_exp`'s affine from this one's voxel
-    size via a shift correction tuned assuming the own NIfTI's resolution roughly matches the
-    blocky MRSI grid's (`own_diag/2`, meant to be a half-*blocky*-voxel nudge). A much finer own
-    NIfTI (e.g. an interpolated pseudo image) makes that term negligible instead, dragging
-    `RAW_exp`'s translation off by about half the *old* voxel size. Shifting this affine's own
-    translation by `(new_voxel - old_voxel) / 2` exactly cancels that drift, so
-    `create_MRSI_affine()`'s output is unchanged no matter this affine's own resolution.
+    Both affines use the standard NIfTI convention (index `i`'s *center* sits at
+    `world = voxel_size * i + translation`) and describe the same field of view at different
+    resolutions, so their voxel-0 centers differ by exactly half the voxel-size change --
+    `new_translation = old_translation + (new_voxel - old_voxel) / 2`. That is also exactly what
+    `GESeries.MRSISeries.create_MRSI_affine()` does going the other way (fine -> blocky), so
+    `create_MRSI_affine()` applied to this function's output reproduces `affine`'s own
+    translation exactly, regardless of `affine`'s own resolution.
     """
     scaled = affine.copy()
     old_voxel = np.array([affine[0, 0], affine[1, 1]])
@@ -243,7 +249,7 @@ class SphereRing:
 
     name: str
     n_spheres: int = 8
-    ring_radius_mm: float = 60.0
+    ring_radius_mm: float = 40.0
     z_offset_mm: float = 20.0
     sphere_radius_mm: float = 10.0
     intensity_range: tuple[float, float] = (0.3, 1.0)
@@ -265,7 +271,32 @@ class SphereRing:
         return out
 
 
-DEFAULT_SPHERE_RINGS: list[SphereRing] = [SphereRing(name="metabolite_ring")]
+DEFAULT_SPHERE_RINGS: list[SphereRing] = [
+    SphereRing(
+        name="metabolite_ring",
+        n_spheres=8,
+        ring_radius_mm=45.0,
+        z_offset_mm=5.0,
+        sphere_radius_mm=12.0,
+        intensity_range=(0.2, 1),
+    )
+]
+
+# A ring with no corresponding spectra -- `sphere_grid_intensity` never sees these, only
+# `sphere_phantom_image` does, so they show up as extra anatomical structure with zero MRSI
+# signal (a real phantom always has more visible structure than the spectroscopy sequence
+# actually excites). Offset to the opposite side of the central slice from DEFAULT_SPHERE_RINGS
+# so the two rings stay visually distinct despite both sitting near z=0.
+ANATOMY_ONLY_SPHERE_RINGS: list[SphereRing] = [
+    SphereRing(
+        name="anatomy_only_ring",
+        n_spheres=6,
+        ring_radius_mm=10.0,
+        z_offset_mm=-5.0,
+        sphere_radius_mm=6.0,
+        intensity_range=(0.4, 0.9),
+    )
+]
 
 
 def sphere_intensity(world_xyz: np.ndarray, rings: list[SphereRing]) -> np.ndarray:
@@ -304,25 +335,19 @@ def sphere_grid_intensity(
 # --- Real T1 template (brain-shaped anatomy) ----------------------------------------------------
 
 
-def _template_cache_path() -> Path:
-    return Path(tempfile.gettempdir()) / "mnutils_template_cache" / "chris_t1.nii.gz"
-
-
-def _fetch_t1_template_path() -> Path:
-    """Download the CC BY-NC 4.0 template once per machine, cached under the system temp dir."""
-    cache = _template_cache_path()
+def _download_and_cache(url: str, cache_name: str) -> Path:
+    """Download `url` once per machine, cached under the system temp dir."""
+    cache = Path(tempfile.gettempdir()) / "mnutils_template_cache" / cache_name
     if not cache.is_file():
         cache.parent.mkdir(parents=True, exist_ok=True)
-        logger.info(f"Downloading T1 template fixture from {_TEMPLATE_URL} to {cache}")
-        with urllib.request.urlopen(_TEMPLATE_URL, timeout=30) as response:  # noqa: S310
+        logger.info(f"Downloading template fixture from {url} to {cache}")
+        with urllib.request.urlopen(url, timeout=30) as response:  # noqa: S310
             cache.write_bytes(response.read())
     return cache
 
 
-@functools.cache
-def _cropped_template() -> tuple[np.ndarray, np.ndarray]:
-    """The template's data cropped to its non-background bounding box, and the matching affine."""
-    img = nib.load(_fetch_t1_template_path())
+def _crop_nonbackground(img: nib.Nifti1Image) -> tuple[np.ndarray, np.ndarray]:
+    """Crop `img`'s data to its non-background bounding box; return data and the matching affine."""
     data = np.asarray(img.get_fdata(), dtype=np.float32)
     mask = data > (data.max() * 0.05)
     idx = np.array(np.where(mask))
@@ -333,6 +358,17 @@ def _cropped_template() -> tuple[np.ndarray, np.ndarray]:
     return cropped, affine
 
 
+def _fetch_t1_template_path() -> Path:
+    """Download the CC BY-NC 4.0 T1 template once per machine, cached under the system temp dir."""
+    return _download_and_cache(_TEMPLATE_URL, "chris_t1.nii.gz")
+
+
+@functools.cache
+def _cropped_template() -> tuple[np.ndarray, np.ndarray]:
+    """T1 template data cropped to its non-background bounding box, and the matching affine."""
+    return _crop_nonbackground(nib.load(_fetch_t1_template_path()))
+
+
 def write_template_t1(path: Path) -> None:
     """Write the cropped, full-resolution template as an anatomical NIfTI."""
     data, affine = _cropped_template()
@@ -340,6 +376,29 @@ def write_template_t1(path: Path) -> None:
     nib.save(nib.Nifti1Image(data, affine), path)
 
 
+def _fetch_pd_template_path() -> Path:
+    """Download the CC BY-NC 4.0 PD template once per machine, cached under the system temp dir."""
+    return _download_and_cache(_TEMPLATE_PD_URL, "chris_pd.nii.gz")
+
+
+@functools.cache
+def _cropped_pd_template() -> tuple[np.ndarray, np.ndarray]:
+    """PD template data cropped to its non-background bounding box, and the matching affine."""
+    return _crop_nonbackground(nib.load(_fetch_pd_template_path()))
+
+
+def write_template_pd(path: Path) -> None:
+    """Write the cropped, full-resolution PD template as an anatomical NIfTI.
+
+    Unlike `write_template_t1`, this is kept at its native 0.86x0.86x2.4mm voxel size -- a real 2D
+    -acquired scan's in-plane vs. slice-thickness anisotropy, not resampled to isotropic -- so it's
+    the fixture that exercises `display_images`' `zooms` aspect correction (issue #35).
+    """
+    data, affine = _cropped_pd_template()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    nib.save(nib.Nifti1Image(data, affine), path)
+
+
 def template_grid_intensity(grid: tuple[int, int, int]) -> tuple[np.ndarray, np.ndarray]:
     """Downsample the template onto `grid`; returns `(own_affine, intensity_map in [0, 1])`.
 
@@ -375,14 +434,13 @@ def template_grid_intensity(grid: tuple[int, int, int]) -> tuple[np.ndarray, np.
     intensity_map = np.maximum(intensity_map, 0.0)
     own_affine = np.diag([*voxel_size, 1.0])
     own_affine[:3, 3] = affine[:3, 3]
-    # MRSISeries.create_MRSI_affine() always adds an extra half-*blocky*-voxel shift in x/y on top
-    # of its resize shift (tuned for real GE headers, where the "fine" reference affine needs it).
     # For grid_mode=True zoom, blocky voxel i's true center is:
     #   native_translation + blocky_voxel*(i + 0.5) - native_voxel/2
-    # i.e. own_affine's translation should be native_translation - native_voxel/2 to land there once
-    # create_MRSI_affine's own +blocky_voxel/2 shift is added back on top -- the blocky_voxel terms
-    # cancel exactly, so the correction here is half a *native* voxel, not half the blocky one.
-    own_affine[:2, 3] -= voxel_native[:2] / 2
+    # i.e. as a diag affine's translation (the world position of index 0): native_translation +
+    # blocky_voxel/2 - native_voxel/2. This holds on every axis, independent of
+    # `create_MRSI_affine()`/`rescale_affine_xy()` -- own_affine is this function's own ground
+    # truth, derived purely from how the template was downsampled.
+    own_affine[:3, 3] += voxel_size / 2 - voxel_native / 2
     return own_affine, intensity_map
 
 

{mnutils-1.2.2 → mnutils-1.2.3}/src/mnutils/testing/synthetic.py

@@ -220,6 +220,10 @@ def _build_brain_mrs_mrsi_exam(root: Path) -> None:
 
     # The real T1 template, cropped to the head -- see _spectra._TEMPLATE_ATTRIBUTION.
     _spectra.write_template_t1(data / "002_3D_Ax_T1_BRAVO" / "2_3D_Ax_T1_BRAVO.nii.gz")
+    # Same subject, real 2D-acquired PD scan at its native anisotropic voxel size -- the fixture
+    # docs/data-model/geseries.md uses to show display_images' zooms aspect correction actually
+    # doing something, which the (isotropic) T1 above can't demonstrate.
+    _spectra.write_template_pd(data / "004_2D_Ax_PD" / "4_2D_Ax_PD.nii.gz")
 
     # Series 8's intensity map seeds create_MRSI_affine's reference voxel size *and* the
     # per-grid-cell simulate_grid scaling below -- real brain signal in, brain-shaped spectra out.
@@ -326,20 +330,24 @@ def _build_nist_phantom_exam(root: Path) -> None:
     data = root / "data"
     exam = data / "ExamNISTanon"
     grid = (16, 16, 16)
-    fov_mm = 300.0  # -> 14 mm in-plane voxels, comfortably resolves the 8-sphere ring
+    fov_mm = 300.0  # -> 14 mm in-plane voxels, comfortably resolves the sphere rings
     z_extent_mm = 300.0
-    rings = _spectra.DEFAULT_SPHERE_RINGS
+    signal_rings = _spectra.DEFAULT_SPHERE_RINGS
+    # The anatomical phantom shows more structure than the spectroscopy sequence excites --
+    # ANATOMY_ONLY_SPHERE_RINGS never reaches sphere_grid_intensity, so those spheres carry no
+    # MRSI signal at all, only a T1-visible presence.
+    anatomy_rings = signal_rings + _spectra.ANATOMY_ONLY_SPHERE_RINGS
 
     _spectra.sphere_phantom_image(
         data / "002_3D_Ax_T1_BRAVO" / "2_3D_Ax_T1_BRAVO.nii.gz",
         shape=(128, 128, 100),
         voxel_mm=1,
-        rings=rings,
+        rings=anatomy_rings,
         seed=2,
     )
 
     intensity_map, voxel_xy = _spectra.sphere_grid_intensity(
-        grid, fov_mm=fov_mm, z_extent_mm=z_extent_mm, rings=rings
+        grid, fov_mm=fov_mm, z_extent_mm=z_extent_mm, rings=signal_rings
     )
     own_affine = _spectra.grid_own_affine(grid, (voxel_xy, voxel_xy, z_extent_mm / grid[2]))
 

{mnutils-1.2.2 → mnutils-1.2.3}/src/mnutils/utils/file_helpers.py

@@ -68,11 +68,13 @@ def get_all_dicom_series_ids(data_folder: str | Path) -> tuple[list[int], list[i
 
     # Only flag gaps within the low, dense protocol-step range (series <= 99).
     # Series >= 100 are reformats/resaves with sparse-by-design numbering
-    # (e.g. 500/501, 40003) and must never be flagged as "missing".
+    # (e.g. 500/501, 40003) and must never be flagged as "missing" -- nor may
+    # they stretch the checked range: it ends at the last series <= 99 that
+    # actually exists, not at 99.
+    dense = [n for n in series_numbers if n <= 99]
     missing = []
-    if series_numbers[0] <= 99:
-        dense_range = range(series_numbers[0], min(series_numbers[-1], 99) + 1)
-        missing = sorted(set(dense_range) - set(series_numbers))
+    if dense:
+        missing = sorted(set(range(dense[0], dense[-1] + 1)) - set(dense))
     if missing:
         logger.error(f"Missing series IDs: {missing}. DOUBLE CHECK DATA FOLDER!")
 

{mnutils-1.2.2 → mnutils-1.2.3}/src/mnutils/utils/nifti.py

@@ -24,22 +24,66 @@ DEFAULT_RESAMPLE_PARAMS = {
 type DISPLAY_PLANES = Literal["axial", "coronal", "sagittal"]
 
 
+def _resolve_orientation(
+    orientation: tuple[str, str, str] | None, display_plane: DISPLAY_PLANES | None
+) -> tuple[str, str, str]:
+    """Resolve the target axis codes from `orientation`/`display_plane`.
+
+    Shared by `orient_nifti` and `get_display_affine` so the two can't drift apart.
+    """
+    if display_plane is not None:
+        match display_plane:
+            case "axial":
+                orientation = ("L", "P", "S")
+            case "coronal":
+                orientation = ("L", "I", "P")
+            case "sagittal":
+                orientation = ("I", "L", "P")
+            case _:
+                orientation = DEFAULT_PARAMS["orientation"]
+        logger.debug(f"Orienting NIfTI to {display_plane} plane. Using orientation {orientation}.")
+        return orientation
+
+    if orientation is None:
+        logger.debug(
+            f"No orientation specified. Using default orientation: {DEFAULT_PARAMS['orientation']}."
+        )
+        return DEFAULT_PARAMS["orientation"]
+
+    return orientation
+
+
 def get_display_affine(
     nii: spatialimages.SpatialImage | GESeries.NiiBase,
-    orientation: tuple[str, str, str] = ("L", "P", "S"),
+    orientation: tuple[str, str, str] | None = None,
+    display_plane: DISPLAY_PLANES | None = None,
 ) -> npt.NDArray[np.float64]:
     """Return the affine mapping display voxel indices (after orient_nifti) to world mm.
 
     orient_nifti applies apply_orientation then flipud(rot90(k=1)) which equals
     a transpose of axes 0 and 1. This function encodes both steps as an affine.
     Use inv(get_display_affine(t1)) @ mrsi_affine to get mrsi→display mapping.
+
+    Parameters
+    ----------
+    nii : nibabel.spatialimages.SpatialImage or GESeries.NiiBase
+        The image to compute the display affine for.
+    orientation : tuple[str, str, str], optional
+        Target axis codes. Defaults to `DEFAULT_PARAMS["orientation"]` if
+        neither this nor `display_plane` is given.
+    display_plane : {"axial", "coronal", "sagittal"}, optional
+        If given, overrides `orientation` with a preset for the named plane,
+        matching `orient_nifti`.
     """
     if isinstance(nii, GESeries.NiiBase):
         nii: spatialimages.SpatialImage = nii.nii
-    current_ornt = nib.orientations.io_orientation(nii.affine)
+    orientation = _resolve_orientation(orientation, display_plane)
+    # Reorient with the target axcodes applied directly (not composed with the
+    # image's current orientation via ornt_transform) -- orient_nifti does the same on
+    # the data via apply_orientation, and the two must use the identical permutation
+    # or the zooms end up describing axes other than the ones actually displayed.
     target_ornt = nib.orientations.axcodes2ornt(orientation)
-    transform = nib.orientations.ornt_transform(current_ornt, target_ornt)
-    reoriented = nii.as_reoriented(transform)  # pyright: ignore[reportArgumentType]
+    reoriented = nii.as_reoriented(target_ornt)
     oriented_affine = np.asarray(reoriented.affine, dtype=float)
     # flipud(rot90(k=1, axes=(0,1))) = pure transpose of axes 0 and 1.
     # This swaps columns 0 and 1 of the affine.
@@ -49,6 +93,26 @@ def get_display_affine(
     return oriented_affine @ P
 
 
+def get_display_zooms(
+    nii: spatialimages.SpatialImage | GESeries.NiiBase,
+    orientation: tuple[str, str, str] | None = None,
+    display_plane: DISPLAY_PLANES | None = None,
+) -> tuple[float, float]:
+    """Return the (row, col) physical voxel edge lengths of the displayed grid, in mm.
+
+    The column norms of `get_display_affine`'s first two columns give the
+    physical spacing along the two in-plane axes `orient_nifti` puts at
+    positions 0 and 1 -- correct even for oblique/rotated affines, unlike
+    reading `nii.header.get_zooms()` and guessing which entries survived the
+    reorientation/transpose. Meant to be passed straight through as
+    `display_images(..., zooms=...)`.
+    """
+    display_affine = get_display_affine(nii, orientation=orientation, display_plane=display_plane)
+    row_spacing = float(np.linalg.norm(display_affine[:3, 0]))
+    col_spacing = float(np.linalg.norm(display_affine[:3, 1]))
+    return row_spacing, col_spacing
+
+
 def orient_nifti(
     nii: spatialimages.SpatialImage | GESeries.NiiBase,
     orientation: tuple[str, str, str] | None = None,
@@ -82,23 +146,7 @@ def orient_nifti(
     """
     if isinstance(nii, GESeries.NiiBase):
         nii: spatialimages.SpatialImage = nii.nii
-    if display_plane is not None:
-        match display_plane:
-            case "axial":
-                orientation = ("L", "P", "S")
-            case "coronal":
-                orientation = ("L", "I", "P")
-            case "sagittal":
-                orientation = ("I", "L", "P")
-            case _:
-                orientation = DEFAULT_PARAMS["orientation"]
-        logger.debug(f"Orienting NIfTI to {display_plane} plane. Using orientation {orientation}.")
-
-    if orientation is None:
-        logger.debug(
-            f"No orientation specified. Using default orientation: {DEFAULT_PARAMS['orientation']}."
-        )
-        orientation = DEFAULT_PARAMS["orientation"]
+    orientation = _resolve_orientation(orientation, display_plane)
 
     if caching:
         logger.debug(