tk-rt-viewer 2.1.2__tar.gz → 2.2.1__tar.gz

{tk_rt_viewer-2.1.2 → tk_rt_viewer-2.2.1}/CHANGELOG.md

@@ -4,6 +4,42 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [2.2.0]
+
+Loading a series picked from a scan now reads only that series' files.
+
+### Added
+
+- **`load_scanned_series(entry, reg_files=())`** loads one series found by
+  `scan_dicom_series` from the files the scan recorded. `load_dcm_series`
+  walked the directory with pydicom and then twice more through GDCM before
+  reading, and refused any directory holding a second image series.
+- **`load_phase_series(phases, reg_files=(), max_workers=None)`** loads the
+  phases of a 4DCT entry, several at a time. `load_all_series` +
+  `select_phase_series` read every image series under the root just to keep
+  the phases.
+  Both apply registrations from the REG files passed in (normally
+  `SeriesScan.reg_files`), matched by any slice's SOP Instance UID or by the
+  series, as `load_all_series` does.
+- **`SeriesEntry.file_paths`** and **`PhaseEntry.file_paths`**: a series'
+  files in slice order (ImagePositionPatient along the slice normal, as GDCM
+  sorts). **`PhaseEntry.series_uid`** records the phase's SeriesInstanceUID.
+  All new fields have defaults, so existing constructor calls still work.
+- **`scan_dicom_series(..., require_single_series_per_dir=False)`**: when
+  set, raises the new **`MixedSeriesDirectoryError`** (a `ValueError`) if a
+  directory holding a listed series also holds another image series.
+  Non-image objects and the phases of one 4DCT may share a directory. Off by
+  default; `MultiplePatientError` is still checked first.
+- **`NON_IMAGE_MODALITIES`** (formerly the private `_NON_IMAGE_MODALITIES`):
+  the modalities never treated as an image series, so a host that sorts
+  files into per-series folders agrees with the scan on what an image
+  series is.
+
+### Changed
+
+- `_build_series_info` takes the matched REG matrix instead of the tree scan
+  (internal).
+
 ## [2.1.2]
 
 A review pass: behaviour fixes with no API break, a shared implementation for

