🚧 Work in progress: this documentation is still being written and reviewed. Check details against the source code.

Sample pick stages

Pick samples using named joint poses or marker-guided approach motion; vision resources are initialized lazily. Result poses represent computed approaches, not raw detections.

beambot.stages.pick_sample_stages · Source

Tools and end effectors · Guide · Symbol index

How it is used

The dedicated sample action server calls run(), which chooses named-pose picking or the retained vision-guided path. Both paths open the gripper, approach the sample, grasp, and retreat; their target and retreat sources differ.

This is separate from the generic VisionTaskStages workflow. Vision resources are created only when needed, and vacuum_ok remains an unchecked success value because vacuum verification is disabled.

Start here

Callable	Purpose
PickSampleStages.run	Reset result state, validate flange offsets and decode poses, gripper states and constraints, then select vision or named-pose pick. Vacuum verification is disabled; vacuum_ok remains True.

PickSampleStages

BaseStages subclass for the dedicated pick action. It stores per-goal approach results and lazily creates a VisionEngine for marker/sample-ROI goals.

Inherits from: BaseStages.

PickSampleStages.run()

Reset result state, validate flange offsets and decode poses, gripper states and constraints, then select vision or named-pose pick. Vacuum verification is disabled; vacuum_ok remains True.

Entry point · Source

run(self, goal) -> str | None

Parameter	Meaning
goal	SampleAction goal with use_vision, pose keys, gripper states and optional perception/offset fields.

Returns: None on completion, otherwise validation/decode/execution error string.

Errors: Catches JSON syntax errors for gripper states/constraints; malformed decoded shapes and lower-level exceptions can propagate.

Side effects: Executes arm/gripper motion through the selected path, updates result fields and logs.

PickSampleStages.__init__()

Initialize shared stage state and retain camera arguments for lazy VisionEngine construction. The initial vacuum_ok value is an unchecked True.

Lifecycle · Source

__init__(
    self,
    rclpy_node,
    arm_group: str = '',
    ik_frame: str = '',
    camera_type: str = None,
    camera_frame: str = None,
    marker_dictionary: str = None,
)

Parameter	Meaning
rclpy_node	Owning ROS node.
arm_group	Planning group; empty uses the base default.
ik_frame	IK frame; empty uses the base default.
camera_type	Camera backend override forwarded to VisionEngine when first needed.
camera_frame	Camera frame override forwarded to VisionEngine.
marker_dictionary	Marker dictionary override forwarded to VisionEngine.

Errors: Base initialization errors propagate.

Side effects: Initializes result state and logs; does not construct a camera yet.

Referenced in source (1)

• SampleActionServer.create_stages — beambot.action_servers.sample_pick_place_server

Internal callbacks and helpers

PickSampleStages._run_vision()

Open the gripper and move to scan_pose; detect either a marker or sample ROI, compute/apply approach offsets, then execute approach, grasp and retreat to scan_pose.

Internal helper · Source

_run_vision(self, goal, poses: dict, gripper_states: dict, constraints) -> str | None

Parameter	Meaning
goal	SampleAction goal with scan pose, detection and approach settings.
poses	Named joint-pose mapping in degrees.
gripper_states	SRDF action mapping, using release and grasp.
constraints	Optional MoveIt path constraints.

Returns: None after completion; initialization, positioning, detection, pose or execution error string otherwise.

Errors: Vision construction exceptions are caught; subsequent detection/geometry/MTC exceptions can propagate. Missing detections and poses become explicit errors.

Side effects: Lazily creates VisionEngine, captures imagery, queries TF/IK, stores the computed approach in last_detected_pose and executes two motion tasks.

Referenced in source (1)

• PickSampleStages.run — beambot.stages.pick_sample_stages

PickSampleStages._run_hardcoded()

Build one task that opens the gripper, moves through approach_pose and target_pose, grasps and retreats to approach_pose.

Internal helper · Source

_run_hardcoded(self, goal, poses: dict, gripper_states: dict, constraints) -> str | None

Parameter	Meaning
goal	SampleAction goal with approach_pose, target_pose and gripper_group.
poses	Named six-joint degree lists.
gripper_states	SRDF gripper states, using release and grasp.
constraints	Optional MoveIt path constraints.

Returns: None on execution success or named-pose/planning/execution error string.

Errors: Malformed degree values and MTC construction errors propagate; missing or wrong-shape poses return errors.

Side effects: Creates/plans one task and actuates robot/gripper; no camera capture.

Referenced in source (1)

• PickSampleStages.run — beambot.stages.pick_sample_stages