feat(api, shared-data): add location-based gripper offsets to final labware movement offsets

api/src/opentrons/motion_planning/waypoints.py

@@ -128,8 +128,8 @@ def get_gripper_labware_movement_waypoints(
     offset_data: LabwareMovementOffsetData,
 ) -> List[GripperMovementWaypointsWithJawStatus]:
     """Get waypoints for moving labware using a gripper."""
-    pick_up_offset = offset_data.pick_up_offset
-    drop_offset = offset_data.drop_offset
+    pick_up_offset = offset_data.pickUpOffset
+    drop_offset = offset_data.dropOffset
 
     pick_up_location = from_labware_center + Point(
         pick_up_offset.x, pick_up_offset.y, pick_up_offset.z

api/src/opentrons/protocol_engine/commands/move_labware.py

@@ -136,9 +136,8 @@ async def execute(self, params: MoveLabwareParams) -> MoveLabwareResult:
                 available_new_location,
             )
             user_offset_data = LabwareMovementOffsetData(
-                pick_up_offset=params.pickUpOffset
-                or LabwareOffsetVector(x=0, y=0, z=0),
-                drop_offset=params.dropOffset or LabwareOffsetVector(x=0, y=0, z=0),
+                pickUpOffset=params.pickUpOffset or LabwareOffsetVector(x=0, y=0, z=0),
+                dropOffset=params.dropOffset or LabwareOffsetVector(x=0, y=0, z=0),
             )
             # Skips gripper moves when using virtual gripper
             await self._labware_movement.move_labware_with_gripper(

api/src/opentrons/protocol_engine/execution/labware_movement.py

@@ -1,7 +1,7 @@
 """Labware movement command handling."""
 from __future__ import annotations
 
-from typing import Optional, Union, TYPE_CHECKING
+from typing import Optional, TYPE_CHECKING
 from opentrons_shared_data.gripper.constants import (
     LABWARE_GRIP_FORCE,
     IDLE_STATE_GRIP_FORCE,
@@ -26,11 +26,10 @@
 )
 
 from ..types import (
-    DeckSlotLocation,
-    ModuleLocation,
     OnLabwareLocation,
     LabwareLocation,
     LabwareMovementOffsetData,
+    OnDeckLabwareLocation,
 )
 
 if TYPE_CHECKING:
@@ -84,8 +83,8 @@ def __init__(
     async def move_labware_with_gripper(
         self,
         labware_id: str,
-        current_location: Union[DeckSlotLocation, ModuleLocation, OnLabwareLocation],
-        new_location: Union[DeckSlotLocation, ModuleLocation, OnLabwareLocation],
+        current_location: OnDeckLabwareLocation,
+        new_location: OnDeckLabwareLocation,
         user_offset_data: LabwareMovementOffsetData,
     ) -> None:
         """Move a loaded labware from one location to another using gripper."""

api/src/opentrons/protocol_engine/state/geometry.py

@@ -6,7 +6,6 @@
 from opentrons_shared_data.labware.constants import WELL_NAME_PATTERN
 
 from .. import errors
-from ..errors import LabwareMovementNotAllowedError
 from ..types import (
     OFF_DECK_LOCATION,
     LoadedLabware,
@@ -26,7 +25,7 @@
     CurrentWell,
     TipGeometry,
     LabwareMovementOffsetData,
-    ModuleModel,
+    OnDeckLabwareLocation,
 )
 from .config import Config
 from .labware import LabwareView
@@ -38,7 +37,6 @@
 
 
 SLOT_WIDTH = 128
-_ADDITIONAL_TC2_PICKUP_OFFSET = 3.5
 
 
 class _TipDropSection(enum.Enum):
@@ -48,6 +46,13 @@ class _TipDropSection(enum.Enum):
     RIGHT = "right"
 
 
+class _GripperMoveType(enum.Enum):
+    """Types of gripper movement."""
+
+    PICK_UP_LABWARE = enum.auto()
+    DROP_LABWARE = enum.auto()
+
+
 # TODO(mc, 2021-06-03): continue evaluation of which selectors should go here
 # vs which selectors should be in LabwareView
 class GeometryView:
@@ -623,27 +628,26 @@ def _get_drop_tip_well_x_offset(
 
     def get_final_labware_movement_offset_vectors(
         self,
-        from_location: LabwareLocation,
-        to_location: LabwareLocation,
+        from_location: OnDeckLabwareLocation,
+        to_location: OnDeckLabwareLocation,
         additional_offset_vector: LabwareMovementOffsetData,
     ) -> LabwareMovementOffsetData:
         """Calculate the final labware offset vector to use in labware movement."""
-        # TODO (fps, 2022-05-30): Update this once RLAB-295 is merged
-        #  Get location-based offsets from deck/module/adapter definitions,
-        #  then add additional offsets
-        pick_up_offset = additional_offset_vector.pick_up_offset
-        drop_offset = additional_offset_vector.drop_offset
-
-        if isinstance(from_location, ModuleLocation):
-            module_id = from_location.moduleId
-            if (
-                self._modules.get_connected_model(module_id)
-                == ModuleModel.THERMOCYCLER_MODULE_V2
-            ):
-                pick_up_offset.z += _ADDITIONAL_TC2_PICKUP_OFFSET
+        pick_up_offset = (
+            self.get_total_nominal_gripper_offset_for_move_type(
+                location=from_location, move_type=_GripperMoveType.PICK_UP_LABWARE
+            )
+            + additional_offset_vector.pickUpOffset
+        )
+        drop_offset = (
+            self.get_total_nominal_gripper_offset_for_move_type(
+                location=to_location, move_type=_GripperMoveType.DROP_LABWARE
+            )
+            + additional_offset_vector.dropOffset
+        )
 
         return LabwareMovementOffsetData(
-            pick_up_offset=pick_up_offset, drop_offset=drop_offset
+            pickUpOffset=pick_up_offset, dropOffset=drop_offset
         )
 
     @staticmethod
@@ -654,7 +658,98 @@ def ensure_valid_gripper_location(
         if not isinstance(
             location, (DeckSlotLocation, ModuleLocation, OnLabwareLocation)
         ):
-            raise LabwareMovementNotAllowedError(
+            raise errors.LabwareMovementNotAllowedError(
                 "Off-deck labware movements are not supported using the gripper."
             )
         return location
+
+    def get_total_nominal_gripper_offset_for_move_type(
+        self, location: OnDeckLabwareLocation, move_type: _GripperMoveType
+    ) -> LabwareOffsetVector:
+        """Get the total of the offsets to be used to pick up labware in its current location."""
+        if move_type == _GripperMoveType.PICK_UP_LABWARE:
+            if isinstance(location, (ModuleLocation, DeckSlotLocation)):
+                return self._nominal_gripper_offsets_for_location(location).pickUpOffset
+            else:
+                # If it's a labware on a labware (most likely an adapter),
+                # we calculate the offset as sum of offsets for the direct parent labware
+                # and the underlying non-labware parent location.
+                direct_parent_offset = self._nominal_gripper_offsets_for_location(
+                    location
+                )
+                ancestor = self._labware.get_parent_location(location.labwareId)
+                assert isinstance(
+                    ancestor, (DeckSlotLocation, ModuleLocation)
+                ), "No gripper offsets for off-deck labware"
+                return (
+                    direct_parent_offset.pickUpOffset
+                    + self._nominal_gripper_offsets_for_location(
+                        location=ancestor
+                    ).pickUpOffset
+                )
+        else:
+            if isinstance(location, (ModuleLocation, DeckSlotLocation)):
+                return self._nominal_gripper_offsets_for_location(location).dropOffset
+            else:
+                # If it's a labware on a labware (most likely an adapter),
+                # we calculate the offset as sum of offsets for the direct parent labware
+                # and the underlying non-labware parent location.
+                direct_parent_offset = self._nominal_gripper_offsets_for_location(
+                    location
+                )
+                ancestor = self._labware.get_parent_location(location.labwareId)
+                assert isinstance(
+                    ancestor, (DeckSlotLocation, ModuleLocation)
+                ), "No gripper offsets for off-deck labware"
+                return (
+                    direct_parent_offset.dropOffset
+                    + self._nominal_gripper_offsets_for_location(
+                        location=ancestor
+                    ).dropOffset
+                )
+
+    def _nominal_gripper_offsets_for_location(
+        self, location: OnDeckLabwareLocation
+    ) -> LabwareMovementOffsetData:
+        """Provide the default gripper offset data for the given location type."""
+        if isinstance(location, DeckSlotLocation):
+            offsets = self._labware.get_deck_default_gripper_offsets()
+        elif isinstance(location, ModuleLocation):
+            offsets = self._modules.get_default_gripper_offsets(location.moduleId)
+        else:
+            # Labware is on a labware/adapter
+            offsets = self._labware_gripper_offsets(location.labwareId)
+        return offsets or LabwareMovementOffsetData(
+            pickUpOffset=LabwareOffsetVector(x=0, y=0, z=0),
+            dropOffset=LabwareOffsetVector(x=0, y=0, z=0),
+        )
+
+    def _labware_gripper_offsets(
+        self, labware_id: str
+    ) -> Optional[LabwareMovementOffsetData]:
+        """Provide the most appropriate gripper offset data for the specified labware.
+
+        We check the types of gripper offsets available for the labware ("default" or slot-based)
+        and return the most appropriate one for the overall location of the labware.
+        Currently, only module adapters (specifically, the H/S universal flat adapter)
+        have non-default offsets that are specific to location of the module on deck,
+        so, this code only checks for the presence of those known offsets.
+        """
+        parent_location = self._labware.get_parent_location(labware_id)
+        assert isinstance(
+            parent_location, (DeckSlotLocation, ModuleLocation)
+        ), "No gripper offsets for off-deck labware"
+
+        if isinstance(parent_location, DeckSlotLocation):
+            slot_name = parent_location.slotName
+        else:
+            module_loc = self._modules.get_location(parent_location.moduleId)
+            slot_name = module_loc.slotName
+
+        slot_based_offset = self._labware.get_labware_gripper_offsets(
+            labware_id=labware_id, slot_name=slot_name
+        )
+
+        return slot_based_offset or self._labware.get_labware_gripper_offsets(
+            labware_id=labware_id, slot_name=None
+        )

api/src/opentrons/protocol_engine/state/labware.py

@@ -46,6 +46,7 @@
     ModuleLocation,
     ModuleModel,
     OverlapOffset,
+    LabwareMovementOffsetData,
 )
 from ..actions import (
     Action,
@@ -719,3 +720,46 @@ def _is_magnetic_module_uri_in_half_millimeter(self, labware_id: str) -> bool:
         """Check whether the labware uri needs to be calculated in half a millimeter."""
         uri = self.get_uri_from_definition(self.get_definition(labware_id))
         return uri in _MAGDECK_HALF_MM_LABWARE
+
+    def get_deck_default_gripper_offsets(self) -> Optional[LabwareMovementOffsetData]:
+        """Get the deck's default gripper offsets."""
+        parsed_offsets = (
+            self.get_deck_definition().get("gripperOffsets", {}).get("default")
+        )
+        return (
+            LabwareMovementOffsetData(
+                pickUpOffset=LabwareOffsetVector(
+                    x=parsed_offsets["pickUpOffset"]["x"],
+                    y=parsed_offsets["pickUpOffset"]["y"],
+                    z=parsed_offsets["pickUpOffset"]["z"],
+                ),
+                dropOffset=LabwareOffsetVector(
+                    x=parsed_offsets["dropOffset"]["x"],
+                    y=parsed_offsets["dropOffset"]["y"],
+                    z=parsed_offsets["dropOffset"]["z"],
+                ),
+            )
+            if parsed_offsets
+            else None
+        )
+
+    def get_labware_gripper_offsets(
+        self,
+        labware_id: str,
+        slot_name: Optional[DeckSlotName],
+    ) -> Optional[LabwareMovementOffsetData]:
+        """Get the labware's gripper offsets of the specified type."""
+        parsed_offsets = self.get_definition(labware_id).gripperOffsets
+        offset_key = slot_name.name if slot_name else "default"
+        return (
+            LabwareMovementOffsetData(
+                pickUpOffset=cast(
+                    LabwareOffsetVector, parsed_offsets[offset_key].pickUpOffset
+                ),
+                dropOffset=cast(
+                    LabwareOffsetVector, parsed_offsets[offset_key].dropOffset
+                ),
+            )
+            if parsed_offsets
+            else None
+        )

api/src/opentrons/protocol_engine/state/modules.py

@@ -44,6 +44,7 @@
     HeaterShakerMovementRestrictors,
     ModuleLocation,
     DeckType,
+    LabwareMovementOffsetData,
 )
 from .. import errors
 from ..commands import (
@@ -945,3 +946,10 @@ def raise_if_module_in_location(
                 raise errors.LocationIsOccupiedError(
                     f"Module {module.model} is already present at {location}."
                 )
+
+    def get_default_gripper_offsets(
+        self, module_id: str
+    ) -> Optional[LabwareMovementOffsetData]:
+        """Get the deck's default gripper offsets."""
+        offsets = self.get_definition(module_id).gripperOffsets
+        return offsets.get("default") if offsets else None

api/src/opentrons/protocol_engine/types.py

@@ -80,6 +80,8 @@ class OnLabwareLocation(BaseModel):
 ]
 """Union of all locations where it's legal to keep a labware."""
 
+OnDeckLabwareLocation = Union[DeckSlotLocation, ModuleLocation, OnLabwareLocation]
+
 NonStackedLocation = Union[DeckSlotLocation, ModuleLocation, _OffDeckLocationType]
 """Union of all locations where it's legal to keep a labware that can't be stacked on another labware"""
 
@@ -382,6 +384,13 @@ class OverlapOffset(Vec3f):
     """Offset representing overlap space of one labware on top of another labware or module."""
 
 
+class LabwareMovementOffsetData(BaseModel):
+    """Offsets to be used during labware movement."""
+
+    pickUpOffset: LabwareOffsetVector
+    dropOffset: LabwareOffsetVector
+
+
 # TODO(mm, 2023-04-13): Move to shared-data, so this binding can be maintained alongside the JSON
 # schema that it's sourced from. We already do that for labware definitions and JSON protocols.
 class ModuleDefinition(BaseModel):
@@ -440,6 +449,10 @@ class ModuleDefinition(BaseModel):
         ...,
         description="List of module models this model is compatible with.",
     )
+    gripperOffsets: Optional[Dict[str, LabwareMovementOffsetData]] = Field(
+        default_factory=dict,
+        description="Offsets to use for labware movement using gripper",
+    )
 
 
 class LoadedModule(BaseModel):
@@ -616,10 +629,3 @@ class LabwareMovementStrategy(str, Enum):
     USING_GRIPPER = "usingGripper"
     MANUAL_MOVE_WITH_PAUSE = "manualMoveWithPause"
     MANUAL_MOVE_WITHOUT_PAUSE = "manualMoveWithoutPause"
-
-
-class LabwareMovementOffsetData(BaseModel):
-    """Offsets to be used during labware movement."""
-
-    pick_up_offset: LabwareOffsetVector
-    drop_offset: LabwareOffsetVector

api/tests/opentrons/motion_planning/test_waypoints.py

@@ -272,8 +272,8 @@ def test_get_gripper_labware_movement_waypoints() -> None:
         to_labware_center=Point(201, 202, 219.5),
         gripper_home_z=999,
         offset_data=LabwareMovementOffsetData(
-            pick_up_offset=LabwareOffsetVector(x=-1, y=-2, z=-3),
-            drop_offset=LabwareOffsetVector(x=1, y=2, z=3),
+            pickUpOffset=LabwareOffsetVector(x=-1, y=-2, z=-3),
+            dropOffset=LabwareOffsetVector(x=1, y=2, z=3),
         ),
     )
     assert result == [

api/tests/opentrons/protocol_engine/commands/test_move_labware.py

@@ -225,8 +225,8 @@ async def test_gripper_move_labware_implementation(
             current_location=validated_from_location,
             new_location=validated_new_location,
             user_offset_data=LabwareMovementOffsetData(
-                pick_up_offset=LabwareOffsetVector(x=1, y=2, z=3),
-                drop_offset=LabwareOffsetVector(x=0, y=0, z=0),
+                pickUpOffset=LabwareOffsetVector(x=1, y=2, z=3),
+                dropOffset=LabwareOffsetVector(x=0, y=0, z=0),
             ),
         ),
     )

api/tests/opentrons/protocol_engine/conftest.py

@@ -100,6 +100,14 @@ def well_plate_def() -> LabwareDefinition:
     )
 
 
+@pytest.fixture(scope="session")
+def adapter_plate_def() -> LabwareDefinition:
+    """Get the definition of a h/s adapter plate."""
+    return LabwareDefinition.parse_obj(
+        load_definition("opentrons_universal_flat_adapter", 1)
+    )
+
+
 @pytest.fixture(scope="session")
 def reservoir_def() -> LabwareDefinition:
     """Get the definition of single-row reservoir."""