{tk_rt_viewer-2.1.2 → tk_rt_viewer-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tk-rt-viewer
-Version: 2.1.2
+Version: 2.2.1
 Summary: SimpleITK-based DICOM-RT MPR viewer widget for Tkinter (CT, RT-DOSE, RT-STRUCT, DVH)
 Project-URL: Homepage, https://github.com/oki1002/DICOM_RT_Viewer
 Project-URL: Repository, https://github.com/oki1002/DICOM_RT_Viewer
@@ -215,9 +215,29 @@ for entry in scan.series:
 ```
 
 `scan_dicom_series` raises `MultiplePatientError` when the tree holds more
-than one patient; pass `require_single_patient=False` to scan anyway. To load
-the phases of a 4DCT entry afterwards, narrow a `load_all_series` result with
-`select_phase_series(all_series, entry.phases)`.
+than one patient; pass `require_single_patient=False` to scan anyway.
+
+Each entry records its own files in slice order, so the series the user picks
+is loaded without scanning its directory again, even when other series share
+that directory. A 4DCT entry is loaded phase by phase, several at a time:
+
+```python
+from tk_rt_viewer.io import load_phase_series, load_scanned_series
+
+info = load_scanned_series(entry, scan.reg_files)            # one series
+phases = load_phase_series(four_d.phases, scan.reg_files)    # {"0%": ..., ...}
+```
+
+Passing `scan.reg_files` attaches the transform of any registration naming
+the series (see [Registration](#registration-fusion)). Load RT-DOSE entries with
+`load_rt_dose(entry.file_path)`.
+
+Code that addresses a series by its directory, such as RT-STRUCT import and
+export (`rtstruct_io`, through rt-utils), needs one image series per
+directory. Pass `require_single_series_per_dir=True` to have the scan raise
+`MixedSeriesDirectoryError` (listing the directories) instead of letting
+those slices mix. Non-image objects (RT-STRUCT, RT-PLAN, RT-DOSE, REG) may
+share a directory with their series, and so may the phases of one 4DCT.
 
 Load the primary image first. The secondary overlay, the 4DCT phases and
 RT-DOSE are all displayed on the primary image's grid, so there is nothing
@@ -701,7 +721,8 @@ field and belongs to a different IOD, so `transform_to_matrix` raises
 A registration written this way is read back by
 `tk_rt_viewer.io.find_reg_matrices` (and therefore applied automatically by
 `load_all_series` / `load_dcm_series`) when the file sits anywhere under the
-scanned directory. Any referenced slice is enough: references are resolved
+scanned directory; `load_scanned_series` / `load_phase_series` apply it when
+the file is among the `reg_files` passed in. Any referenced slice is enough: references are resolved
 to their whole series. The reader also accepts the item-level
 `ReferencedSeriesSequence` written by 2.1.x, and skips the identity item that
 names the fixed image's own frame of reference, so the fixed series is not

{tk_rt_viewer-2.1.2 → tk_rt_viewer-2.2.1}/README.md

@@ -178,9 +178,29 @@ for entry in scan.series:
 ```
 
 `scan_dicom_series` raises `MultiplePatientError` when the tree holds more
-than one patient; pass `require_single_patient=False` to scan anyway. To load
-the phases of a 4DCT entry afterwards, narrow a `load_all_series` result with
-`select_phase_series(all_series, entry.phases)`.
+than one patient; pass `require_single_patient=False` to scan anyway.
+
+Each entry records its own files in slice order, so the series the user picks
+is loaded without scanning its directory again, even when other series share
+that directory. A 4DCT entry is loaded phase by phase, several at a time:
+
+```python
+from tk_rt_viewer.io import load_phase_series, load_scanned_series
+
+info = load_scanned_series(entry, scan.reg_files)            # one series
+phases = load_phase_series(four_d.phases, scan.reg_files)    # {"0%": ..., ...}
+```
+
+Passing `scan.reg_files` attaches the transform of any registration naming
+the series (see [Registration](#registration-fusion)). Load RT-DOSE entries with
+`load_rt_dose(entry.file_path)`.
+
+Code that addresses a series by its directory, such as RT-STRUCT import and
+export (`rtstruct_io`, through rt-utils), needs one image series per
+directory. Pass `require_single_series_per_dir=True` to have the scan raise
+`MixedSeriesDirectoryError` (listing the directories) instead of letting
+those slices mix. Non-image objects (RT-STRUCT, RT-PLAN, RT-DOSE, REG) may
+share a directory with their series, and so may the phases of one 4DCT.
 
 Load the primary image first. The secondary overlay, the 4DCT phases and
 RT-DOSE are all displayed on the primary image's grid, so there is nothing
@@ -664,7 +684,8 @@ field and belongs to a different IOD, so `transform_to_matrix` raises
 A registration written this way is read back by
 `tk_rt_viewer.io.find_reg_matrices` (and therefore applied automatically by
 `load_all_series` / `load_dcm_series`) when the file sits anywhere under the
-scanned directory. Any referenced slice is enough: references are resolved
+scanned directory; `load_scanned_series` / `load_phase_series` apply it when
+the file is among the `reg_files` passed in. Any referenced slice is enough: references are resolved
 to their whole series. The reader also accepts the item-level
 `ReferencedSeriesSequence` written by 2.1.x, and skips the identity item that
 names the fixed image's own frame of reference, so the fixed series is not

{tk_rt_viewer-2.1.2 → tk_rt_viewer-2.2.1}/src/tk_rt_viewer/__init__.py

@@ -38,8 +38,9 @@ Submodule API (import from the submodule)
 -----------------------------------------
 ``tk_rt_viewer.io``
     validate_dicom_files, find_reg_matrices, scan_dicom_series,
-    select_phase_series, load_all_series, load_dcm_series,
-    normalize_phase_label
+    load_scanned_series, load_phase_series, select_phase_series,
+    load_all_series, load_dcm_series, normalize_phase_label,
+    MultiplePatientError, MixedSeriesDirectoryError, NON_IMAGE_MODALITIES
 
 ``tk_rt_viewer.rtstruct_io``
     load_rt_struct, mask2rtstruct, save_structure_set,
@@ -103,7 +104,7 @@ __all__ = [
     "StructureSet",
     "to_gy_pairs",
 ]
-__version__ = "2.1.2"
+__version__ = "2.2.1"
 
 
 def __getattr__(name: str) -> Any:

{tk_rt_viewer-2.1.2 → tk_rt_viewer-2.2.1}/src/tk_rt_viewer/io.py

@@ -13,6 +13,16 @@ scan_dicom_series(dcm_root_dir) -> SeriesScan
     Enumerate the image series in a directory tree without reading pixel
     data, for a series picker.
 
+load_scanned_series(entry, reg_files=()) -> SeriesInfo
+    Load one series found by scan_dicom_series, reading only its own files.
+
+load_phase_series(phases, reg_files=(), max_workers=None)
+    -> dict[str, SeriesInfo]
+    Load the phases of a scanned 4DCT, reading only their own files.
+
+NON_IMAGE_MODALITIES
+    Modalities never treated as an image series (RT objects, REG, SR, ...).
+
 select_phase_series(all_series, phases) -> dict[str, SeriesInfo]
     Pick the 4DCT phases named by a scan result out of a load_all_series map.
 
@@ -42,8 +52,9 @@ import logging
 import math
 import pathlib
 import re
-from collections.abc import Iterator, Sequence
-from dataclasses import dataclass, field
+from collections.abc import Iterable, Iterator, Sequence
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field, replace
 from typing import TypedDict
 
 import numpy as np
@@ -62,8 +73,9 @@ _PHASE_LABEL_PATTERN = re.compile(r"\d+%")
 #: Modalities never loaded as a displayable image series. Without this,
 #: GDCM enumerates RT objects alongside the images and they are read through
 #: the CT path (RT-DOSE without its DoseGridScaling). RT-DOSE has its own
-#: loader, :func:`load_rt_dose`.
-_NON_IMAGE_MODALITIES: frozenset[str] = frozenset(
+#: loader, :func:`load_rt_dose`. Public so hosts that reorganise files agree
+#: with :func:`scan_dicom_series` on what counts as an image series.
+NON_IMAGE_MODALITIES: frozenset[str] = frozenset(
     {"RTSTRUCT", "RTPLAN", "RTRECORD", "RTDOSE", "REG", "SR", "PR", "KO", "SEG"}
 )
 
@@ -81,10 +93,19 @@ _NON_CT_WINDOW_PERCENTILES: tuple[float, float] = (0.5, 99.5)
 #: Width used for an image with a flat intensity range (no meaningful window).
 _FLAT_IMAGE_WINDOW_WIDTH: float = 1.0
 
+#: Upper bound on the worker threads :func:`load_phase_series` uses by default.
+#: Phases are read concurrently because reading is I/O bound and SimpleITK
+#: releases the GIL; more workers than this mostly contend for the disk.
+_DEFAULT_PHASE_LOAD_WORKERS: int = 4
+
 #: Modalities :func:`scan_dicom_series` lists by default.
 DEFAULT_SCAN_MODALITIES: frozenset[str] = frozenset({"CT", "MR", "PT", "RTDOSE"})
 
 
+#: ``(by_sop_instance_uid, by_series_instance_uid)`` registration matrices.
+type _RegMatrices = tuple[dict[str, np.ndarray], dict[str, np.ndarray]]
+
+
 class SeriesInfo(TypedDict):
     """Dict shape returned by :func:`load_all_series` and :func:`load_dcm_series`."""
 
@@ -327,6 +348,24 @@ class MultiplePatientError(ValueError):
     """
 
 
+class MixedSeriesDirectoryError(ValueError):
+    """A directory being scanned holds more than one image series.
+
+    Raised by :func:`scan_dicom_series` when *require_single_series_per_dir*
+    is set. Code that addresses a series by its directory (RT-STRUCT export
+    and import through rt-utils, for one) would silently mix the slices of
+    every image series in that directory.
+
+    Attributes:
+        directories: The offending directories, sorted.
+    """
+
+    def __init__(self, directories: Sequence[pathlib.Path]) -> None:
+        self.directories: tuple[pathlib.Path, ...] = tuple(sorted(directories))
+        listing = ", ".join(f"'{d}'" for d in self.directories)
+        super().__init__(f"Found more than one image series in: {listing}.")
+
+
 @dataclass(frozen=True)
 class PhaseEntry:
     """One respiratory phase of a 4DCT series.
@@ -335,11 +374,16 @@ class PhaseEntry:
         label:       Normalised phase label, e.g. ``"10%"``.
         description: The phase's own SeriesDescription.
         series_dir:  Directory holding the phase's files.
+        series_uid:  The phase's SeriesInstanceUID.
+        file_paths:  The phase's files in slice order (see
+            :attr:`SeriesEntry.file_paths`).
     """
 
     label: str
     description: str
     series_dir: pathlib.Path
+    series_uid: str = ""
+    file_paths: tuple[pathlib.Path, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -355,6 +399,9 @@ class SeriesEntry:
             directly, since a directory may hold several dose objects.
         phases:      The phases of a 4DCT series, lowest percentage first;
             empty for an ordinary series.
+        file_paths:  Every file of the series, in slice order, so
+            :func:`load_scanned_series` reads them without scanning the
+            directory again. Empty for a grouped 4DCT entry (see *phases*).
     """
 
     modality: str
@@ -363,6 +410,7 @@ class SeriesEntry:
     series_uid: str
     file_path: pathlib.Path
     phases: tuple[PhaseEntry, ...] = ()
+    file_paths: tuple[pathlib.Path, ...] = ()
 
     @property
     def is_4dct(self) -> bool:
@@ -392,13 +440,16 @@ def scan_dicom_series(
     modalities: frozenset[str] = DEFAULT_SCAN_MODALITIES,
     group_4dct: bool = True,
     require_single_patient: bool = True,
+    require_single_series_per_dir: bool = False,
 ) -> SeriesScan:
     """List the series under *dcm_root_dir* without reading any pixel data.
 
     Headers only, so a large folder is enumerated quickly and the host loads
-    just what the user selects (:func:`load_dcm_series`,
-    :func:`load_rt_dose`). Series come back images first, then RT-DOSE, each
-    group ordered by modality and description.
+    just what the user selects (:func:`load_scanned_series`,
+    :func:`load_phase_series`, :func:`load_rt_dose`). Each entry records its
+    files in slice order, so loading it never scans the directory again.
+    Series come back images first, then RT-DOSE, each group ordered by
+    modality and description.
 
     Args:
         dcm_root_dir: Root directory to scan, recursively.
@@ -408,13 +459,23 @@ def scan_dicom_series(
             (``"0%"``, ``"10%"``, ...) into one entry holding them as phases.
         require_single_patient: Raise when the tree holds more than one
             patient.
+        require_single_series_per_dir: Raise when a directory holding a
+            listed series also holds another image series. Non-image objects
+            (RT-STRUCT, RT-PLAN, RT-DOSE, REG, ...) may share the directory,
+            and so may the phases of one grouped 4DCT. Set this when the
+            host addresses a series by its directory, e.g. for RT-STRUCT
+            import and export.
 
     Raises:
         MultiplePatientError: If *require_single_patient* and more than one
-            PatientID or PatientName was found.
+            PatientID or PatientName was found. Checked first.
+        MixedSeriesDirectoryError: If *require_single_series_per_dir* and a
+            directory mixes image series.
     """
     root = pathlib.Path(dcm_root_dir)
     series_by_uid: dict[str, SeriesEntry] = {}
+    files_by_uid: dict[str, list[tuple[tuple[float, float], pathlib.Path]]] = {}
+    image_series_by_dir: dict[pathlib.Path, set[str]] = {}
     reg_files: list[pathlib.Path] = []
     patient_ids: set[str] = set()
     patient_names: set[str] = set()
@@ -431,19 +492,24 @@ def scan_dicom_series(
         if modality == "REG":
             reg_files.append(file)
             continue
-        if modality not in modalities:
-            continue
 
         series_uid = str(ds.get("SeriesInstanceUID", ""))
-        if not series_uid or series_uid in series_by_uid:
+        if not series_uid:
+            continue
+        if modality not in NON_IMAGE_MODALITIES:
+            image_series_by_dir.setdefault(file.parent, set()).add(series_uid)
+        if modality not in modalities:
             continue
-        series_by_uid[series_uid] = SeriesEntry(
-            modality=modality,
-            description=str(ds.get("SeriesDescription", "")).strip(),
-            series_dir=file.parent,
-            series_uid=series_uid,
-            file_path=file,
-        )
+
+        files_by_uid.setdefault(series_uid, []).append((_slice_sort_key(ds), file))
+        if series_uid not in series_by_uid:
+            series_by_uid[series_uid] = SeriesEntry(
+                modality=modality,
+                description=str(ds.get("SeriesDescription", "")).strip(),
+                series_dir=file.parent,
+                series_uid=series_uid,
+                file_path=file,
+            )
 
     if require_single_patient and (len(patient_ids) > 1 or len(patient_names) > 1):
         raise MultiplePatientError(
@@ -451,7 +517,19 @@ def scan_dicom_series(
             f"names={sorted(patient_names)}."
         )
 
-    series = _order_series(list(series_by_uid.values()), group_4dct)
+    entries = [
+        replace(entry, file_paths=_sorted_files(files_by_uid[uid]))
+        for uid, entry in series_by_uid.items()
+    ]
+    series = _order_series(entries, group_4dct)
+
+    if require_single_series_per_dir:
+        mixed_dirs = _find_mixed_series_dirs(
+            image_series_by_dir, frozenset(series_by_uid), series
+        )
+        if mixed_dirs:
+            raise MixedSeriesDirectoryError(mixed_dirs)
+
     logger.info(
         f"Scanned '{root}': {len(series)} series "
         f"({sum(len(entry.phases) for entry in series)} 4DCT phases, "
@@ -465,6 +543,58 @@ def scan_dicom_series(
     )
 
 
+def _slice_sort_key(ds: pydicom.Dataset) -> tuple[float, float]:
+    """Return ``(position along the slice normal, InstanceNumber)`` for a slice.
+
+    The position is the ImagePositionPatient projected onto the normal of
+    ImageOrientationPatient, the order GDCM itself sorts a series into. A
+    slice without usable geometry falls back to its InstanceNumber.
+    """
+    try:
+        instance = float(ds.get("InstanceNumber"))
+    except (TypeError, ValueError):
+        instance = math.inf
+
+    position = ds.get("ImagePositionPatient")
+    orientation = ds.get("ImageOrientationPatient")
+    if position is None or orientation is None:
+        return instance, instance
+    try:
+        cosines = np.asarray(orientation, dtype=float)
+        normal = np.cross(cosines[:3], cosines[3:6])
+        distance = float(np.dot(normal, np.asarray(position, dtype=float)))
+    except (TypeError, ValueError):
+        return instance, instance
+    return distance, instance
+
+
+def _sorted_files(
+    keyed_files: Iterable[tuple[tuple[float, float], pathlib.Path]],
+) -> tuple[pathlib.Path, ...]:
+    """Order a series' files by their slice keys, the path breaking ties."""
+    return tuple(
+        file for _, file in sorted(keyed_files, key=lambda kf: (kf[0], str(kf[1])))
+    )
+
+
+def _find_mixed_series_dirs(
+    image_series_by_dir: dict[pathlib.Path, set[str]],
+    listed_uids: frozenset[str],
+    series: Sequence[SeriesEntry],
+) -> list[pathlib.Path]:
+    """Return the directories where a listed series shares with another image series.
+
+    The phases of a grouped 4DCT count as one acquisition, so a directory
+    holding only those phases is not mixed.
+    """
+    phase_uids = {phase.series_uid for entry in series for phase in entry.phases}
+    return [
+        directory
+        for directory, uids in image_series_by_dir.items()
+        if len(uids) > 1 and uids & listed_uids and not uids <= phase_uids
+    ]
+
+
 def _order_series(entries: list[SeriesEntry], group_4dct: bool) -> list[SeriesEntry]:
     """Group 4DCT phases and sort the result into display order."""
     phases: list[SeriesEntry] = []
@@ -495,6 +625,8 @@ def _order_series(entries: list[SeriesEntry], group_4dct: bool) -> list[SeriesEn
                 label=str(normalize_phase_label(entry.description)),
                 description=entry.description,
                 series_dir=entry.series_dir,
+                series_uid=entry.series_uid,
+                file_paths=entry.file_paths,
             )
             for entry in phases
         ),
@@ -714,8 +846,7 @@ def _find_reg_matrix(
 def _build_series_info(
     reader: sitk.ImageSeriesReader,
     raw_image: sitk.Image,
-    file_names: tuple[str, ...],
-    scan: _ScanResult,
+    reg_matrix: np.ndarray | None,
     series_id: str,
 ) -> tuple[str, SeriesInfo]:
     """Build the ``(description, SeriesInfo)`` pair for one loaded series."""
@@ -723,7 +854,6 @@ def _build_series_info(
     modality = _get_modality(reader)
     window_level = _get_window_level(reader, image_lps, modality)
 
-    reg_matrix = _find_reg_matrix(scan, file_names, series_id)
     if reg_matrix is not None:
         logger.info(f"Applying REG matrix to series '{series_id}'.")
         transform: sitk.AffineTransform | None = _build_transform(reg_matrix)
@@ -741,6 +871,49 @@ def _build_series_info(
     )
 
 
+def _read_reg_files(
+    reg_files: Iterable[pathlib.Path],
+) -> _RegMatrices:
+    """Return ``(by_sop_instance_uid, by_series_instance_uid)`` from REG files.
+
+    Reads only the files given (typically :attr:`SeriesScan.reg_files`), so
+    no directory tree is walked. Unreadable files are logged and skipped.
+    """
+    by_sop: dict[str, np.ndarray] = {}
+    by_series: dict[str, np.ndarray] = {}
+    for file in reg_files:
+        try:
+            ds = pydicom.dcmread(str(file))
+        except Exception as exc:
+            logger.warning(f"Skipping unreadable REG file '{file}': {exc}")
+            continue
+        if ds.get("SOPClassUID", "") == _SPATIAL_REGISTRATION_UID:
+            _collect_reg_matrices(ds, pathlib.Path(file), by_sop, by_series)
+    return by_sop, by_series
+
+
+def _match_reg_matrix(
+    reader: sitk.ImageSeriesReader,
+    file_count: int,
+    series_uid: str,
+    reg_matrices: _RegMatrices,
+) -> np.ndarray | None:
+    """Return the REG matrix for a series read by *reader*, if any.
+
+    Matched by the SOP Instance UID of any slice (a REG object may name only
+    one), in slice order, then by *series_uid*.
+    """
+    by_sop, by_series = reg_matrices
+    if by_sop:
+        for index in range(file_count):
+            if not reader.HasMetaDataKey(index, "0008|0018"):
+                continue
+            sop_uid = reader.GetMetaData(index, "0008|0018").strip().rstrip("\0")
+            if sop_uid in by_sop:
+                return by_sop[sop_uid]
+    return by_series.get(series_uid)
+
+
 # ---------------------------------------------------------------------------
 # Public API
 # ---------------------------------------------------------------------------
@@ -768,12 +941,12 @@ def _load_all_series_impl(
     for dcm_dir in sorted(scan.dirs_with_dicom):
         for sid in reader.GetGDCMSeriesIDs(str(dcm_dir)):
             modality = scan.modality_by_series.get(sid, "")
-            if modality.upper() in _NON_IMAGE_MODALITIES:
+            if modality.upper() in NON_IMAGE_MODALITIES:
                 logger.info(f"Skipping {modality} series '{sid}' (not an image).")
                 continue
             raw_image, file_names = _read_series(reader, dcm_dir, sid)
             description, info = _build_series_info(
-                reader, raw_image, file_names, scan, sid
+                reader, raw_image, _find_reg_matrix(scan, file_names, sid), sid
             )
             loaded_count += 1
             if description in series_dict:
@@ -872,3 +1045,102 @@ def load_dcm_series(dcm_dir: str | pathlib.Path) -> SeriesInfo:
             f"but found {loaded_count}."
         )
     return next(iter(series_dict.values()))
+
+
+def load_scanned_series(
+    entry: SeriesEntry | PhaseEntry,
+    reg_files: Sequence[pathlib.Path] = (),
+) -> SeriesInfo:
+    """Load one series found by :func:`scan_dicom_series`.
+
+    Reads exactly the entry's own files, in the slice order the scan
+    recorded, so it neither walks the directory again nor trips over other
+    series stored in the same directory. An entry built without
+    ``file_paths`` falls back to asking GDCM for the files of its
+    ``series_uid`` in ``series_dir``.
+
+    Args:
+        entry: An image series or a single 4DCT phase from a scan.
+        reg_files: REG files to look the series up in, typically
+            :attr:`SeriesScan.reg_files`. The matching transform is attached
+            as ``SeriesInfo["transform"]``; with none given it is ``None``.
+
+    Raises:
+        ValueError: If *entry* is a grouped 4DCT (use
+            :func:`load_phase_series`) or an RT-DOSE (use
+            :func:`load_rt_dose`).
+        FileNotFoundError: If the entry has no files to read.
+    """
+    return _load_scanned_series(entry, _read_reg_files(reg_files))
+
+
+def load_phase_series(
+    phases: Sequence[PhaseEntry],
+    reg_files: Sequence[pathlib.Path] = (),
+    max_workers: int | None = None,
+) -> dict[str, SeriesInfo]:
+    """Load the phases of a scanned 4DCT, keyed by phase label in *phases* order.
+
+    Only the phases' own files are read, several phases at a time.
+
+    Args:
+        phases: :attr:`SeriesEntry.phases` of a grouped 4DCT entry.
+        reg_files: REG files to look each phase up in (see
+            :func:`load_scanned_series`).
+        max_workers: Phases read concurrently. Defaults to
+            ``min(len(phases), 4)``.
+
+    Raises:
+        FileNotFoundError: If a phase has no files to read. The first
+            failure of any phase is propagated.
+    """
+    if not phases:
+        return {}
+    reg_matrices = _read_reg_files(reg_files)
+    workers = max_workers or min(len(phases), _DEFAULT_PHASE_LOAD_WORKERS)
+    with ThreadPoolExecutor(max_workers=workers) as executor:
+        infos = list(
+            executor.map(
+                lambda phase: _load_scanned_series(phase, reg_matrices), phases
+            )
+        )
+    return {phase.label: info for phase, info in zip(phases, infos, strict=True)}
+
+
+def _load_scanned_series(
+    entry: SeriesEntry | PhaseEntry,
+    reg_matrices: _RegMatrices,
+) -> SeriesInfo:
+    """Load one scanned series with REG matrices already read.
+
+    Shared by :func:`load_scanned_series` and :func:`load_phase_series`.
+    """
+    if isinstance(entry, SeriesEntry):
+        if entry.is_4dct:
+            raise ValueError("A grouped 4DCT entry must be loaded by its phases.")
+        if entry.modality == "RTDOSE":
+            raise ValueError("RT-DOSE must be loaded with load_rt_dose.")
+
+    reader = sitk.ImageSeriesReader()
+    file_names = [str(file) for file in entry.file_paths]
+    if not file_names and entry.series_uid:
+        file_names = list(
+            reader.GetGDCMSeriesFileNames(str(entry.series_dir), entry.series_uid)
+        )
+    if not file_names:
+        raise FileNotFoundError(
+            f"No files recorded for series '{entry.series_uid}' in "
+            f"'{entry.series_dir}'."
+        )
+
+    reader.SetFileNames(file_names)
+    reader.MetaDataDictionaryArrayUpdateOn()
+    raw_image = reader.Execute()
+    series_id = entry.series_uid or str(entry.series_dir)
+    logger.info(f"Series '{series_id}' loaded with {len(file_names)} files.")
+
+    reg_matrix = _match_reg_matrix(
+        reader, len(file_names), entry.series_uid, reg_matrices
+    )
+    _, info = _build_series_info(reader, raw_image, reg_matrix, series_id)
+    return info

{tk_rt_viewer-2.1.2 → tk_rt_viewer-2.2.1}/tests/test_io.py

@@ -8,11 +8,14 @@ from pydicom.dataset import Dataset, FileDataset, FileMetaDataset
 from pydicom.uid import CTImageStorage, ExplicitVRLittleEndian, generate_uid
 
 from tk_rt_viewer.io import (
+    MixedSeriesDirectoryError,
     MultiplePatientError,
     PhaseEntry,
     _collect_reg_matrices,
     _first_float,
     load_dcm_series,
+    load_phase_series,
+    load_scanned_series,
     normalize_phase_label,
     scan_dicom_series,
     select_phase_series,
@@ -349,3 +352,251 @@ class TestNonCtWindowFallback:
         width, level = _get_window_level(sitk.ImageSeriesReader(), image, "MR")
         assert width > 0
         assert level == pytest.approx(7.0)
+
+
+def _write_ct_slices(
+    directory: pathlib.Path,
+    series_description: str,
+    n_slices: int = 3,
+    prefix: str = "",
+    patient: str = "Test",
+    positions: list[float] | None = None,
+    value: int = 0,
+) -> tuple[str, list[pathlib.Path]]:
+    """Write a CT series whose file names do not follow the slice order.
+
+    Files are named in *reverse* slice order, and several series can share
+    *directory* through distinct *prefix* values. Every voxel of slice ``i``
+    holds ``value + i`` so the slice order of a loaded volume can be read
+    back. Returns ``(series_uid, files in slice order)``.
+    """
+    directory.mkdir(parents=True, exist_ok=True)
+    series_uid, study, for_ref = generate_uid(), generate_uid(), generate_uid()
+    z_values = (
+        positions if positions is not None else [float(i) for i in range(n_slices)]
+    )
+    files: list[pathlib.Path] = []
+    for i, z in enumerate(z_values):
+        file_meta = FileMetaDataset()
+        file_meta.MediaStorageSOPClassUID = CTImageStorage
+        sop_uid = generate_uid()
+        file_meta.MediaStorageSOPInstanceUID = sop_uid
+        file_meta.TransferSyntaxUID = ExplicitVRLittleEndian
+
+        path = directory / f"{prefix}{len(z_values) - i:03d}.dcm"
+        ds = FileDataset(str(path), {}, file_meta=file_meta, preamble=b"\0" * 128)
+        ds.SOPClassUID = CTImageStorage
+        ds.SOPInstanceUID = sop_uid
+        ds.StudyInstanceUID = study
+        ds.SeriesInstanceUID = series_uid
+        ds.FrameOfReferenceUID = for_ref
+        ds.PatientName = patient
+        ds.PatientID = patient
+        ds.Modality = "CT"
+        ds.SeriesDescription = series_description
+        ds.Rows = 4
+        ds.Columns = 4
+        ds.BitsAllocated = 16
+        ds.BitsStored = 16
+        ds.HighBit = 15
+        ds.PixelRepresentation = 1
+        ds.SamplesPerPixel = 1
+        ds.PhotometricInterpretation = "MONOCHROME2"
+        ds.PixelSpacing = [1.0, 1.0]
+        ds.SliceThickness = 1.0
+        ds.ImagePositionPatient = [0.0, 0.0, z]
+        ds.ImageOrientationPatient = [1, 0, 0, 0, 1, 0]
+        ds.InstanceNumber = i + 1
+        ds.RescaleIntercept = 0
+        ds.RescaleSlope = 1
+        ds.PixelData = np.full((4, 4), value + i, dtype=np.int16).tobytes()
+        ds.save_as(str(path), enforce_file_format=True)
+        files.append(path)
+    return series_uid, files
+
+
+def _write_rtdose(path: pathlib.Path, patient: str = "Test") -> None:
+    """Write a header-only RT-DOSE object (enough for the scan)."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    meta = FileMetaDataset()
+    meta.MediaStorageSOPClassUID = "1.2.840.10008.5.1.4.1.1.481.2"
+    meta.MediaStorageSOPInstanceUID = generate_uid()
+    meta.TransferSyntaxUID = ExplicitVRLittleEndian
+    ds = FileDataset(str(path), {}, file_meta=meta, preamble=b"\0" * 128)
+    ds.SOPClassUID = meta.MediaStorageSOPClassUID
+    ds.SOPInstanceUID = meta.MediaStorageSOPInstanceUID
+    ds.SeriesInstanceUID = generate_uid()
+    ds.Modality = "RTDOSE"
+    ds.PatientID = patient
+    ds.PatientName = patient
+    ds.save_as(str(path), enforce_file_format=True)
+
+
+def _slice_values(image) -> list[int]:
+    import SimpleITK as sitk
+
+    array = sitk.GetArrayFromImage(image)
+    return [int(array[k, 0, 0]) for k in range(array.shape[0])]
+
+
+class TestScanRecordsSeriesFiles:
+    def test_files_are_recorded_in_slice_order(self, tmp_path) -> None:
+        # Positions deliberately out of step with both names and numbers
+        _, files = _write_ct_slices(tmp_path, "CT", positions=[2.0, 0.0, 1.0])
+        (entry,) = scan_dicom_series(tmp_path).series
+        assert entry.file_paths == (files[1], files[2], files[0])
+
+    def test_order_matches_gdcm(self, tmp_path) -> None:
+        import SimpleITK as sitk
+
+        uid, _ = _write_ct_slices(tmp_path, "CT", positions=[5.0, -1.0, 3.0, 0.5])
+        (entry,) = scan_dicom_series(tmp_path).series
+        gdcm = sitk.ImageSeriesReader.GetGDCMSeriesFileNames(str(tmp_path), uid)
+        assert [str(p) for p in entry.file_paths] == list(gdcm)
+
+    def test_phases_carry_their_uid_and_files(self, tmp_path) -> None:
+        uid, files = _write_ct_slices(tmp_path / "p0", "4D 0%")
+        _write_ct_slices(tmp_path / "p50", "4D 50%")
+        (entry,) = scan_dicom_series(tmp_path).series
+        phase = entry.phases[0]
+        assert phase.series_uid == uid
+        assert phase.file_paths == tuple(files)
+        # The grouped entry itself holds no files of its own
+        assert entry.file_paths == ()
+
+
+class TestRequireSingleSeriesPerDir:
+    def test_two_image_series_in_one_directory_raise(self, tmp_path) -> None:
+        _write_ct_slices(tmp_path / "mixed", "Plan CT", prefix="a")
+        _write_ct_slices(tmp_path / "mixed", "Other CT", prefix="b")
+        with pytest.raises(MixedSeriesDirectoryError) as info:
+            scan_dicom_series(tmp_path, require_single_series_per_dir=True)
+        assert info.value.directories == (tmp_path / "mixed",)
+
+    def test_off_by_default(self, tmp_path) -> None:
+        _write_ct_slices(tmp_path, "Plan CT", prefix="a")
+        _write_ct_slices(tmp_path, "Other CT", prefix="b")
+        assert len(scan_dicom_series(tmp_path).series) == 2
+
+    def test_non_image_objects_may_share_the_directory(self, tmp_path) -> None:
+        _write_ct_slices(tmp_path, "Plan CT")
+        _write_rtdose(tmp_path / "dose.dcm")
+        scan = scan_dicom_series(tmp_path, require_single_series_per_dir=True)
+        assert [e.modality for e in scan.series] == ["CT", "RTDOSE"]
+
+    def test_series_in_separate_directories_pass(self, tmp_path) -> None:
+        _write_ct_slices(tmp_path / "a", "Plan CT")
+        _write_ct_slices(tmp_path / "b", "Other CT")
+        scan = scan_dicom_series(tmp_path, require_single_series_per_dir=True)
+        assert len(scan.series) == 2
+
+    def test_4dct_phases_may_share_a_directory(self, tmp_path) -> None:
+        for percent in (0, 50):
+            _write_ct_slices(tmp_path / "4d", f"4D {percent}%", prefix=f"p{percent}_")
+        scan = scan_dicom_series(tmp_path, require_single_series_per_dir=True)
+        assert len(scan.series[0].phases) == 2
+
+    def test_4dct_phases_mixed_with_another_series_raise(self, tmp_path) -> None:
+        for percent in (0, 50):
+            _write_ct_slices(tmp_path / "4d", f"4D {percent}%", prefix=f"p{percent}_")
+        _write_ct_slices(tmp_path / "4d", "AIP", prefix="aip_")
+        with pytest.raises(MixedSeriesDirectoryError):
+            scan_dicom_series(tmp_path, require_single_series_per_dir=True)
+
+    def test_multiple_patients_are_reported_first(self, tmp_path) -> None:
+        _write_ct_slices(tmp_path, "Plan CT", prefix="a", patient="P1")
+        _write_ct_slices(tmp_path, "Other CT", prefix="b", patient="P2")
+        with pytest.raises(MultiplePatientError):
+            scan_dicom_series(tmp_path, require_single_series_per_dir=True)
+
+
+class TestLoadScannedSeries:
+    def test_loads_only_the_selected_series_from_a_shared_directory(
+        self, tmp_path
+    ) -> None:
+        _write_ct_slices(tmp_path, "A", prefix="a", value=100)
+        _write_ct_slices(tmp_path, "B", prefix="b", n_slices=5, value=200)
+        scan = scan_dicom_series(tmp_path)
+        entry_b = next(e for e in scan.series if e.description == "B")
+
+        info = load_scanned_series(entry_b)
+
+        assert info["sitk_image"].GetSize() == (4, 4, 5)
+        assert _slice_values(info["sitk_image"]) == [200, 201, 202, 203, 204]
+        assert info["transform"] is None
+
+    def test_matches_load_dcm_series(self, tmp_path) -> None:
+        _write_ct_slices(tmp_path, "A", positions=[3.0, 1.0, 2.0, 0.0], value=10)
+        (entry,) = scan_dicom_series(tmp_path).series
+        expected = load_dcm_series(tmp_path)
+        actual = load_scanned_series(entry)
+        import SimpleITK as sitk
+
+        for key in ("sitk_image", "original_sitk_image"):
+            assert actual[key].GetOrigin() == expected[key].GetOrigin()
+            assert actual[key].GetDirection() == expected[key].GetDirection()
+            assert np.array_equal(
+                sitk.GetArrayFromImage(actual[key]),
+                sitk.GetArrayFromImage(expected[key]),
+            )
+        assert actual["window_level"] == expected["window_level"]
+        assert actual["modality"] == expected["modality"]
+
+    def test_entry_without_files_falls_back_to_gdcm(self, tmp_path) -> None:
+        import dataclasses
+
+        _write_ct_slices(tmp_path, "A", prefix="a", value=1)
+        _write_ct_slices(tmp_path, "B", prefix="b", value=50)
+        entry = next(
+            e for e in scan_dicom_series(tmp_path).series if e.description == "B"
+        )
+        info = load_scanned_series(dataclasses.replace(entry, file_paths=()))
+        assert _slice_values(info["sitk_image"]) == [50, 51, 52]
+
+    def test_rejects_grouped_4dct_and_dose(self, tmp_path) -> None:
+        _write_ct_slices(tmp_path / "p0", "4D 0%")
+        _write_rtdose(tmp_path / "dose" / "dose.dcm")
+        scan = scan_dicom_series(tmp_path)
+        for entry in scan.series:
+            with pytest.raises(ValueError):
+                load_scanned_series(entry)
+
+
+class TestLoadPhaseSeries:
+    def test_loads_phases_in_order_with_their_registration(self, tmp_path) -> None:
+        import pydicom
+
+        from tk_rt_viewer.reg_io import save_registration
+
+        _write_ct_slices(tmp_path / "plan", "Plan CT")
+        for percent in (50, 0, 10):
+            _write_ct_slices(
+                tmp_path / "4d", f"4D {percent}%", prefix=f"p{percent}_", value=percent
+            )
+        # An unrelated series in the tree must not be read at all
+        _write_ct_slices(tmp_path / "other", "Other CT")
+
+        scan = scan_dicom_series(tmp_path / "plan")  # only for the reference
+        fixed_ref = pydicom.dcmread(scan.series[0].file_path, stop_before_pixels=True)
+        moving_ref = pydicom.dcmread(
+            tmp_path / "4d" / "p10_001.dcm", stop_before_pixels=True
+        )
+        matrix = np.eye(4)
+        matrix[:3, 3] = (5.0, -3.0, 2.0)
+        save_registration(tmp_path / "reg" / "reg.dcm", matrix, fixed_ref, moving_ref)
+
+        scan = scan_dicom_series(tmp_path)
+        four_d = scan.series[0]
+        phases = load_phase_series(four_d.phases, scan.reg_files)
+
+        assert list(phases) == ["0%", "10%", "50%"]
+        assert _slice_values(phases["50%"]["sitk_image"]) == [50, 51, 52]
+        assert phases["0%"]["transform"] is None
+        transform = phases["10%"]["transform"]
+        assert transform is not None
+        assert transform.TransformPoint((0.0, 0.0, 0.0)) == pytest.approx(
+            (-5.0, 3.0, -2.0)
+        )
+
+    def test_no_phases(self) -> None:
+        assert load_phase_series(()) == {}