ndslice 0.7.0__tar.gz → 0.8.0__tar.gz

{ndslice-0.7.0 → ndslice-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ndslice
-Version: 0.7.0
+Version: 0.8.0
 Summary: Interactive N-dimensional numpy array viewer with FFT support
 Author-email: Henric Rydén <henric.ryden@gmail.com>
 License-Expression: MIT
@@ -26,6 +26,8 @@ License-File: LICENSE
 Requires-Dist: numpy>=1.20.0
 Requires-Dist: pyqtgraph>=0.14.0
 Requires-Dist: PyQt5>=5.15.0
+Requires-Dist: platformdirs>=3.0.0
+Requires-Dist: tomli>=1.1.0; python_version < "3.11"
 Requires-Dist: h5py>=3.0.0
 Requires-Dist: scipy>=1.7.0
 Requires-Dist: pydicom>=2.4.0
@@ -67,6 +69,8 @@ pha = np.pi/4 * (X + Y + Z)
 complex_data = mag * np.exp(1j * pha)
 
 ndslice(complex_data, title='3D Complex Gaussian')
+# Optional dimension labels:
+ndslice(data, dim_labels=["X", "Y", "Z"])
 ```
 
 ![Showcase](docs/images/showcase.gif)
@@ -129,8 +133,14 @@ ndslice(data1, block=True)  # Script pauses here
 ndslice(data2)  # Shown after first closes
 ```
 
+If Qt is already initialized in the current process, `ndslice(..., block=False)`
+cannot safely fork a child process. In that case:
+
+- In IPython/Jupyter with `%gui qt`, ndslice opens inline in the current process (still non-blocking).
+- Without an active Qt event loop, ndslice falls back to blocking mode and emits a warning.
 
 ### Command Line
+
 ```bash
 ndslice data.npy # Numpy file
 ndslice image.nii.gz

{ndslice-0.7.0 → ndslice-0.8.0}/README.md

@@ -25,6 +25,8 @@ pha = np.pi/4 * (X + Y + Z)
 complex_data = mag * np.exp(1j * pha)
 
 ndslice(complex_data, title='3D Complex Gaussian')
+# Optional dimension labels:
+ndslice(data, dim_labels=["X", "Y", "Z"])
 ```
 
 ![Showcase](docs/images/showcase.gif)
@@ -87,8 +89,14 @@ ndslice(data1, block=True)  # Script pauses here
 ndslice(data2)  # Shown after first closes
 ```
 
+If Qt is already initialized in the current process, `ndslice(..., block=False)`
+cannot safely fork a child process. In that case:
+
+- In IPython/Jupyter with `%gui qt`, ndslice opens inline in the current process (still non-blocking).
+- Without an active Qt event loop, ndslice falls back to blocking mode and emits a warning.
 
 ### Command Line
+
 ```bash
 ndslice data.npy # Numpy file
 ndslice image.nii.gz

{ndslice-0.7.0 → ndslice-0.8.0}/ndslice/__main__.py

@@ -6,7 +6,7 @@ import argparse
 import numpy as np
 from pathlib import Path
 from .ndslice import ndslice
-from .selectors import H5DatasetSelector, NpzDatasetSelector, MatDatasetSelector
+from .selectors import h5_selector_for_path, NpzDatasetSelector, MatDatasetSelector
 from .file_interpreters import load_path
 
 
@@ -50,13 +50,15 @@ For files with multiple datasets (HDF5, NPZ, MAT), a GUI selector will automatic
                 detected_format = loaded.metadata.get('detected_format')
                 if detected_format:
                     title = f"{title} [{detected_format}]"
-                ndslice(data=loaded.data, title=title, block=False, filepath=filepath)
+                ndslice(data=loaded.data, title=title, block=False, filepath=filepath,
+                        dim_labels=loaded.metadata.get('dim_labels'),
+                        voxel_spacing=loaded.metadata.get('voxel_spacing'))
                 continue
             
             # Multi-dataset formats - use selectors
             selector = None
             if suffix in ['.h5', '.hdf5']:
-                selector = H5DatasetSelector(filepath)
+                selector = h5_selector_for_path(filepath)
             elif suffix == '.npz':
                 selector = NpzDatasetSelector(filepath)
             elif suffix == '.mat':
@@ -77,4 +79,4 @@ For files with multiple datasets (HDF5, NPZ, MAT), a GUI selector will automatic
 
 
 if __name__ == '__main__':
-    main()
+    main()

ndslice-0.8.0/ndslice/config.py

@@ -0,0 +1,185 @@
+"""Persistent user configuration for ndslice."""
+
+from dataclasses import dataclass, replace
+from pathlib import Path
+from platformdirs import user_config_dir
+
+try:
+    import tomllib
+except ImportError:  # pragma: no cover - exercised only on Python < 3.11
+    import tomli as tomllib
+
+
+INITIAL_INDEX_FIRST = "first"
+INITIAL_INDEX_CENTER = "center"
+INITIAL_INDEX_LAST = "last"
+VALID_INITIAL_INDEX = {INITIAL_INDEX_FIRST, INITIAL_INDEX_CENTER, INITIAL_INDEX_LAST}
+DEFAULT_SLICE_FIRST = "first"
+DEFAULT_SLICE_LAST = "last"
+VALID_DEFAULT_SLICE = {DEFAULT_SLICE_FIRST, DEFAULT_SLICE_LAST}
+
+DEFAULT_COLORMAP = "gray"
+ANGLE_COLORMAP_SAME = "same"
+DEFAULT_CHANNEL = "auto"
+SUPPORTED_CHANNELS = (
+    "auto",
+    "real",
+    "abs",
+    "imag",
+    "angle",
+)
+DEFAULT_ORIGIN = "lower_left"
+SUPPORTED_ORIGINS = (
+    "upper_left",
+    "lower_left",
+    "upper_right",
+    "lower_right",
+)
+DEFAULT_DISPLAY_MODE = "square_pixels"
+SUPPORTED_DISPLAY_MODES = (
+    "square_pixels",
+    "square_fov",
+    "auto",
+)
+DISPLAY_MODE_ALIASES = {
+    "fit": "auto",
+}
+
+
+@dataclass(frozen=True)
+class ViewerConfig:
+    initial_index: str = INITIAL_INDEX_FIRST
+    default_slice: str = DEFAULT_SLICE_FIRST
+    initial_origin: str = DEFAULT_ORIGIN
+    default_channel: str = DEFAULT_CHANNEL
+    default_colormap: str = DEFAULT_COLORMAP
+    angle_colormap: str = ANGLE_COLORMAP_SAME
+    default_display_mode: str = DEFAULT_DISPLAY_MODE
+
+
+def get_config_path():
+    return Path(user_config_dir("ndslice", appauthor=False)) / "config.toml"
+
+
+def load_config(path=None, colormap_names=None):
+    """Load user config, falling back to defaults for any invalid value."""
+    config_path = Path(path) if path is not None else get_config_path()
+    valid_colormaps = tuple(colormap_names) if colormap_names is not None else None
+
+    try:
+        raw = tomllib.loads(config_path.read_text(encoding="utf-8"))
+    except Exception:
+        return ViewerConfig()
+
+    startup = raw.get("startup", {})
+    if not isinstance(startup, dict):
+        startup = {}
+
+    display = raw.get("display", {})
+    if not isinstance(display, dict):
+        display = {}
+
+    initial_index = startup.get("initial_index", INITIAL_INDEX_FIRST)
+    if initial_index not in VALID_INITIAL_INDEX:
+        initial_index = INITIAL_INDEX_FIRST
+
+    default_slice = startup.get("default_slice", DEFAULT_SLICE_FIRST)
+    if default_slice not in VALID_DEFAULT_SLICE:
+        default_slice = DEFAULT_SLICE_FIRST
+
+    initial_origin = startup.get("initial_origin", DEFAULT_ORIGIN)
+    if initial_origin not in SUPPORTED_ORIGINS:
+        initial_origin = DEFAULT_ORIGIN
+
+    default_channel = display.get("default_channel", DEFAULT_CHANNEL)
+    if default_channel not in SUPPORTED_CHANNELS:
+        default_channel = DEFAULT_CHANNEL
+
+    default_colormap = display.get("default_colormap", DEFAULT_COLORMAP)
+    if valid_colormaps is not None and default_colormap not in valid_colormaps:
+        default_colormap = DEFAULT_COLORMAP
+
+    angle_colormap = display.get("angle_colormap", ANGLE_COLORMAP_SAME)
+    valid_angle_colormaps = (
+        (ANGLE_COLORMAP_SAME,) + valid_colormaps
+        if valid_colormaps is not None
+        else None
+    )
+    if valid_angle_colormaps is not None and angle_colormap not in valid_angle_colormaps:
+        angle_colormap = ANGLE_COLORMAP_SAME
+
+    default_display_mode = display.get("default_display_mode", DEFAULT_DISPLAY_MODE)
+    default_display_mode = DISPLAY_MODE_ALIASES.get(default_display_mode, default_display_mode)
+    if default_display_mode not in SUPPORTED_DISPLAY_MODES:
+        default_display_mode = DEFAULT_DISPLAY_MODE
+
+    return ViewerConfig(
+        initial_index=initial_index,
+        default_slice=default_slice,
+        initial_origin=initial_origin,
+        default_channel=default_channel,
+        default_colormap=default_colormap,
+        angle_colormap=angle_colormap,
+        default_display_mode=default_display_mode,
+    )
+
+
+def save_config(config, path=None, colormap_names=None):
+    """Write the complete viewer config to TOML."""
+    config_path = Path(path) if path is not None else get_config_path()
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    valid_colormaps = tuple(colormap_names) if colormap_names is not None else None
+
+    initial_index = config.initial_index
+    if initial_index not in VALID_INITIAL_INDEX:
+        initial_index = INITIAL_INDEX_FIRST
+
+    default_slice = config.default_slice
+    if default_slice not in VALID_DEFAULT_SLICE:
+        default_slice = DEFAULT_SLICE_FIRST
+
+    initial_origin = config.initial_origin
+    if initial_origin not in SUPPORTED_ORIGINS:
+        initial_origin = DEFAULT_ORIGIN
+
+    default_channel = config.default_channel
+    if default_channel not in SUPPORTED_CHANNELS:
+        default_channel = DEFAULT_CHANNEL
+
+    default_colormap = config.default_colormap
+    if valid_colormaps is not None and default_colormap not in valid_colormaps:
+        default_colormap = DEFAULT_COLORMAP
+
+    angle_colormap = config.angle_colormap
+    valid_angle_colormaps = (
+        (ANGLE_COLORMAP_SAME,) + valid_colormaps
+        if valid_colormaps is not None
+        else None
+    )
+    if valid_angle_colormaps is not None and angle_colormap not in valid_angle_colormaps:
+        angle_colormap = ANGLE_COLORMAP_SAME
+
+    default_display_mode = config.default_display_mode
+    default_display_mode = DISPLAY_MODE_ALIASES.get(default_display_mode, default_display_mode)
+    if default_display_mode not in SUPPORTED_DISPLAY_MODES:
+        default_display_mode = DEFAULT_DISPLAY_MODE
+
+    text = (
+        "[startup]\n"
+        f'initial_index = "{initial_index}"\n'
+        f'default_slice = "{default_slice}"\n'
+        f'initial_origin = "{initial_origin}"\n'
+        "\n"
+        "[display]\n"
+        f'default_channel = "{default_channel}"\n'
+        f'default_colormap = "{default_colormap}"\n'
+        f'angle_colormap = "{angle_colormap}"\n'
+        f'default_display_mode = "{default_display_mode}"\n'
+    )
+    config_path.write_text(text, encoding="utf-8")
+
+
+def update_config(path=None, colormap_names=None, **changes):
+    config = replace(load_config(path, colormap_names=colormap_names), **changes)
+    save_config(config, path, colormap_names=colormap_names)
+    return config

{ndslice-0.7.0 → ndslice-0.8.0}/ndslice/file_interpreters.py

@@ -23,6 +23,75 @@ def remove_trailing_singletons(data):
     return data.reshape(shape[:dim+1])
 
 
+def _nifti_dim_labels(ndim):
+    labels = [''] * ndim
+    for dim, label in enumerate(('X', 'Y', 'Z', 'T')):
+        if dim < ndim:
+            labels[dim] = label
+    return labels
+
+
+def _valid_spacing_value(value):
+    try:
+        value = float(value)
+    except (TypeError, ValueError):
+        return None
+    return value if np.isfinite(value) and value > 0 else None
+
+
+def _nifti_voxel_spacing(zooms, ndim):
+    spacing = [None] * ndim
+    for dim in range(min(ndim, 3, len(zooms))):
+        spacing[dim] = _valid_spacing_value(zooms[dim])
+    return spacing
+
+
+def _dicom_pixel_voxel_spacing(pixel_spacing, ndim):
+    spacing = [None] * ndim
+    if pixel_spacing is None or ndim < 2:
+        return spacing
+
+    values = list(pixel_spacing)
+    if len(values) < 2:
+        return spacing
+
+    spacing[-2] = _valid_spacing_value(values[0])
+    spacing[-1] = _valid_spacing_value(values[1])
+    return spacing
+
+
+def _metadata_voxel_spacing(voxel_spacing, ndim):
+    spacing = [None] * ndim
+    if voxel_spacing is None:
+        return spacing
+
+    for dim, value in enumerate(voxel_spacing):
+        if dim >= ndim:
+            break
+        spacing[dim] = _valid_spacing_value(value)
+    return spacing
+
+
+def _append_dim_label(dim_labels, label):
+    labels = list(dim_labels or [])
+    labels.append(label or '')
+    return labels
+
+
+def _append_voxel_spacing(voxel_spacing, spacing):
+    values = list(voxel_spacing or [])
+    values.append(spacing)
+    return values
+
+
+def _reverse_spatial_metadata(values, ndim):
+    values = list(values or [])
+    values = (values + [None] * ndim)[:ndim]
+    spatial_ndim = min(3, ndim)
+    values[:spatial_ndim] = reversed(values[:spatial_ndim])
+    return values
+
+
 class PhilipsRECLoader:
     def __init__(self, rec_path):
         self.rec_path = Path(rec_path)
@@ -273,14 +342,16 @@ class DicomLoader:
             )
 
         data = remove_trailing_singletons(np.asarray(dcm.pixel_array))
