Merge branch 'feature/preciseflex-nest-type-discovery' into dev-precise-flex-pf400

Author: miikee

pylabrobot/arms/arm.py

@@ -1,6 +1,6 @@
-from typing import Union
+from typing import Optional, Union
 
-from pylabrobot.arms.backend import ArmBackend
+from pylabrobot.arms.backend import AccessPattern, ArmBackend
 from pylabrobot.arms.coords import CartesianCoords, JointCoords
 from pylabrobot.machines.machine import Machine
 
@@ -56,16 +56,44 @@ async def move_to_safe(self):
     """Move the arm to a predefined safe position."""
     return await self.backend.move_to_safe()
 
-  async def approach(self, position: Union[CartesianCoords, JointCoords], approach_height: float):
-    """Move the arm to a position above the specified coordinates by a certain distance."""
-    return await self.backend.approach(position, approach_height)
+  async def approach(
+    self,
+    position: Union[CartesianCoords, JointCoords],
+    access: Optional[AccessPattern] = None
+  ):
+    """Move the arm to an approach position (offset from target).
+
+    Args:
+      position: Target position (CartesianCoords or JointCoords)
+      access: Access pattern defining how to approach the target.
+              Defaults to VerticalAccess() if not specified.
+    """
+    return await self.backend.approach(position, access)
+
+  async def pick_plate(
+    self,
+    position: Union[CartesianCoords, JointCoords],
+    access: Optional[AccessPattern] = None
+  ):
+    """Pick a plate from the specified position.
 
-  async def pick_plate(self, position: Union[CartesianCoords, JointCoords], approach_height: float):
-    """Pick a plate from the specified position."""
-    return await self.backend.pick_plate(position, approach_height)
+    Args:
+      position: Target position for pickup
+      access: Access pattern defining how to approach and retract.
+              Defaults to VerticalAccess() if not specified.
+    """
+    return await self.backend.pick_plate(position, access)
 
   async def place_plate(
-    self, position: Union[CartesianCoords, JointCoords], approach_height: float
+    self,
+    position: Union[CartesianCoords, JointCoords],
+    access: Optional[AccessPattern] = None
   ):
-    """Place a plate at the specified position."""
-    return await self.backend.place_plate(position, approach_height)
+    """Place a plate at the specified position.
+
+    Args:
+      position: Target position for placement
+      access: Access pattern defining how to approach and retract.
+              Defaults to VerticalAccess() if not specified.
+    """
+    return await self.backend.place_plate(position, access)

pylabrobot/arms/backend.py

@@ -1,10 +1,57 @@
 from abc import ABCMeta, abstractmethod
-from typing import Union
+from dataclasses import dataclass
+from typing import Optional, Union
 
 from pylabrobot.arms.coords import CartesianCoords, JointCoords
 from pylabrobot.machines.backend import MachineBackend
 
 
+@dataclass
+class VerticalAccess:
+  """Access location from above (most common pattern for stacks and tube racks).
+
+  This access pattern is used when approaching a location from above, such as
+  picking from a plate stack or tube rack on the deck.
+
+  Args:
+    approach_height_mm: Height above the target position to move to before
+                        descending to grip (default: 100mm)
+    clearance_mm: Vertical distance to retract after gripping before lateral
+                  movement (default: 100mm)
+    gripper_offset_mm: Additional vertical offset added when holding a plate,
+                      accounts for gripper thickness (default: 10mm)
+  """
+  approach_height_mm: float = 100
+  clearance_mm: float = 100
+  gripper_offset_mm: float = 10
+
+
+@dataclass
+class HorizontalAccess:
+  """Access location from the side (for hotel-style plate carriers).
+
+  This access pattern is used when approaching a location horizontally, such as
+  accessing plates in a hotel-style storage system.
+
+  Args:
+    approach_distance_mm: Horizontal distance in front of the target to stop
+                         before moving in to grip (default: 50mm)
+    clearance_mm: Horizontal distance to retract after gripping before lifting
+                  (default: 50mm)
+    lift_height_mm: Vertical distance to lift the plate after horizontal retract,
+                   before lateral movement (default: 100mm)
+    gripper_offset_mm: Additional vertical offset added when holding a plate,
+                      accounts for gripper thickness (default: 10mm)
+  """
+  approach_distance_mm: float = 50
+  clearance_mm: float = 50
+  lift_height_mm: float = 100
+  gripper_offset_mm: float = 10
+
+
+AccessPattern = Union[VerticalAccess, HorizontalAccess]
+
+
 class ArmBackend(MachineBackend, metaclass=ABCMeta):
   """Backend for a robotic arm"""
 
@@ -49,20 +96,48 @@ async def move_to_safe(self):
     ...
 
   @abstractmethod
-  async def approach(self, position: Union[CartesianCoords, JointCoords], approach_height: float):
-    """Move the arm to a position above the specified coordinates by a certain distance."""
+  async def approach(
+    self,
+    position: Union[CartesianCoords, JointCoords],
+    access: Optional[AccessPattern] = None
+  ):
+    """Move the arm to an approach position (offset from target).
+
+    Args:
+      position: Target position (CartesianCoords or JointCoords)
+      access: Access pattern defining how to approach the target.
+              Defaults to VerticalAccess() if not specified.
+    """
     ...
 
   @abstractmethod
-  async def pick_plate(self, position: Union[CartesianCoords, JointCoords], approach_height: float):
-    """Pick a plate from the specified position."""
+  async def pick_plate(
+    self,
+    position: Union[CartesianCoords, JointCoords],
+    access: Optional[AccessPattern] = None
+  ):
+    """Pick a plate from the specified position.
+
+    Args:
+      position: Target position for pickup
+      access: Access pattern defining how to approach and retract.
+              Defaults to VerticalAccess() if not specified.
+    """
     ...
 
   @abstractmethod
   async def place_plate(
-    self, position: Union[CartesianCoords, JointCoords], approach_height: float
+    self,
+    position: Union[CartesianCoords, JointCoords],
+    access: Optional[AccessPattern] = None
   ):
-    """Place a plate at the specified position."""
+    """Place a plate at the specified position.
+
+    Args:
+      position: Target position for placement
+      access: Access pattern defining how to approach and retract.
+              Defaults to VerticalAccess() if not specified.
+    """
     ...
 
   @abstractmethod