tk-rt-viewer 1.1.0__py3-none-any.whl

tk_rt_viewer/__init__.py

@@ -0,0 +1,101 @@
+"""tk_rt_viewer — SimpleITK-based DICOM MPR viewer widget for Tkinter.
+
+Public API (re-exported here)
+-----------------------------
+DicomViewer
+    A ``ttk.Frame`` subclass embedding an MPR viewer. Layout is selectable
+    via ``SliceViewerState.layout_mode``: ``"mpr_wide"`` (default; axial
+    large left, coronal/sagittal stacked right), ``"mpr"`` (2x2 grid with a
+    DVH panel), or ``"single"`` (axial only). Supports secondary image
+    blending and 4DCT phase overlay via a built-in blend slider.
+
+SliceViewerState
+    Observable state container.  Holds all mutable state: images, indices,
+    window/level, ROI masks, brush settings, bounding boxes, crosshair
+    positions, and 4DCT phase data. Change events are declared as constants
+    in :mod:`tk_rt_viewer.events`.
+
+StructureSet / RoiEntry
+    ROI mask container keyed by integer ROI number, and the typed entry it
+    stores. Used internally by ``SliceViewerState``; exposed here for
+    callers that build structure sets directly.
+
+IsoDoseLevel / DEFAULT_ISODOSE_LEVELS / to_gy_pairs
+    Iso-dose levels expressed as a percentage of a reference dose, the
+    default ladder the overlay falls back to, and the conversion to the
+    ``(Gy, colour)`` pairs ``DicomViewer.set_isodose_lines`` takes. Use
+    these to build an iso-dose settings UI without restating the levels.
+
+Submodule API (import from the submodule)
+-----------------------------------------
+``tk_rt_viewer.io``
+    validate_dicom_files, find_reg_matrices,
+    load_all_series, load_dcm_series, normalize_phase_label
+
+``tk_rt_viewer.rtstruct_io``
+    load_rt_struct, mask2rtstruct, save_structure_set,
+    resample_mask_to_original_space, random_hex_color, RtStructLoadError
+
+``tk_rt_viewer.roi_operations``
+    interpolate_contour, apply_margin, smooth_contour,
+    boolean_operation, thin_slices
+
+``tk_rt_viewer.events``
+    Event-name constants for ``SliceViewerState.add_listener``.
+
+Quick start::
+
+    import tkinter as tk
+    from tk_rt_viewer import DicomViewer, SliceViewerState
+
+    root = tk.Tk()
+    state = SliceViewerState()
+    viewer = DicomViewer(root, state=state)
+    viewer.pack(fill="both", expand=True)
+    viewer.load_ct("/path/to/dicom")
+    root.mainloop()
+"""
+
+from typing import TYPE_CHECKING, Any
+
+from .isodose_levels import DEFAULT_ISODOSE_LEVELS, IsoDoseLevel, to_gy_pairs
+from .state.viewer_state import RoiEntry, SliceViewerState, StructureSet
+
+if TYPE_CHECKING:
+    from .viewer import DicomViewer
+
+__all__ = [
+    "DEFAULT_ISODOSE_LEVELS",
+    "DicomViewer",
+    "IsoDoseLevel",
+    "RoiEntry",
+    "SliceViewerState",
+    "StructureSet",
+    "to_gy_pairs",
+]
+__version__ = "1.1.0"
+
+
+def __getattr__(name: str) -> Any:
+    """Import :class:`DicomViewer` on first access.
+
+    ``viewer`` pulls in Tkinter and a Matplotlib GUI backend. Importing it
+    eagerly here meant that reaching for any part of this package — the
+    ``events`` constants, the pure-SimpleITK helpers in ``io``,
+    ``rtstruct_io`` and ``roi_operations`` — required a working Tkinter
+    build, so those helpers could not be used from a headless process
+    (a batch converter, an inference worker, a CI runner without
+    ``python3-tk``). Deferring the import keeps the widget available as
+    ``tk_rt_viewer.DicomViewer`` while leaving the GUI-free modules
+    importable on their own.
+    """
+    if name == "DicomViewer":
+        from .viewer import DicomViewer
+
+        return DicomViewer
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    """Include the lazily imported names in ``dir()`` and tab completion."""
+    return sorted([*globals(), *__all__])

tk_rt_viewer/event_controllers/bbox_handler.py