+        pixel_spacing = getattr(dcm, 'PixelSpacing', None)
         self.metadata.update({
             'shape': tuple(data.shape),
             'dtype': str(data.dtype),
+            'voxel_spacing': _dicom_pixel_voxel_spacing(pixel_spacing, data.ndim),
             'dicom_metadata': {
                 'patient_name': str(getattr(dcm, 'PatientName', '')),
                 'series_description': str(getattr(dcm, 'SeriesDescription', '')),
                 'modality': str(getattr(dcm, 'Modality', '')),
-                'pixel_spacing': list(getattr(dcm, 'PixelSpacing', [])) if hasattr(dcm, 'PixelSpacing') else None,
+                'pixel_spacing': list(pixel_spacing) if pixel_spacing is not None else None,
                 'image_position_patient': list(getattr(dcm, 'ImagePositionPatient', [])) if hasattr(dcm, 'ImagePositionPatient') else None,
             },
         })
@@ -399,6 +470,8 @@ class DicomDirectoryLoader:
             nifti_paths = []
             json_paths = []
             sidecar_metadata = []
+            nifti_dim_labels = []
+            nifti_voxel_spacings = []
 
             for nifti_path, json_path in nifti_outputs:
                 nifti_loader = NiftiLoader(nifti_path)
@@ -406,9 +479,18 @@ class DicomDirectoryLoader:
                 nifti_paths.append(str(nifti_path))
                 json_paths.append(str(json_path) if json_path else None)
                 sidecar_metadata.append(_read_json_sidecar(json_path))
