tk-rt-viewer 2.3.0__tar.gz → 2.3.1__tar.gz

{tk_rt_viewer-2.3.0 → tk_rt_viewer-2.3.1}/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.1]
+
+A newly drawn 3-D box no longer spans the whole image along the axis that
+cannot be seen while drawing.
+
+### Added
+
+- **`geometry.fit_box_length(image, dim, length, min_extent)`**: returns
+  *length*, or half of the image's extent along *dim* when that extent is
+  shorter than *min_extent*.
+
+### Changed
+
+- A 3-D box newly drawn on a view is now
+  **`Bbox3dEventHandler.NEW_BOX_DEPTH_MM`** (50 mm) deep along that view's
+  normal, centred on the displayed slice. It used to keep the depth of the box
+  it replaced, or span the whole image when none was left (e.g. after a
+  clearing click), which hid how deep the box was while drawing.
+- Where the image along that normal is shorter than
+  **`Bbox3dEventHandler.NARROW_EXTENT_MM`** (60 mm), e.g. a short
+  craniocaudal scan range, the new box is half the image deep instead, so it
+  does not fill the image end to end.
+
 ## [2.3.0]
 
 Zoom per view, a reversible wheel, and views that fill the figure.

{tk_rt_viewer-2.3.0 → tk_rt_viewer-2.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tk-rt-viewer
-Version: 2.3.0
+Version: 2.3.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
@@ -544,7 +544,7 @@ visible the 3-D box takes the mouse.
 ```python
 from tk_rt_viewer import Box3D
 
-# Turn the tool on; the user draws on any view. Drawing on a second view
+# Turn the tool on; the user draws on any view. Resizing on a second view
 # trims the depth of the box drawn on the first.
 state.set_bbox_3d_visible(True)
 
@@ -560,7 +560,10 @@ state.set_bounding_box_3d(None)
 ```
 
 Clicking outside the box clears it, as with the per-view box; a drag that
-follows redraws it in that plane while keeping the depth set on another view.
+follows draws a new box in that plane, 50 mm deep along the view's normal and
+centred on the displayed slice (`Bbox3dEventHandler.NEW_BOX_DEPTH_MM`), or half
+the image deep where the image is narrower than 60 mm along that normal
+(`NARROW_EXTENT_MM`). Resize or move it on another view to change its depth.
 
 Each view draws the box solid while the displayed slice cuts through it and
 dashed while it does not, so its depth is visible without leaving the slice.

{tk_rt_viewer-2.3.0 → tk_rt_viewer-2.3.1}/README.md

@@ -507,7 +507,7 @@ visible the 3-D box takes the mouse.
 ```python
 from tk_rt_viewer import Box3D
 
-# Turn the tool on; the user draws on any view. Drawing on a second view
+# Turn the tool on; the user draws on any view. Resizing on a second view
 # trims the depth of the box drawn on the first.
 state.set_bbox_3d_visible(True)
 
@@ -523,7 +523,10 @@ state.set_bounding_box_3d(None)
 ```
 
 Clicking outside the box clears it, as with the per-view box; a drag that
-follows redraws it in that plane while keeping the depth set on another view.
+follows draws a new box in that plane, 50 mm deep along the view's normal and
+centred on the displayed slice (`Bbox3dEventHandler.NEW_BOX_DEPTH_MM`), or half
+the image deep where the image is narrower than 60 mm along that normal
+(`NARROW_EXTENT_MM`). Resize or move it on another view to change its depth.
 
 Each view draws the box solid while the displayed slice cuts through it and
 dashed while it does not, so its depth is visible without leaving the slice.

{tk_rt_viewer-2.3.0 → tk_rt_viewer-2.3.1}/src/tk_rt_viewer/__init__.py

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

tk_rt_viewer-2.3.1/src/tk_rt_viewer/event_controllers/bbox3d_handler.py

@@ -0,0 +1,60 @@
+"""bbox3d_handler.py — Volumetric (3-D) bounding box drag handler.
+
+The box is a single :class:`~tk_rt_viewer.geometry.Box3D` in
+:class:`~tk_rt_viewer.state.viewer_state.SliceViewerState`; every view shows
+its projection and the viewer renders it through the
+``"bounding_box_3d_changed"`` listener.
+
+A gesture on any view edits that one box and only the two dimensions the view
+displays; the perpendicular dimension is set from a view that shows it. A new
+box drawn on a view is :attr:`Bbox3dEventHandler.NEW_BOX_DEPTH_MM` deep,
+centred on the displayed slice, so it never spans the whole image along the
+axis the user cannot see while drawing. Along an image narrower than
+:attr:`Bbox3dEventHandler.NARROW_EXTENT_MM` it is half the image instead.
+"""
+
+from ..geometry import AXIS_TO_XYZ_DIM, Box3D, fit_box_length
+from .rect_drag import Rect, RectDragHandler
+
+
+class Bbox3dEventHandler(RectDragHandler):
+    """Create / move / resize the 3-D bounding box from any view."""
+
+    #: Depth (mm) of a newly drawn box along the normal of the view it is
+    #: drawn on, centred on the displayed slice. Hosts may override it.
+    NEW_BOX_DEPTH_MM: float = 50.0
+
+    #: Image extent (mm) along that normal below which the new box is half the
+    #: extent instead, so it does not fill a narrow scan range.
+    NARROW_EXTENT_MM: float = 60.0
+
+    def _is_enabled(self) -> bool:
+        return self.state.bbox_3d_visible and self.state.primary_image is not None
+
+    def _current_rect(self, axis: str) -> Rect | None:
+        box = self.state.bounding_box_3d
+        return None if box is None else box.project(axis)
+
+    def _clear(self, axis: str) -> None:
+        self.state.set_bounding_box_3d(None)
+
+    def _commit(self, axis: str, rect: Rect, mode: str) -> None:
+        if mode == "create" and self.state.primary_image is not None:
+            self.state.set_bounding_box_3d(self._new_box(axis, rect))
+        else:
+            self.state.set_bbox_3d_from_view(axis, rect)
+
+    def _new_box(self, axis: str, rect: Rect) -> Box3D:
+        """Return a box drawn as *rect* on *axis*, centred on the displayed slice."""
+        dim = AXIS_TO_XYZ_DIM[axis]
+        center = self.state.index_to_physical(axis, self.state.indices[axis])
+        depth = fit_box_length(
+            self.state.primary_image,
+            dim,
+            self.NEW_BOX_DEPTH_MM,
+            self.NARROW_EXTENT_MM,
+        )
+        base = Box3D(lower=(0.0, 0.0, 0.0), upper=(0.0, 0.0, 0.0))
+        return base.with_range(
+            dim, center - depth / 2.0, center + depth / 2.0
+        ).with_view_rect(axis, rect)

{tk_rt_viewer-2.3.0 → tk_rt_viewer-2.3.1}/src/tk_rt_viewer/geometry.py

@@ -197,6 +197,25 @@ def as_point(values) -> tuple[float, float, float]:
     return (float(values[0]), float(values[1]), float(values[2]))
 
 
+def fit_box_length(
+    image: sitk.Image, dim: int, length: float, min_extent: float
+) -> float:
+    """Return *length*, or half of *image*'s extent along *dim* if it is narrow.
+
+    A default-sized box would cover a narrow image (e.g. a short craniocaudal
+    scan range) end to end, so when the extent along physical dimension *dim*
+    (0=x, 1=y, 2=z) is shorter than *min_extent* the box takes half of it.
+
+    Args:
+        image: The image the box is drawn on.
+        dim: Physical dimension (0=x, 1=y, 2=z).
+        length: Preferred box length in mm.
+        min_extent: Extent (mm) below which half the extent is used instead.
+    """
+    extent = Box3D.from_image_extent(image).size[dim]
+    return extent / 2.0 if extent < min_extent else length
+
+
 def view_dims(axis: str) -> tuple[int, int]:
     """Return the physical dimensions plotted on *axis*' x and y axes.
 

{tk_rt_viewer-2.3.0 → tk_rt_viewer-2.3.1}/tests/test_bbox3d_handler.py

@@ -19,7 +19,7 @@ from matplotlib.figure import Figure
 
 from tk_rt_viewer.event_controllers import rect_drag
 from tk_rt_viewer.event_controllers.bbox3d_handler import Bbox3dEventHandler
-from tk_rt_viewer.geometry import AXES, Box3D
+from tk_rt_viewer.geometry import AXES
 from tk_rt_viewer.state.viewer_state import SliceViewerState
 
 
@@ -134,33 +134,80 @@ class TestRectDrag:
 
 
 class TestBbox3dHandler:
-    def test_drag_creates_a_full_depth_box(self, setup) -> None:
+    @staticmethod
+    def _slice_coordinate(state: SliceViewerState, axis: str) -> float:
+        return state.index_to_physical(axis, state.indices[axis])
+
+    def test_drag_creates_a_fixed_depth_box_on_the_displayed_slice(self, setup) -> None:
         state, handler, _ = setup
         drag(handler, (-10.0, -10.0), (10.0, 20.0))
 
         box = state.bounding_box_3d
         assert box is not None
         assert box.project("axial") == pytest.approx((-10.0, -10.0, 20.0, 30.0))
-        extent = Box3D.from_image_extent(state.primary_image)
-        assert (box.lower[2], box.upper[2]) == (extent.lower[2], extent.upper[2])
+        center = self._slice_coordinate(state, "axial")
+        half = Bbox3dEventHandler.NEW_BOX_DEPTH_MM / 2.0
+        assert (box.lower[2], box.upper[2]) == pytest.approx(
+            (center - half, center + half)
+        )
+
+    def test_new_box_on_a_narrow_image_is_half_the_image_deep(self) -> None:
+        state = SliceViewerState()
+        # 10 axial slices x 3 mm = 30 mm craniocaudally (narrower than 60 mm)
+        image = sitk.GetImageFromArray(np.zeros((10, 40, 40), dtype=np.int16))
+        image.SetSpacing((2.0, 2.0, 3.0))
+        state.set_primary_image_data(image)
+        state.set_bbox_3d_visible(True)
+        handler = Bbox3dEventHandler(state, FakeViewer(), FakeHover())
+
+        drag(handler, (10.0, 10.0), (30.0, 30.0))
 
-    def test_drag_on_another_view_only_changes_that_view_dimensions(
+        assert state.bounding_box_3d.size[2] == pytest.approx(15.0)
+
+    def test_new_box_after_a_clearing_click_keeps_the_fixed_depth(self, setup) -> None:
+        state, handler, _ = setup
+        drag(handler, (-10.0, -10.0), (10.0, 20.0))
+        drag(handler, (-30.0, -30.0), (-30.0, -30.0))
+        assert state.bounding_box_3d is None
+
+        drag(handler, (-20.0, -20.0), (0.0, 0.0))
+
+        box = state.bounding_box_3d
+        assert box.size[2] == pytest.approx(Bbox3dEventHandler.NEW_BOX_DEPTH_MM)
+
+    def test_new_box_on_another_view_uses_that_view_slice_for_depth(
         self, setup
     ) -> None:
         state, handler, hover = setup
         drag(handler, (-10.0, -10.0), (10.0, 20.0))
-        y_range = (state.bounding_box_3d.lower[1], state.bounding_box_3d.upper[1])
 
-        # Start outside the current projection: the box is redrawn in this
-        # plane, keeping the depth (y) set from the axial view.
+        # Start outside the current projection: a new box is drawn in this
+        # plane, its depth (y) centred on the displayed coronal slice
         hover.current_axis = "coronal"  # shows x and z
         drag(handler, (-30.0, -6.0), (-20.0, 6.0))
 
         box = state.bounding_box_3d
-        assert (box.lower[1], box.upper[1]) == y_range
+        center = self._slice_coordinate(state, "coronal")
+        half = Bbox3dEventHandler.NEW_BOX_DEPTH_MM / 2.0
+        assert (box.lower[1], box.upper[1]) == pytest.approx(
+            (center - half, center + half)
+        )
         assert (box.lower[2], box.upper[2]) == pytest.approx((-6.0, 6.0))
         assert (box.lower[0], box.upper[0]) == pytest.approx((-30.0, -20.0))
 
+    def test_resize_on_another_view_keeps_the_depth(self, setup) -> None:
+        state, handler, hover = setup
+        drag(handler, (-10.0, -10.0), (10.0, 20.0))
+        y_range = (state.bounding_box_3d.lower[1], state.bounding_box_3d.upper[1])
+
+        hover.current_axis = "coronal"
+        z_low = state.bounding_box_3d.lower[2]
+        drag(handler, (0.0, z_low), (0.0, z_low - 5.0))  # bottom edge
+
+        box = state.bounding_box_3d
+        assert (box.lower[1], box.upper[1]) == y_range
+        assert box.lower[2] == pytest.approx(z_low - 5.0)
+
     def test_click_outside_clears_the_box(self, setup) -> None:
         state, handler, _ = setup
         drag(handler, (-10.0, -10.0), (10.0, 20.0))

{tk_rt_viewer-2.3.0 → tk_rt_viewer-2.3.1}/tests/test_geometry.py

@@ -14,6 +14,7 @@ import SimpleITK as sitk
 from tk_rt_viewer.geometry import (
     AXES,
     compute_extent,
+    fit_box_length,
     mask_slice_to_paths,
     slice_along_axis,
 )
@@ -123,3 +124,19 @@ class TestSliceAlongAxis:
         np.testing.assert_array_equal(
             slice_along_axis(arr, "sagittal", 3), arr[:, :, 3]
         )
+
+
+class TestFitBoxLength:
+    @staticmethod
+    def _image(slices: int) -> sitk.Image:
+        image = sitk.GetImageFromArray(np.zeros((slices, 4, 4), dtype=np.int16))
+        image.SetSpacing((1.0, 1.0, 2.0))
+        return image
+
+    def test_keeps_the_length_on_a_wide_image(self) -> None:
+        # 30 slices x 2 mm = 60 mm: not narrower than the threshold
+        assert fit_box_length(self._image(30), 2, 50.0, 60.0) == 50.0
+
+    def test_uses_half_the_extent_on_a_narrow_image(self) -> None:
+        # 20 slices x 2 mm = 40 mm
+        assert fit_box_length(self._image(20), 2, 50.0, 60.0) == 40.0 / 2

tk_rt_viewer-2.3.0/src/tk_rt_viewer/event_controllers/bbox3d_handler.py

@@ -1,59 +0,0 @@
-"""bbox3d_handler.py — Volumetric (3-D) bounding box drag handler.
-
-The box is a single :class:`~tk_rt_viewer.geometry.Box3D` in
-:class:`~tk_rt_viewer.state.viewer_state.SliceViewerState`; every view shows
-its projection and the viewer renders it through the
-``"bounding_box_3d_changed"`` listener.
-
-A gesture on any view edits that one box and only the two dimensions the view
-displays; the perpendicular dimension is set from a view that shows it. A new
-box drawn on a view keeps the depth of the box it replaces, or spans the whole
-image when there was none.
-"""
-
-from typing import TYPE_CHECKING
-
-from ..geometry import Box3D
-from ..protocols import ViewerHost
-from .rect_drag import Rect, RectDragHandler
-
-if TYPE_CHECKING:
-    from ..state.viewer_state import SliceViewerState
-    from .viewer_events import ViewerEventHandler
-
-
-class Bbox3dEventHandler(RectDragHandler):
-    """Create / move / resize the 3-D bounding box from any view."""
-
-    def __init__(
-        self,
-        state: "SliceViewerState",
-        viewer: ViewerHost,
-        hover: "ViewerEventHandler",
-    ) -> None:
-        super().__init__(state, viewer, hover)
-        # The box cleared by a create press; its depth is reused for the new one
-        self._previous_box: Box3D | None = None
-
-    def cancel(self) -> None:
-        super().cancel()
-        self._previous_box = None
-
-    def _is_enabled(self) -> bool:
-        return self.state.bbox_3d_visible and self.state.primary_image is not None
-
-    def _current_rect(self, axis: str) -> Rect | None:
-        box = self.state.bounding_box_3d
-        return None if box is None else box.project(axis)
-
-    def _clear(self, axis: str) -> None:
-        self._previous_box = self.state.bounding_box_3d
-        self.state.set_bounding_box_3d(None)
-
-    def _commit(self, axis: str, rect: Rect, mode: str) -> None:
-        image = self.state.primary_image
-        if mode == "create" and image is not None:
-            base = self._previous_box or Box3D.from_image_extent(image)
-            self.state.set_bounding_box_3d(base.with_view_rect(axis, rect))
-        else:
-            self.state.set_bbox_3d_from_view(axis, rect)