tk-rt-viewer 2.3.2__tar.gz → 2.3.3__tar.gz

{tk_rt_viewer-2.3.2 → tk_rt_viewer-2.3.3}/CHANGELOG.md

@@ -4,6 +4,18 @@ 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.3.3]
+
+### Added
+
+- `rtstruct_io.mask2rtstruct` and `rtstruct_io.save_structure_set` take a
+  keyword-only `add_roi_kwargs` mapping, forwarded to rt-utils'
+  `RTStruct.add_roi` for every ROI. Callers can now set
+  `approximate_contours`, `use_pin_hole`, `roi_generation_algorithm`,
+  `description`, etc. `mask`, `color` and `name` still come from the
+  structures and raise `ValueError` if given here. The default (`None`)
+  keeps the previous behaviour.
+
 ## [2.3.2]
 
 ### Fixed

{tk_rt_viewer-2.3.2 → tk_rt_viewer-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tk-rt-viewer
-Version: 2.3.2
+Version: 2.3.3
 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
@@ -374,6 +374,11 @@ written = save_structure_set(
 )
 ```
 
+Pass `add_roi_kwargs` to forward options to rt-utils' `RTStruct.add_roi`
+for every ROI, e.g. `add_roi_kwargs={"approximate_contours": False}` to
+keep every contour vertex instead of the simplified outline. `mask2rtstruct`
+accepts the same keyword.
+
 `rt_utils.RTStruct.save` silently appends `.dcm` to a path that does not
 already end with it, with no way to opt out; `mask2rtstruct` resolves
 against that internally so its `exists()` check, its log messages, and its

{tk_rt_viewer-2.3.2 → tk_rt_viewer-2.3.3}/README.md

@@ -337,6 +337,11 @@ written = save_structure_set(
 )
 ```
 
+Pass `add_roi_kwargs` to forward options to rt-utils' `RTStruct.add_roi`
+for every ROI, e.g. `add_roi_kwargs={"approximate_contours": False}` to
+keep every contour vertex instead of the simplified outline. `mask2rtstruct`
+accepts the same keyword.
+
 `rt_utils.RTStruct.save` silently appends `.dcm` to a path that does not
 already end with it, with no way to opt out; `mask2rtstruct` resolves
 against that internally so its `exists()` check, its log messages, and its

{tk_rt_viewer-2.3.2 → tk_rt_viewer-2.3.3}/src/tk_rt_viewer/__init__.py

@@ -104,7 +104,7 @@ __all__ = [
     "StructureSet",
     "to_gy_pairs",
 ]
-__version__ = "2.3.2"
+__version__ = "2.3.3"
 
 
 def __getattr__(name: str) -> Any:

{tk_rt_viewer-2.3.2 → tk_rt_viewer-2.3.3}/src/tk_rt_viewer/io.py

@@ -55,7 +55,7 @@ import re
 from collections.abc import Iterable, Iterator, Sequence
 from concurrent.futures import ThreadPoolExecutor
 from dataclasses import dataclass, field, replace
-from typing import TypedDict
+from typing import TypedDict, cast
 
 import numpy as np
 import pydicom
@@ -672,7 +672,7 @@ def _read_files(
     """Read *file_names* as one series, keeping per-slice metadata on *reader*."""
     reader.SetFileNames(file_names)
     reader.MetaDataDictionaryArrayUpdateOn()
-    image = reader.Execute()
+    image = cast(sitk.Image, reader.Execute())
     logger.info(f"Series '{series_id}' loaded with {len(file_names)} files.")
     return image
 

{tk_rt_viewer-2.3.2 → tk_rt_viewer-2.3.3}/src/tk_rt_viewer/rtstruct_io.py

@@ -8,13 +8,15 @@ load_rt_struct(ct_dir, rtstruct_path, progress_callback=None, max_workers=1)
     and display metadata. Raises RtStructLoadError if the file itself
     cannot be parsed.
 
-mask2rtstruct(ct_dir, rtss_path, structures) -> pathlib.Path
+mask2rtstruct(ct_dir, rtss_path, structures, *, replace_existing=True,
+              add_roi_kwargs=None) -> pathlib.Path
     Convert NumPy mask arrays to an RT-STRUCT DICOM file, creating or
     updating as appropriate. Returns the path actually written to (rt-utils
-    appends ".dcm" to a path that lacks it).
+    appends ".dcm" to a path that lacks it). add_roi_kwargs is forwarded to
+    rt-utils' RTStruct.add_roi (e.g. approximate_contours).
 
 save_structure_set(structure_set, ct_dir, rtss_path, lps_image,
-                   original_image=None) -> int
+                   original_image=None, *, add_roi_kwargs=None) -> int
     Write every ROI of a StructureSet to an RT-STRUCT file, resampling
     each mask back to the original DICOM geometry first.
 
@@ -29,7 +31,7 @@ random_hex_color() -> str
 import logging
 import pathlib
 from collections import Counter
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from concurrent.futures import ThreadPoolExecutor, as_completed
 from typing import TYPE_CHECKING, Any, TypedDict
 