@@ -0,0 +1,270 @@
+"""bbox_handler.py — Bounding box drag event handler.
+
+The bounding box is stored in :class:`SliceViewerState` as physical
+coordinates ``(x_min, y_min, width, height)``.  This handler translates
+mouse events into state updates; rendering is performed by
+:class:`DicomViewer` through the ``"bounding_boxes_changed"`` listener.
+
+Supported interactions:
+    - **Create**: left-click on empty space -> drag to define a new box.
+    - **Move**: left-click inside an existing box -> drag to reposition.
+    - **Resize**: left-click near an edge or corner handle -> drag to resize.
+      Handle detection tolerance is :attr:`TOLERANCE_PIXELS` pixels.
+"""
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from ..state.viewer_state import SliceViewerState
+    from ..viewer import DicomViewer
+
+
+class BboxEventHandler:
+    """Handle bounding-box create / move / resize interactions."""
+
+    #: Pixel radius within which an edge or corner counts as a resize handle.
+    TOLERANCE_PIXELS: int = 5
+
+    #: Minimum allowed box dimension (in data units) during a resize.
+    _MIN_SIZE: float = 1.0
+
+    def __init__(self, state: "SliceViewerState", viewer: "DicomViewer") -> None:
+        self.state = state
+        self.viewer = viewer
+
+        self._interaction_mode: str | None = None  # "create" | "move" | "resize"
+        self._resize_handle: str | None = None  # "t" | "b" | "l" | "r" | corners
+        self._active_axis: str | None = None
+        self._is_dragging: bool = False
+        self._drag_start_pos_data: tuple[float, float] | None = None
+        self._original_pos: list[float] | None = None
+
+    @property
+    def is_dragging(self) -> bool:
+        """``True`` while a bounding-box interaction is in progress."""
+        return self._is_dragging
+
+    # ------------------------------------------------------------------
+    # Event handlers
+    # ------------------------------------------------------------------
+    def handle_press(self, event) -> bool:
+        """Begin a create, move, or resize interaction on left-button press.
+
+        Returns:
+            ``True`` if the handler consumed the event; ``False`` otherwise.
+        """
+        if not self.state.bbox_visible:
+            return False
+
+        axis = self.state.current_axis
+        if not axis or event.xdata is None or event.ydata is None:
+            return False
+
+        px, py = event.xdata, event.ydata
+        bbox = self.state.bounding_boxes.get(axis)
+        handle = self._detect_handle(event, axis)
+
+        if handle and bbox is not None:
+            # Resize an existing box. _detect_handle only returns a handle
+            # when a box exists, so the bbox check is for the type checker
+            # and against future refactors breaking that invariant.
+            self._begin_drag(axis, "resize", (px, py), list(bbox))
+            self._resize_handle = handle
+            return True
+
+        if bbox is not None and (
+            bbox[0] <= px <= bbox[0] + bbox[2] and bbox[1] <= py <= bbox[1] + bbox[3]
+        ):
+            # Move the existing box.
+            self._begin_drag(axis, "move", (px, py), list(bbox))
+            return True
+
+        # Click outside any existing box: clear and start creating a new one.
+        self.state.set_bounding_box(axis, None)
+        self._begin_drag(axis, "create", (px, py), None)
+        self.state.set_bounding_box(axis, (px, py, 0, 0))
+        return True
+
+    def handle_motion(self, event) -> None:
+        """Update the bounding box as the mouse moves during a drag."""
+        if (
+            not self._is_dragging
+            or not self._active_axis
+            or event.xdata is None
+            or event.ydata is None
+        ):
+            return
+        self._apply_drag(event.xdata, event.ydata)
+
+    def handle_release(self, event) -> None:
+        """End the current interaction on left-button release.
+
+        Tk can coalesce or simply drop ``motion_notify_event`` callbacks
+        during a fast drag, so the geometry last committed by
+        :meth:`handle_motion` is not guaranteed to reflect the pixel the
+        mouse was actually released at. Without a final update here, a
+        quick drag can commit a box shaped like an early, still-thin
+        intermediate frame — visually indistinguishable from a single
+        line — instead of the box the user actually drew. Applying one
+        last update using the release event's own coordinates closes
+        that gap.
+        """
+        if event.button != 1:
+            return
+        if self._is_dragging and event.xdata is not None and event.ydata is not None:
+            self._apply_drag(event.xdata, event.ydata)
+        self._is_dragging = False
+        self._interaction_mode = None
+        self._resize_handle = None
+        self._active_axis = None
+        self._drag_start_pos_data = None
+        self._original_pos = None
+
+    def _apply_drag(self, px: float, py: float) -> None:
+        """Update the box currently being created/moved/resized to (px, py).
+
+        Callers guarantee a drag is in progress; the guard below encodes
+        that invariant explicitly (and narrows the Optionals for type
+        checking) rather than assuming it.
+        """
+        axis = self._active_axis
+        if axis is None or self._drag_start_pos_data is None:
+            return
+        x0, y0 = self._drag_start_pos_data
+        mode = self._interaction_mode
+
+        if mode == "create":
+            x_start, x_end = (x0, px) if x0 <= px else (px, x0)
+            y_start, y_end = (y0, py) if y0 <= py else (py, y0)
+            self.state.set_bounding_box(
+                axis, (x_start, y_start, x_end - x_start, y_end - y_start)
+            )
+        elif mode == "move":
+            if self._original_pos is None:
+                return
+            x, y, w, h = self._original_pos
+            self.state.set_bounding_box(axis, (x + px - x0, y + py - y0, w, h))
+        elif mode == "resize":
+            self._resize_bbox(px - x0, py - y0)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+    def _begin_drag(
+        self,
+        axis: str,
+        mode: str,
+        start_pos: tuple[float, float],
+        original_pos: list[float] | None,
+    ) -> None:
+        """Initialise drag state for any of the three interaction modes."""
+        self._interaction_mode = mode
+        self._active_axis = axis
+        self._is_dragging = True
+        self._drag_start_pos_data = start_pos
+        self._original_pos = original_pos
+
+    def _detect_handle(self, event, axis: str) -> str | None:
+        """Return the name of the resize handle under the cursor, or ``None``.
+
+        Handle names use compass notation: ``"t"``, ``"b"``, ``"l"``, ``"r"``
+        for edges and ``"tl"``, ``"tr"``, ``"bl"``, ``"br"`` for corners.
+
+        Edge-to-handle mapping (defined in data coordinates):
+            "l" = left edge   (x_min)
+            "r" = right edge  (x_max = x + w)
+            "b" = bottom edge (y_min; posterior in axial, inferior in cor/sag)
+            "t" = top edge    (y_max = y + h; anterior in axial, superior in cor/sag)
+
+        Detection is performed in data coordinates. The pixel tolerance is
+        converted to data units via an inverse transform so that the correct
+        handle is returned regardless of ylim orientation.
+        """
+        bbox = self.state.bounding_boxes.get(axis)
+        if bbox is None or not self.viewer.axs.get(axis):
+            return None
+        if event.xdata is None or event.ydata is None:
+            return None
+
+        ax = self.viewer.axs[axis]
+        x, y, w, h = bbox
+        x_min, x_max = x, x + w
+        y_min, y_max = y, y + h
+
+        # Convert the pixel tolerance to data units via the inverse display
+        # transform. Before the axes has been drawn its transform can be
+        # singular, so a non-invertible / degenerate transform falls back to
+        # a 1-data-unit tolerance rather than swallowing unrelated errors.
+        try:
+            inv = ax.transData.inverted()
+            p0 = inv.transform((0, 0))
+            p1 = inv.transform((self.TOLERANCE_PIXELS, self.TOLERANCE_PIXELS))
+            tol_x = abs(p1[0] - p0[0])
+            tol_y = abs(p1[1] - p0[1])
+        except (np.linalg.LinAlgError, ValueError):
+            tol_x = tol_y = 1.0
+
+        ex, ey = event.xdata, event.ydata
+        on_l = abs(ex - x_min) < tol_x
+        on_r = abs(ex - x_max) < tol_x
+        on_b = abs(ey - y_min) < tol_y
+        on_t = abs(ey - y_max) < tol_y
+
+        if on_t and on_l:
+            return "tl"
+        if on_t and on_r:
+            return "tr"
+        if on_b and on_l:
+            return "bl"
+        if on_b and on_r:
+            return "br"
+        if on_t:
+            return "t"
+        if on_b:
+            return "b"
+        if on_l:
+            return "l"
+        if on_r:
+            return "r"
+        return None
+
+    def _resize_bbox(self, dx: float, dy: float) -> None:
+        """Apply a resize delta to the original box according to the active handle.
+
+        dx/dy are data-coordinate deltas (event.xdata/ydata - drag_start).
+        Because :meth:`_detect_handle` also operates in data coordinates, the
+        dragged edge always moves in the expected direction regardless of
+        ylim orientation:
+
+            dragging "t" up   (dy > 0) -> increase y_max -> h += dy
+            dragging "b" down (dy < 0) -> decrease y_min -> y += dy; h -= dy
+        """
+        handle = self._resize_handle
+        axis = self._active_axis
+        if handle is None or axis is None or self._original_pos is None:
+            return
+        x, y, w, h = self._original_pos
+        min_size = self._MIN_SIZE
+
+        if "l" in handle:
+            new_w = w - dx
+            if new_w >= min_size:
+                x += dx
+                w = new_w
+        if "r" in handle:
+            new_w = w + dx
+            if new_w >= min_size:
+                w = new_w
+        if "t" in handle:
+            new_h = h + dy
+            if new_h >= min_size:
+                h = new_h
+        if "b" in handle:
+            new_h = h - dy
+            if new_h >= min_size:
+                y += dy
+                h = new_h
+
+        self.state.set_bounding_box(axis, (x, y, w, h))