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

Sample place stages

Place 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.place_sample_stages · Source

Tools and end effectors · Guide · Symbol index

How it is used

The dedicated sample action server calls run(), which selects named-pose placement or the retained marker-guided path. The stage sequence approaches, releases, and retreats; the vision path returns to its scan pose.

This implementation is separate from generic VisionTaskStages. Its vision path always detects a marker even when another detection_type value changes the diagnostic text.

Start here

Callable	Purpose
PlaceSampleStages.run	Reset result state, validate flange offsets and decode poses, gripper states and constraints, then select vision or named-pose place.

PlaceSampleStages

BaseStages subclass for the dedicated place action. It owns per-goal approach results and lazily constructs its vision engine when requested.

Inherits from: BaseStages.

PlaceSampleStages.run()

Reset result state, validate flange offsets and decode poses, gripper states and constraints, then select vision or named-pose place.

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.

PlaceSampleStages.__init__()

Initialize shared stage state and retain camera arguments for lazy VisionEngine construction.

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

PlaceSampleStages._run_vision()

Move to scan_pose without changing the gripper; detect a marker, compute/apply approach offsets, then execute approach, release and retreat to scan_pose. detection_type changes diagnostic text but does not select another detector here.

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.
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)

• PlaceSampleStages.run — beambot.stages.place_sample_stages

PlaceSampleStages._run_hardcoded()

Build one task that moves through approach_pose and target_pose, releases the gripper 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.
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)

• PlaceSampleStages.run — beambot.stages.place_sample_stages