@@ -63,6 +65,9 @@ _COLOR_RNG: np.random.Generator = np.random.default_rng()
 #: Suffix rt-utils' ``RTStruct.save()`` silently appends to any path lacking it.
 _RTSTRUCT_SUFFIX = ".dcm"
 
+#: add_roi keywords mask2rtstruct fills in itself from *structures*
+_RESERVED_ADD_ROI_KEYS = frozenset({"mask", "color", "name"})
+
 
 def _resolved_rtss_path(rtss_path: pathlib.Path) -> pathlib.Path:
     """Return the path rt-utils will actually write *rtss_path* to.
@@ -97,6 +102,8 @@ def save_structure_set(
     rtss_path: str | pathlib.Path,
     lps_image: sitk.Image,
     original_image: sitk.Image | None = None,
+    *,
+    add_roi_kwargs: Mapping[str, Any] | None = None,
 ) -> int:
     """Write every ROI of *structure_set* to an RT-STRUCT file.
 
@@ -115,13 +122,15 @@ def save_structure_set(
         original_image: The CT before LPS alignment
             (``SeriesInfo["original_sitk_image"]``). ``None`` when the series
             needed no reorientation; the masks are then written as they are.
+        add_roi_kwargs: Forwarded to :func:`mask2rtstruct`.
 
     Returns:
         The number of ROIs written.
 
     Raises:
         ValueError: If *structure_set* contains no ROI with a usable mask,
-            since that would write an RT-STRUCT with no structures at all.
+            since that would write an RT-STRUCT with no structures at all,
+            or if *add_roi_kwargs* contains a reserved key.
         RuntimeError: If rt-utils rejects an ROI (propagated from
             :func:`mask2rtstruct`).
     """
@@ -146,7 +155,9 @@ def save_structure_set(
     if not structures:
         raise ValueError("Structure set contains no ROI with a mask to save.")
 
-    written_path = mask2rtstruct(ct_dir, rtss_path, structures)
+    written_path = mask2rtstruct(
+        ct_dir, rtss_path, structures, add_roi_kwargs=add_roi_kwargs
+    )
     logger.info(f"Structure set saved to '{written_path}' ({len(structures)} ROIs).")
     return len(structures)
 
@@ -333,6 +344,7 @@ def mask2rtstruct(
     structures: dict[int, dict[str, Any]],
     *,
     replace_existing: bool = True,
+    add_roi_kwargs: Mapping[str, Any] | None = None,
 ) -> pathlib.Path:
     """Write ``(D, H, W)`` mask arrays to an RT-STRUCT DICOM file.
 
@@ -346,17 +358,32 @@ def mask2rtstruct(
             rebuilt so it holds exactly *structures*. ``False`` appends to the
             existing file instead; rt-utils cannot remove ROIs, so saving the
             same ROIs twice that way duplicates them.
+        add_roi_kwargs: Extra keyword arguments forwarded to rt-utils'
+            ``RTStruct.add_roi`` for every ROI, e.g.
+            ``{"approximate_contours": False, "use_pin_hole": True}``.
+            ``mask``, ``color`` and ``name`` are taken from *structures*
+            and must not be given here.
 
     Returns:
         The path actually written.
 
     Raises:
-        ValueError: If *rtss_path* is ``None``.
-        RuntimeError: If any ROI cannot be added to the RT-STRUCT builder.
+        ValueError: If *rtss_path* is ``None`` or *add_roi_kwargs* contains
+            a reserved key.
+        RuntimeError: If any ROI cannot be added to the RT-STRUCT builder
+            (including unknown keys in *add_roi_kwargs*).
     """
     if rtss_path is None:
         raise ValueError("rtss_path must not be None; provide a concrete output path.")
 
+    roi_options = dict(add_roi_kwargs or {})
+    reserved = _RESERVED_ADD_ROI_KEYS & roi_options.keys()
+    if reserved:
+        raise ValueError(
+            f"add_roi_kwargs must not contain {sorted(reserved)}; "
+            "they are taken from structures."
+        )
+
     ct_dir = pathlib.Path(ct_dir)
     rtss_path = _resolved_rtss_path(pathlib.Path(rtss_path))
 
@@ -382,6 +409,7 @@ def mask2rtstruct(
                 mask=np.transpose(roi_data["mask"], (1, 2, 0)).astype(bool, copy=False),
                 color=roi_data["color"],
                 name=roi_name,
+                **roi_options,
             )
         except Exception as exc:
             logger.error(f"Failed to add ROI '{roi_name}': {exc}")

{tk_rt_viewer-2.3.2 → tk_rt_viewer-2.3.3}/tests/test_rtstruct_io.py

@@ -22,16 +22,17 @@ from tk_rt_viewer.state.viewer_state import StructureSet
 
 @pytest.fixture()
 def captured_structures(monkeypatch) -> dict:
-    """Capture the structures dict (and replace_existing) passed to mask2rtstruct."""
+    """Capture the arguments passed to mask2rtstruct."""
     captured: dict = {}
 
     def fake_mask2rtstruct(
-        ct_dir, rtss_path, structures, *, replace_existing=True
+        ct_dir, rtss_path, structures, *, replace_existing=True, add_roi_kwargs=None
     ) -> pathlib.Path:
         captured["ct_dir"] = ct_dir
         captured["rtss_path"] = rtss_path
         captured["structures"] = structures
         captured["replace_existing"] = replace_existing
+        captured["add_roi_kwargs"] = add_roi_kwargs
         return pathlib.Path(rtss_path)
 
     monkeypatch.setattr(rtstruct_io, "mask2rtstruct", fake_mask2rtstruct)
@@ -142,6 +143,22 @@ class TestSaveStructureSet:
 
         assert captured_structures["replace_existing"] is True
 
+    def test_add_roi_kwargs_is_forwarded(self, captured_structures) -> None:
+        lps = _image()
+        structure_set = StructureSet()
+        structure_set.add("PTV", _mask(lps), "#ff0000")
+        options = {"approximate_contours": False}
+
+        rtstruct_io.save_structure_set(
+            structure_set,
+            "/ct",
+            "/out/rs.dcm",
+            lps_image=lps,
+            add_roi_kwargs=options,
+        )
+
+        assert captured_structures["add_roi_kwargs"] == options
+
 
 class TestSaveStructureSetResampling:
     """Resampling must happen only when there is a different geometry to reach."""
@@ -344,6 +361,92 @@ class TestMask2RtStructImplicitDcmSuffix:
         assert written == out
 
 
+class TestMask2RtStructAddRoiKwargs:
+    """``add_roi_kwargs`` reaches ``RTStruct.add_roi`` for every ROI."""
+
+    @staticmethod
+    def _structures() -> dict:
+        mask = np.zeros((4, 8, 8), dtype=bool)
+        mask[1:3, 2:6, 2:6] = True
+        return {
+            1: {"name": "PTV", "mask": mask, "color": "#ff0000"},
+            2: {"name": "CTV", "mask": mask.copy(), "color": "#00ff00"},
+        }
+
+    @staticmethod
+    def _ct_dir(tmp_path) -> pathlib.Path:
+        ct_dir = tmp_path / "ct"
+        ct_dir.mkdir()
+        _write_minimal_ct_series(ct_dir)
+        return ct_dir
+
+    def test_options_are_passed_to_every_add_roi_call(
+        self, tmp_path, monkeypatch
+    ) -> None:
+        from rt_utils import RTStruct
+
+        calls: list[dict] = []
+        real_add_roi = RTStruct.add_roi
+
+        def spy(self, **kwargs):
+            calls.append(kwargs)
+            return real_add_roi(self, **kwargs)
+
+        monkeypatch.setattr(RTStruct, "add_roi", spy)
+
+        rtstruct_io.mask2rtstruct(
+            self._ct_dir(tmp_path),
+            tmp_path / "rs.dcm",
+            self._structures(),
+            add_roi_kwargs={"approximate_contours": False, "description": "auto"},
+        )
+
+        assert len(calls) == 2
+        assert all(c["approximate_contours"] is False for c in calls)
+        assert all(c["description"] == "auto" for c in calls)
+
+    def test_none_keeps_the_rt_utils_defaults(self, tmp_path, monkeypatch) -> None:
+        from rt_utils import RTStruct
+
+        calls: list[dict] = []
+        real_add_roi = RTStruct.add_roi
+
+        def spy(self, **kwargs):
+            calls.append(kwargs)
+            return real_add_roi(self, **kwargs)
+
+        monkeypatch.setattr(RTStruct, "add_roi", spy)
+
+        rtstruct_io.mask2rtstruct(
+            self._ct_dir(tmp_path), tmp_path / "rs.dcm", self._structures()
+        )
+
+        assert all(set(c) == {"mask", "color", "name"} for c in calls)
+
+    @pytest.mark.parametrize("key", ["mask", "color", "name"])
+    def test_reserved_keys_are_rejected_before_writing(self, tmp_path, key) -> None:
+        out = tmp_path / "rs.dcm"
+
+        with pytest.raises(ValueError, match=key):
+            rtstruct_io.mask2rtstruct(
+                tmp_path / "missing_ct",
+                out,
+                self._structures(),
+                add_roi_kwargs={key: None},
+            )
+
+        assert not out.exists()
+
+    def test_an_unknown_option_raises_runtime_error(self, tmp_path) -> None:
+        with pytest.raises(RuntimeError, match="PTV"):
+            rtstruct_io.mask2rtstruct(
+                self._ct_dir(tmp_path),
+                tmp_path / "rs.dcm",
+                self._structures(),
+                add_roi_kwargs={"no_such_option": True},
+            )
+
+
 class TestLoadRtStructDuplicateNames:
     """Pins a 2.0.1 fix: two ROIs sharing a name must not collapse onto one mask.