+                nifti_dim_labels.append(nifti_loader.metadata.get('dim_labels', []))
+                nifti_voxel_spacings.append(nifti_loader.metadata.get('voxel_spacing', []))
 
             if len(arrays) == 1:
                 data = arrays[0]
+                base_dim_labels = list(nifti_dim_labels[0]) if nifti_dim_labels else _nifti_dim_labels(data.ndim)
+                dim_labels = _reverse_spatial_metadata(base_dim_labels, data.ndim)
+                base_voxel_spacing = _metadata_voxel_spacing(
+                    nifti_voxel_spacings[0] if nifti_voxel_spacings else None,
+                    data.ndim,
+                )
+                voxel_spacing = base_voxel_spacing
                 stacking_label = None
                 stacking_key = None
                 stacking_values = None
@@ -430,10 +512,20 @@ class DicomDirectoryLoader:
                     if any(description is not None for description in series_descriptions):
                         print(f"  SeriesDescription: {series_descriptions}")
                 data = np.stack(arrays, axis=-1)
+                base_dim_labels = list(nifti_dim_labels[0]) if nifti_dim_labels else _nifti_dim_labels(arrays[0].ndim)
+                base_dim_labels = _reverse_spatial_metadata(base_dim_labels, arrays[0].ndim)
+                dim_labels = _append_dim_label(base_dim_labels, stacking_label)
+                base_voxel_spacing = _metadata_voxel_spacing(
+                    nifti_voxel_spacings[0] if nifti_voxel_spacings else None,
+                    arrays[0].ndim,
+                )
+                voxel_spacing = _append_voxel_spacing(base_voxel_spacing, None)
 
             self.metadata.update({
                 'shape': tuple(data.shape),
                 'dtype': str(data.dtype),
+                'dim_labels': dim_labels,
+                'voxel_spacing': voxel_spacing,
                 'nifti_output_path': nifti_paths[0] if len(nifti_paths) == 1 else nifti_paths,
                 'sidecar_json_path': json_paths[0] if len(json_paths) == 1 else json_paths,
                 'stacked_dimension': stacking_label,
@@ -463,11 +555,14 @@ class NiftiLoader:
                 "Install it with: pip install nibabel"
             )
         
-        data = nib.load(self.file_path).get_fdata()
+        image = nib.load(self.file_path)
+        data = image.get_fdata()
         data = remove_trailing_singletons(data)
         self.metadata.update({
             'shape': tuple(data.shape),
             'dtype': str(data.dtype),
+            'dim_labels': _nifti_dim_labels(data.ndim),
+            'voxel_spacing': _nifti_voxel_spacing(image.header.get_zooms(), data.ndim),
         })
         return data
 
@@ -601,4 +696,4 @@ def load_file(filepath):
         NumPy array
         
     """
-    return load_path(filepath).data
+    return load_path(filepath).data

{ndslice-0.7.0 → ndslice-0.8.0}/ndslice/imageview2d.py

@@ -34,6 +34,7 @@ class ImageView2D(QtWidgets.QWidget):
         self.levelMin = None
         self.levelMax = None
         self.displayMode = 'square_pixels'  # Default to square pixels
+        self.autoAspectRatio = None
         
         # Create the UI layout
         self.setupUI()
@@ -222,18 +223,26 @@ class ImageView2D(QtWidgets.QWidget):
         """Set the color map for the histogram"""
         self.histogram.gradient.setColorMap(colormap)
         
-    def setDisplayMode(self, mode):
+    def setDisplayMode(self, mode, auto_aspect_ratio=None):
         """Set the display mode.
 
         Modes:
         - 'square_pixels': force square pixel display (aspect ratio 1.0)
         - 'square_fov'   : lock aspect ratio to image width/height (field of view square)
-        - 'fit'          : allow non-uniform scaling so the entire image fits viewport
+        - 'auto'         : lock to provided physical aspect, or fit if unavailable
         """
-        if mode not in ('square_pixels', 'square_fov', 'fit'):
+        if mode == 'fit':
+            mode = 'auto'
+        if mode not in ('square_pixels', 'square_fov', 'auto'):
             raise ValueError(f"Unknown display mode: {mode}")
         self.displayMode = mode
+        self.autoAspectRatio = auto_aspect_ratio
         self._updateAspectRatio()
+
+    def setAutoAspectRatio(self, auto_aspect_ratio):
+        self.autoAspectRatio = auto_aspect_ratio
+        if self.displayMode == 'auto':
+            self._updateAspectRatio()
         
     def _updateAspectRatio(self):
         """Update the aspect ratio based on display mode"""
@@ -248,11 +257,12 @@ class ImageView2D(QtWidgets.QWidget):
             height, width = self.image.shape
             aspect_ratio = width / height
             self.view.setAspectLocked(True, ratio=aspect_ratio)
-        elif self.displayMode == 'fit':
-            # Fit: allow free aspect so the whole image fits inside the view box
-            self.view.setAspectLocked(False)
-            # Ensure view box ranges cover the image exactly
-            self.view.autoRange()
+        elif self.displayMode == 'auto':
+            if self.autoAspectRatio is None:
+                self.view.setAspectLocked(False)
+                self.view.autoRange()
+            else:
+                self.view.setAspectLocked(True, ratio=self.autoAspectRatio)
         
         # Trigger a refresh of the view
         if hasattr(self, 'imageItem') and self.imageItem is not None:
@@ -260,7 +270,7 @@ class ImageView2D(QtWidgets.QWidget):
 
     # --- Qt Events -----------------------------------------------------
     def resizeEvent(self, event):
-        """On resize, if in 'fit' mode keep the image fully visible."""
+        """On resize, if in auto-fit mode keep the image fully visible."""
         super().resizeEvent(event)
-        if self.displayMode == 'fit' and self.image is not None:
-            self.view.autoRange()
+        if self.displayMode == 'auto' and self.autoAspectRatio is None and self.image is not None:
+            self.view.autoRange()