lib/pick_and_place: one place for pick-and-place logic, for every gripper and device

[BioCam]

The Problem

v1's CoRe grippers (STAR and Prep) each kept a fragment of legacy's placement logic and handled only a ResourceHolder. Anything else was aimed at the destination's own origin, and the model was told the same: a plate placed onto an Alpaqua magnet was sent to the magnet's origin, 28 mm below where the magnet seats it, and a lid, a ResourceStack or a rotated holder went to the wrong place too, while a Trash kept the resource in the tree. Offsets were turned by absolute rotations, so a device that is itself rotated placed and gripped off target. Legacy's move_resource resolved every destination type in one place; v1 had no shared equivalent, so each new gripper would have had to port it again. And v1 called the move drop_resource, beside a module-level place_resource that updates the model.

PR Content

• New pylabrobot/lib/pick_and_place/: legacy's logic in one place for every gripper.
  • locations.get_pick_location / get_place_location: where a resource is, or will be, on the deck, for every destination legacy supports (ResourceHolder, PlateAdapter, ResourceStack, Lid onto its Liddable, Trash, Coordinate, other), with legacy's rotation handling. Offsets follow the deck's axes (get_rotation_wrt), so a turned device places and grips correctly.
  • locations.get_grip_height: how far above the resource's bottom the fingers close, from exactly one of pickup_distance_from_top / pickup_distance_from_bottom; get_grip_location: the resource's centre at that height.
  • assignment.assign_placed_resource: the model update, moved from resources/resource_state.py; it seats the resource at the very location the move used.
• STAR and Prep CoreGrippers hold no placement or grip logic of their own. pick_up_resource takes pickup_distance_from_top or pickup_distance_from_bottom (exactly one; the 5 mm / preferred-location default is gone). place_resource checks the destination before any motion, then takes the place location once for both the motion and the model. The STAR's C0 ZP / C0 ZR take the grip point as it is; the Prep turns it into its plate-top centre (_compute_plate_top).
• drop_resource → place_resource on both; drop_resource and the Prep move_resource drop_* keywords stay as deprecated aliases, removed in the release after next. _unchecked_fw_place_resource (STAR, with its simulator override), Prep _place_at. check_can_drop_resource_here is unchanged.
• Same commands as legacy: for a holder, a rotated holder, an Alpaqua magnet, a stack, a lid, a trash and a coordinate, every C0 ZP / C0 ZR parameter and the resulting model match legacy; e.g. the place onto the magnet is now C0ZRxs05504xd0yj1133zj2162… (was …yj1137zj1881…).

Layers of a pick-and-place, on any device

Layer	Answers	STAR CoRe	Prep CoRe
1. Public API	what to move, where to	pick_up_resource / place_resource	same
2. lib/pick_and_place (shared)	where the resource is / goes on the deck, where the fingers close, where the model seats it	get_pick_location / get_place_location, get_grip_height, get_grip_location, assign_placed_resource	same
3. Device geometry (private, only if needed)	the grip point as this device's command takes it	none: C0 ZP / C0 ZR take the grip point	_compute_plate_top: the plate-top centre
4. Motion sequence (only if needed)	moves the firmware does not do itself	none	_pick_up_at / _place_at
5. Firmware	the command on the wire	C0 ZP / C0 ZR	PrepPickUpPlate / PrepDropPlate

Placement logic lives only in layer 2; layer 1 takes the place location once, for the motion and the model alike. Every future gripper (iSWAP, PF400, xArm) follows the same layers and names.

Suggested review order

1. lib/pick_and_place/locations.py and assignment.py - the logic.
2. pick_up_resource / place_resource in both core_grippers.py - now short.
3. The tests - wire strings per destination type, the lib per case.

🤖 Generated with Claude Code