ndslice 0.7.0__tar.gz → 0.9.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ndslice
-Version: 0.7.0
+Version: 0.9.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,10 @@ 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"])
+# Optional mask overlay:
+ndslice(data, mask=mask_data)
 ```
 
 ![Showcase](docs/images/showcase.gif)
@@ -115,6 +121,9 @@ Click arrow icons (⬇️/⬆️ and ⬅️/➡️) next to dimension labels to
 Default orientation is image-style (origin lower-left).
 Flip the primary axis for matrix-style (origin upper-left).
 
+**Mask overlay**
+Pass `mask=` to overlay a label volume on the main image. Mask values must be integer labels from `0` to `32`; label `0` is transparent, opacity is adjustable, and the small color swatch cycles between solid RGBCMY colors and a Glasbey rainbow palette for the labels present in the mask.
+
 **Non-blocking windows**
 
 By default, windows open in separate processes, allowing multiple simultaneous views:
@@ -129,11 +138,18 @@ 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 image.nii.gz --mask mask.nii.gz
 ndslice image.dcm
 ndslice some_dicom_dir/ # Automatically attemps to form an nd-array from DICOM the files
 ndslice --help   # Show all options

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

@@ -25,6 +25,10 @@ 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"])
+# Optional mask overlay:
+ndslice(data, mask=mask_data)
 ```
 
 ![Showcase](docs/images/showcase.gif)
@@ -73,6 +77,9 @@ Click arrow icons (⬇️/⬆️ and ⬅️/➡️) next to dimension labels to
 Default orientation is image-style (origin lower-left).
 Flip the primary axis for matrix-style (origin upper-left).
 
+**Mask overlay**
+Pass `mask=` to overlay a label volume on the main image. Mask values must be integer labels from `0` to `32`; label `0` is transparent, opacity is adjustable, and the small color swatch cycles between solid RGBCMY colors and a Glasbey rainbow palette for the labels present in the mask.
+
 **Non-blocking windows**
 
 By default, windows open in separate processes, allowing multiple simultaneous views:
@@ -87,11 +94,18 @@ 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 image.nii.gz --mask mask.nii.gz
 ndslice image.dcm
 ndslice some_dicom_dir/ # Automatically attemps to form an nd-array from DICOM the files
 ndslice --help   # Show all options
@@ -183,4 +197,4 @@ Henric Rydén
 
 Karolinska University Hospital
 
-Stockholm, Sweden
+Stockholm, Sweden

ndslice-0.9.0/ndslice/__init__.py

@@ -0,0 +1,15 @@
+"""
+ndslice - Interactive N-dimensional array viewer with FFT support
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .ndslice import ndslice, NDSliceWindow, Domain
+from .imageview2d import ImageView2D
+
+try:
+    __version__ = version("ndslice")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
+
+__all__ = ["ndslice", "NDSliceWindow", "ImageView2D", "Domain", "__version__"]

{ndslice-0.7.0 → ndslice-0.9.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
 
 
@@ -31,8 +31,19 @@ For files with multiple datasets (HDF5, NPZ, MAT), a GUI selector will automatic
     )
     parser.add_argument('files', type=str, nargs='+', 
                         help='Path(s) to data files or DICOM directories')
+    parser.add_argument('--mask', type=str, default=None,
+                        help='Optional mask volume to overlay on a single main file')
     
     args = parser.parse_args()
+
+    mask_path = None
+    if args.mask is not None:
+        if len(args.files) != 1:
+            parser.error('--mask requires exactly one main file')
+
+        mask_path = Path(args.mask)
+        if not mask_path.exists():
+            parser.error(f'Mask file not found: {mask_path}')
     
     for file_arg in args.files:
         filepath = Path(file_arg)
@@ -50,16 +61,29 @@ 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)
+                mask_data = load_path(mask_path).data if mask_path is not None else None
+                ndslice(data=loaded.data, title=title, block=False, filepath=filepath,
+                        dim_labels=loaded.metadata.get('dim_labels'),
+                        voxel_spacing=loaded.metadata.get('voxel_spacing'),
+                        mask=mask_data)
                 continue
             
             # Multi-dataset formats - use selectors
             selector = None
             if suffix in ['.h5', '.hdf5']:
-                selector = H5DatasetSelector(filepath)
+                if mask_path is not None:
+                    print("--mask is not supported for multi-dataset main files yet")
+                    continue
+                selector = h5_selector_for_path(filepath)
             elif suffix == '.npz':
+                if mask_path is not None:
+                    print("--mask is not supported for multi-dataset main files yet")
+                    continue
                 selector = NpzDatasetSelector(filepath)
             elif suffix == '.mat':
+                if mask_path is not None:
+                    print("--mask is not supported for multi-dataset main files yet")
+                    continue
                 selector = MatDatasetSelector(filepath)
             else:
                 print(f"Unsupported file type: {suffix}. Supported types: directories with DICOM .dcm files, .h5, .hdf5, .npy, .npz, .mat, .REC, .cfl, .dcm, .nii, .nii.gz, .txt")
@@ -77,4 +101,4 @@ For files with multiple datasets (HDF5, NPZ, MAT), a GUI selector will automatic
 
 
 if __name__ == '__main__':
-    main()
+    main()

ndslice-0.9.0/ndslice/config.py

@@ -0,0 +1,205 @@
+"""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",
+}
+DEFAULT_MASK_OPACITY = 0.8
+
+
+@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
+    default_mask_opacity: float = DEFAULT_MASK_OPACITY
+
+
+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
+
+    default_mask_opacity = _clean_mask_opacity(
+        display.get("default_mask_opacity", DEFAULT_MASK_OPACITY)
+    )
+
+    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,
+        default_mask_opacity=default_mask_opacity,
+    )
+
+
+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
+
+    default_mask_opacity = _clean_mask_opacity(config.default_mask_opacity)
+
+    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'
+        f"default_mask_opacity = {default_mask_opacity:.6g}\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
+
+
+def _clean_mask_opacity(value):
+    try:
+        opacity = float(value)
+    except (TypeError, ValueError):
+        return DEFAULT_MASK_OPACITY
+    if not 0.0 <= opacity <= 1.0:
+        return DEFAULT_MASK_OPACITY
+    return opacity

{ndslice-0.7.0 → ndslice-0.9.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