get_anchor (#147)

* get_anchor

* type

Author: rickwierenga

pylabrobot/resources/resource.py

@@ -119,13 +119,79 @@ def __repr__(self) -> str:
   def __hash__(self) -> int:
     return hash(repr(self))
 
-  def get_absolute_location(self) -> Coordinate:
+  def get_anchor(self, x: str, y: str, z: str) -> Coordinate:
+    """ Get a relative location within the resource.
+
+    Args:
+      x: `"l"`/`"left"`, `"c"`/`"center"`, or `"r"`/`"right"`
+      y: `"b"`/`"back"`, `"c"`/`"center"`, or `"f"`/`"front"`
+      z: `"t"`/`"top"`, `"c"`/`"center"`, or `"b"`/`"bottom"`
+
+    Returns:
+      A relative location within the resource, the anchor point wrt the left front bottom corner.
+
+    Examples:
+      >>> r = Resource("resource", size_x=12, size_y=12, size_z=12)
+      >>> r.get_anchor("l", "b", "t")
+
+      Coordinate(x=0.0, y=12.0, z=12.0)
+
+      >>> r.get_anchor("c", "c", "c")
+
+      Coordinate(x=6.0, y=6.0, z=6.0)
+
+      >>> r.get_anchor("r", "f", "b")
+
+      Coordinate(x=12.0, y=0.0, z=0.0)
+    """
+
+    x_: float
+    if x.lower() in {"l", "left"}:
+      x_ = 0
+    elif x.lower() in {"c", "center"}:
+      x_ = self.get_size_x() / 2
+    elif x.lower() in {"r", "right"}:
+      x_ = self.get_size_x()
+    else:
+      raise ValueError(f"Invalid x value: {x}")
+
+    y_: float
+    if y.lower() in {"b", "back"}:
+      y_ = self.get_size_y()
+    elif y.lower() in {"c", "center"}:
+      y_ = self.get_size_y() / 2
+    elif y.lower() in {"f", "front"}:
+      y_ = 0
+    else:
+      raise ValueError(f"Invalid y value: {y}")
+
+    z_: float
+    if z.lower() in {"t", "top"}:
+      z_ = self.get_size_z()
+    elif z.lower() in {"c", "center"}:
+      z_ = self.get_size_z() / 2
+    elif z.lower() in {"b", "bottom"}:
+      z_ = 0
+    else:
+      raise ValueError(f"Invalid z value: {z}")
+
+    return Coordinate(x_, y_, z_)
+
+  def get_absolute_location(self, x: str = "l", y: str = "f", z: str = "b") -> Coordinate:
     """ Get the absolute location of this resource, probably within the
-    :class:`pylabrobot.resources.Deck`. """
+    :class:`pylabrobot.resources.Deck`. The `x`, `y`, and `z` arguments specify the anchor point
+    within the resource. The default is the left front bottom corner.
+
+    Args:
+      x: `"l"`/`"left"`, `"c"`/`"center"`, or `"r"`/`"right"`
+      y: `"b"`/`"back"`, `"c"`/`"center"`, or `"f"`/`"front"`
+      z: `"t"`/`"top"`, `"c"`/`"center"`, or `"b"`/`"bottom"`
+    """
+
     assert self.location is not None, "Resource has no location."
     if self.parent is None:
       return self.location
-    return self.parent.get_absolute_location() + self.location
+    return self.parent.get_absolute_location() + self.location + self.get_anchor(x=x, y=y, z=z)
 
   def get_size_x(self) -> float:
     if self.rotation in {90, 270}:

pylabrobot/resources/resource_tests.py

@@ -62,6 +62,16 @@ def test_assign_name_taken(self):
       other_child = Resource("child", size_x=5, size_y=5, size_z=5)
       deck.assign_child_resource(other_child, location=Coordinate(5, 5, 5))
 
+  def test_get_anchor(self):
+    resource = Resource("test", size_x=12, size_y=12, size_z=12)
+    self.assertEqual(resource.get_anchor(x="left", y="back", z="bottom"), Coordinate(0, 12, 0))
+    self.assertEqual(resource.get_anchor(x="right", y="front", z="top"), Coordinate(12, 0, 12))
+    self.assertEqual(resource.get_anchor(x="center", y="center", z="center"), Coordinate(6, 6, 6))
+
+    self.assertEqual(resource.get_anchor(x="l", y="b", z="b"), Coordinate(0, 12, 0))
+    self.assertEqual(resource.get_anchor(x="r", y="f", z="t"), Coordinate(12, 0, 12))
+    self.assertEqual(resource.get_anchor(x="c", y="c", z="c"), Coordinate(6, 6, 6))
+
   def test_absolute_location(self):
     deck = Deck()
     parent = Resource("parent", size_x=10, size_y=10, size_z=10)
@@ -72,6 +82,18 @@ def test_absolute_location(self):
     self.assertEqual(deck.get_resource("parent").get_absolute_location(), Coordinate(10, 10, 10))
     self.assertEqual(deck.get_resource("child").get_absolute_location(), Coordinate(15, 15, 15))
 
+  def test_get_absolute_location_with_anchor(self):
+    deck = Deck()
+    parent = Resource("parent", size_x=10, size_y=10, size_z=10)
+    deck.assign_child_resource(parent, location=Coordinate(10, 10, 10))
+    child = Resource("child", size_x=5, size_y=5, size_z=5)
+    parent.assign_child_resource(child, location=Coordinate(5, 5, 5))
+
+    self.assertEqual(deck.get_resource("parent")\
+                     .get_absolute_location(x="right", y="front", z="top"), Coordinate(20, 10, 20))
+    self.assertEqual(deck.get_resource("child")\
+                     .get_absolute_location(x="right", y="front", z="top"), Coordinate(20, 15, 20))
+
   def test_unassign_child(self):
     deck = Deck()
     parent = Resource("parent", size_x=10, size_y=10, size_z=10)