docs: Enhance RegionBox with flexible padding options and module upda…

…tes (#215)

Introduce the BoxPadMethod enum for padding flexibility in RegionBox.
Update import paths and remove deprecated modules to streamline the
codebase.

docs/usage/.pages

@@ -1,3 +1,4 @@
 nav:
   - Home: index.md
+  - Core Types: CoreTypes
   - ...

docs/usage/CoreTypes/index.md

@@ -0,0 +1 @@
+# Bounding Box

mkdocs.yml

@@ -57,6 +57,10 @@ plugins:
   - search                            # necessary for search functionality to work
   - git-authors                       # adds authors to pages using git history
   - include-markdown                  # allows for including Markdown files into another Markdown file
+  - mkdocs-jupyter:
+      allow_errors: false
+      theme: dark
+      include_source: true
   - mkdocstrings:
       handlers:
         python:

pixi.toml

@@ -90,6 +90,7 @@ mike = ">=2.1.2,<3"
 mkdocs-include-markdown-plugin = ">=7.1.1,<8"
 mkdocs-click = ">=0.6.0,<0.7"
 black = ">=24.10.0,<25"
+mkdocs-jupyter = ">=0.25.1,<0.26"
 
 [feature.docs.pypi-dependencies]
 mkdocs-awesome-pages-plugin = ">=2.9.3, <3"

src/imgtools/__init__.py

@@ -1,6 +1,6 @@
 __version__ = "1.21.0"
 
-from .coretypes import Coordinate3D, Size3D, Spacing3D
+from .coretypes import BoxPadMethod, Coordinate3D, RegionBox, Size3D, Spacing3D
 from .datasets import example_data, example_data_paths
 from .dicom import find_dicoms, lookup_tag, similar_tags, tag_exists
 from .logging import logger
@@ -12,10 +12,12 @@
     "tag_exists",
     "logger",
     ## coretypes
+    "BoxPadMethod",
+    "RegionBox",
     "Coordinate3D",
     "Size3D",
     "Spacing3D",
     ## example data
     "example_data",
     "example_data_paths",
- ]
+]

src/imgtools/coretypes/__init__.py

@@ -1,3 +1,4 @@
-from .helper_types import Coordinate3D, Size3D, Spacing3D
+from .box import BoxPadMethod, RegionBox
+from .spatial_types import Coordinate3D, Size3D, Spacing3D
 
-__all__ = ["Coordinate3D", "Size3D", "Spacing3D"]
+__all__ = ["Coordinate3D", "Size3D", "Spacing3D", "RegionBox", "BoxPadMethod"]

src/imgtools/coretypes/box.py

@@ -1,12 +1,13 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
+from enum import Enum
 
 import SimpleITK as sitk
 
 from imgtools.logging import logger
 
-from .helper_types import Coordinate3D, Size3D
+from .spatial_types import Coordinate3D, Size3D
 
 
 # Exception for when the bounding box is outside the image
@@ -61,6 +62,13 @@ def calculate_image_boundaries(
     return RegionBox(min_coord, min_coord + size)
 
 
+class BoxPadMethod(str, Enum):
+    """Enum for padding methods."""
+
+    SYMMETRIC = "symmetric"
+    END = "end"
+
+
 @dataclass
 class RegionBox:
     """Represents a box in 3D space.
@@ -154,24 +162,63 @@ def from_mask_bbox(cls, mask: sitk.Image, label: int = 1) -> RegionBox:
             Coordinate3D(xstart + xsize, ystart + ysize, zstart + zsize),
         )
 
-    def pad(self, padding: int) -> RegionBox:
-        """Expand the bounding box by a specified padding value in all directions.
+    def pad(
+        self, padding: int, method: BoxPadMethod = BoxPadMethod.SYMMETRIC
+    ) -> RegionBox:
+        """Expand the bounding box by a specified padding value.
+
+        Can be applied symmetrically on both sides or only at the end of the box.
+        If the padded result has negative coordinates, they region is adjusted by
+        shifting the min coordinates to 0 and adding the difference to the max coordinates.
 
         Parameters
         ----------
         padding : int
             The padding value to expand the bounding box.
+        method : BoxPadMethod, optional
+            The padding method to use. Default is BoxPadMethod.SYMMETRIC.
+            Options are:
+            - BoxPadMethod.SYMMETRIC: Pad symmetrically on both sides.
+            - BoxPadMethod.END: Pad only at the end of the box (furthest from the origin).
 
         Returns
         -------
         RegionBox
             The expanded bounding box.
+
+        Examples
+        --------
+        >>> box = RegionBox(
+        ...     Coordinate3D(5, 5, 5),
+        ...     Coordinate3D(10, 10, 10),
+        ... )
+        >>> box.pad(5)
+        RegionBox(
+        ... min=Coordinate3D(x=0, y=0, z=0),
+        ... max=Coordinate3D(x=15, y=15, z=15)
+        ... size=(15, 15, 15)
+        )
+        >>> box.pad(5, method=BoxPadMethod.END)
+        RegionBox(
+        ... min=Coordinate3D(x=5, y=5, z=5),
+        ... max=Coordinate3D(x=15, y=15, z=15)
+        ... size=(10, 10, 10)
+        )
         """
         if padding == 0:
             return self
 
-        padded_min = self.min - padding
-        padded_max = self.max + padding
+        match method:
+            case BoxPadMethod.SYMMETRIC:
+                padded_min = self.min - padding
+                padded_max = self.max + padding
+            case BoxPadMethod.END:
+                padded_min = self.min
+                padded_max = self.max + padding
+            case _:
+                errmsg = f"Invalid padding method: {method}"
+                errmsg += f" Options are: {BoxPadMethod.__members__.keys()}"
+                raise ValueError(errmsg)
 
         self._adjust_negative_coordinates(padded_min, padded_max)