Make code more modular, update tests and docs to reflect the change

Author: shoumikchow

.github/workflows/black.yml

@@ -1,4 +1,4 @@
-name: Format
+name: Black
 
 on: [push, pull_request]
 
@@ -13,25 +13,25 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          
+
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.x'
-          
+          python-version: "3.x"
+
       - name: Install Black
         run: pip install black
-        
+
       - name: Run Black
         id: black
         continue-on-error: true
         run: |
-          black --check bbox_visualizer/bbox_visualizer.py tests/test_bbox_visualizer.py
+          black --check bbox_visualizer tests
           echo "has_changes=$?" >> $GITHUB_OUTPUT
 
       - name: Format with Black if needed
         if: steps.black.outputs.has_changes == '1'
-        run: black bbox_visualizer/bbox_visualizer.py tests/test_bbox_visualizer.py
+        run: black bbox_visualizer tests
 
       - name: Create Pull Request
         if: steps.black.outputs.has_changes == '1'

bbox_visualizer/__init__.py

@@ -1,17 +1,28 @@
-"""Top-level package for bbox-visualizer."""
+"""bbox-visualizer - Different ways of visualizing objects given bounding box data."""
 
 from ._version import __version__
+from .core import (
+    draw_rectangle,
+    draw_multiple_rectangles,
+    add_label,
+    add_multiple_labels,
+    add_T_label,
+    add_multiple_T_labels,
+    draw_flag_with_label,
+    draw_multiple_flags_with_labels,
+)
 
-__author__ = """Shoumik Sharar Chowdhury"""
-__email__ = 'shoumikchow@gmail.com'
+__all__ = [
+    "__version__",
+    "draw_rectangle",
+    "draw_multiple_rectangles",
+    "add_label",
+    "add_multiple_labels",
+    "add_T_label",
+    "add_multiple_T_labels",
+    "draw_flag_with_label",
+    "draw_multiple_flags_with_labels",
+]
 
-from .bbox_visualizer import (
-    draw_rectangle, 
-    add_label, 
-    add_T_label, 
-    draw_flag_with_label, 
-    add_multiple_labels, 
-    add_multiple_T_labels, 
-    draw_multiple_rectangles, 
-    draw_multiple_flags_with_labels
-    )
+__author__ = """Shoumik Sharar Chowdhury"""
+__email__ = "shoumikchow@gmail.com"

bbox_visualizer/_version.py

@@ -1,3 +1,3 @@
 """Version information."""
 
-__version__ = "0.2.0" 
+__version__ = "0.2.0"

bbox_visualizer/core/__init__.py

@@ -0,0 +1,21 @@
+"""Core functionality for bbox-visualizer."""
+
+from .rectangle import draw_rectangle, draw_multiple_rectangles
+from .labels import add_label, add_multiple_labels
+from .flags import (
+    add_T_label,
+    add_multiple_T_labels,
+    draw_flag_with_label,
+    draw_multiple_flags_with_labels,
+)
+
+__all__ = [
+    "draw_rectangle",
+    "draw_multiple_rectangles",
+    "add_label",
+    "add_multiple_labels",
+    "add_T_label",
+    "add_multiple_T_labels",
+    "draw_flag_with_label",
+    "draw_multiple_flags_with_labels",
+]

bbox_visualizer/core/_utils.py

@@ -0,0 +1,63 @@
+"""Internal utilities for bbox-visualizer."""
+
+from typing import List, Tuple
+
+
+def validate_bbox(bbox: List[int]) -> None:
+    """Validate bounding box format and values.
+
+    Args:
+        bbox: List of [x_min, y_min, x_max, y_max] coordinates
+
+    Raises:
+        ValueError: If bbox is empty, has wrong length, or has invalid coordinates
+    """
+    if not bbox:
+        raise ValueError("Bounding box cannot be empty")
+    if len(bbox) != 4:
+        raise ValueError(
+            "Bounding box must have exactly 4 coordinates [x_min, y_min, x_max, y_max]"
+        )
+    if bbox[0] > bbox[2] or bbox[1] > bbox[3]:
+        raise ValueError(
+            "Invalid bounding box coordinates: x_min > x_max or y_min > y_max"
+        )
+
+
+def validate_color(color: Tuple[int, int, int]) -> None:
+    """Validate BGR color values.
+
+    Args:
+        color: BGR color tuple (blue, green, red)
+
+    Raises:
+        ValueError: If any color component is outside [0, 255]
+    """
+    if not all(0 <= c <= 255 for c in color):
+        raise ValueError("Color values must be between 0 and 255")
+
+
+def _check_and_modify_bbox(
+    bbox: List[int], img_size: Tuple[int, int, int], margin: int = 0
+) -> List[int]:
+    """Internal function to check and adjust bounding box coordinates.
+
+    .. private::
+
+    Trimming rules:
+        - xmin/ymin: Set to margin if negative
+        - xmax/ymax: Set to image width/height - margin if exceeds image size
+
+    Args:
+        bbox: List of [x_min, y_min, x_max, y_max] coordinates
+        img_size: Tuple of (height, width, channels)
+        margin: Minimum distance from image edges (default: 0)
+
+    Returns:
+        Adjusted bounding box coordinates [x_min, y_min, x_max, y_max]
+    """
+    validate_bbox(bbox)
+    bbox = [value if value > 0 else margin for value in bbox]
+    bbox[2] = bbox[2] if bbox[2] < img_size[1] else img_size[1] - margin
+    bbox[3] = bbox[3] if bbox[3] < img_size[0] else img_size[0] - margin
+    return bbox