add rectangle class (#1815)

Co-authored-by: eir17846 <victor.rogalev@diamond.ac.uk>

Author: Villtord

src/dodal/common/__init__.py

@@ -1,6 +1,6 @@
 from .coordination import group_uuid, inject
 from .enums import EnabledDisabledUpper, InOutUpper, OnOffUpper
-from .maths import in_micros, step_to_num
+from .maths import Rectangle2D, in_micros, step_to_num
 from .types import MsgGenerator, PlanGenerator
 
 __all__ = [
@@ -13,4 +13,5 @@
     "MsgGenerator",
     "PlanGenerator",
     "step_to_num",
+    "Rectangle2D",
 ]

src/dodal/common/maths.py

@@ -48,3 +48,83 @@ def in_micros(t: float) -> int:
     if t < 0:
         raise ValueError(f"Expected a positive time in seconds, got {t!r}")
     return int(np.ceil(t * 1e6))
+
+
+class Rectangle2D:
+    """
+    A 2D rectangle defined by two opposite corners.
+
+    This class represents a rectangle in 2D space using two points: (x1, y1) and (x2, y2).
+    It provides methods to query rectangle properties and check point containment.
+
+    Attributes:
+        x1 (float): The x-coordinate of the first corner.
+        y1 (float): The y-coordinate of the first corner.
+        x2 (float): The x-coordinate of the second corner.
+        y2 (float): The y-coordinate of the second corner.
+    """
+
+    def __init__(self, x1: float, y1: float, x2: float, y2: float):
+        """
+        Initialize a Rectangle2D with two corner points.
+
+        Args:
+            x1 (float): The x-coordinate of the first corner.
+            y1 (float): The y-coordinate of the first corner.
+            x2 (float): The x-coordinate of the second corner.
+            y2 (float): The y-coordinate of the second corner.
+        """
+        self.x1, self.y1 = x1, y1
+        self.x2, self.y2 = x2, y2
+
+    def get_max_x(self) -> float:
+        """
+        Get the maximum x-coordinate of the rectangle.
+
+        Returns:
+            float: The larger of the two x-coordinates (x1, x2).
+        """
+        return max(self.x1, self.x2)
+
+    def get_min_x(self) -> float:
+        """
+        Get the minimum x-coordinate of the rectangle.
+
+        Returns:
+            float: The smaller of the two x-coordinates (x1, x2).
+        """
+        return min(self.x1, self.x2)
+
+    def get_max_y(self) -> float:
+        """
+        Get the maximum y-coordinate of the rectangle.
+
+        Returns:
+            float: The larger of the two y-coordinates (y1, y2).
+        """
+        return max(self.y1, self.y2)
+
+    def get_min_y(self) -> float:
+        """
+        Get the minimum y-coordinate of the rectangle.
+
+        Returns:
+            float: The smaller of the two y-coordinates (y1, y2).
+        """
+        return min(self.y1, self.y2)
+
+    def contains(self, x: float, y: float) -> bool:
+        """
+        Check if a point is contained within the rectangle.
+
+        Args:
+            x (float): The x-coordinate of the point.
+            y (float): The y-coordinate of the point.
+
+        Returns:
+            bool: True if the point is within the rectangle bounds, False otherwise.
+        """
+        return (
+            self.get_min_x() <= x <= self.get_max_x()
+            and self.get_min_y() <= y <= self.get_max_y()
+        )

tests/common/test_maths.py

@@ -1,6 +1,7 @@
 import pytest
 
 from dodal.common import in_micros, step_to_num
+from dodal.common.maths import Rectangle2D
 
 
 @pytest.mark.parametrize(
@@ -61,3 +62,49 @@ def test_step_to_num(
     assert actual_start == start
     assert actual_stop == truncated_stop
     assert num == expected_num
+
+
+@pytest.mark.parametrize(
+    "x_1,y_1,x_2,y_2, inside, outside",
+    [
+        (0, 0, 10.0, 10.0, (5, 5), (15, 15)),
+        (10, 10, 0.0, 0.0, (5, 5), (15, 15)),
+        (-20, 0.0, 20, 10.0, (0, 5), (25, 15)),
+        (-20, 10.0, 20, 0.0, (0, 5), (25, 15)),
+    ],
+)
+def test_rectangle_contains(
+    x_1: float,
+    y_1: float,
+    x_2: float,
+    y_2: float,
+    inside: tuple[float, float],
+    outside: tuple[float, float],
+):
+    rect = Rectangle2D(x_1, y_1, x_2, y_2)
+    assert rect.contains(*inside)
+    assert not rect.contains(*outside)
+
+
+@pytest.mark.parametrize(
+    "x_1,y_1,x_2,y_2, max_x, max_y, min_x, min_y",
+    [
+        (0, 0, 10.0, 10.0, 10.0, 10.0, 0.0, 0.0),
+        (-20, 0.0, 20, 10.0, 20.0, 10.0, -20.0, 0.0),
+    ],
+)
+def test_rectangle_min_max(
+    x_1: float,
+    y_1: float,
+    x_2: float,
+    y_2: float,
+    max_x: float,
+    max_y: float,
+    min_x: float,
+    min_y: float,
+):
+    rect = Rectangle2D(x_1, y_1, x_2, y_2)
+    assert rect.get_max_x() == max_x
+    assert rect.get_max_y() == max_y
+    assert rect.get_min_x() == min_x
+    assert rect.get_min_y() == min_y