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

Vision task coordination

Coordinate detector selection, target computation and motion for generic vision tasks. Detection-only requests can still perform pre-scan motion; vacuum verification is disabled.

beambot.stages.vision_task_stages · Source

Perception and mapping · Guide · Symbol index

How it is used

VisionTaskActionServer calls run() to perform optional scan positioning, detection, target computation, and motion. Detector names resolve through vision_task_detection; goal-computer names resolve through motion_target. The returned target selects Cartesian or joint execution.

Parsed path constraints reach the named scan-pose move, Cartesian approach/retreat, and joint-target positioning/contact moves. Multi-position detection uses a separate scan helper without constraints. detect_only can still involve scan motion and pre-opening, and the joint-target computer ignores it.

Related data types:

• VisionTaskContext: Per-goal data shared with detector and goal-computer functions: the engine, goal, scan positions, optional detected pose, and error text.

Start here

Callable	Purpose
VisionTaskStages.run	Validate offsets and sample-ROI options, execute any scan positioning, wait the configured settle interval, resolve detector/goal-computer callables, detect and compute a motion target, then dispatch motion unless the computer supplies a detect-only/no-motion result.
VisionTaskStages.reset_tf	Delegate TF listener/buffer replacement to the embedded vision engine.
VisionTaskStages._execute_motion_target	Dispatch CartesianTarget to Cartesian execution and JointTarget to joint execution.

VisionTaskStages

Coordinator around one VisionEngine. It exposes the action-server run(goal) contract and delegates acquisition, target calculation, and execution to separate functions.

VisionTaskStages.run()

Validate offsets and sample-ROI options, execute any scan positioning, wait the configured settle interval, resolve detector/goal-computer callables, detect and compute a motion target, then dispatch motion unless the computer supplies a detect-only/no-motion result.

Entry point · Source

run(self, goal) -> 'str | None'

Parameter	Meaning
goal	VisionTaskAction goal with detector/computer names, perception settings, pose/gripper data and target options.

Returns: None for success, detect-only or a successful no-motion target; categorized error string otherwise.

Errors: Unknown callable names become PIPELINE_CONFIG_ERROR; no detection and context errors become DETECTION_FAILED/GOAL_COMPUTE_FAILED. Detector, JSON and construction exceptions may propagate.

Side effects: Stores the goal, resets results, may move before detection-only capture, sleeps, captures/queries TF and executes arm/gripper motion. vacuum_ok is not measured.

VisionTaskStages.reset_tf()

Delegate TF listener/buffer replacement to the embedded vision engine.

Lifecycle · Source

reset_tf(self)

Returns: None.

Errors: VisionEngine reset errors propagate.

Side effects: Replaces perception TF resources.

VisionTaskStages._execute_motion_target()

Dispatch CartesianTarget to Cartesian execution and JointTarget to joint execution.

Method · Source

_execute_motion_target(self, target) -> 'str | None'

Parameter	Meaning
target	Computed target object.

Returns: Delegated result, or PIPELINE_ERROR for an unsupported target class.

Errors: Exceptions from target executors propagate.

Side effects: May execute motion through the selected executor.

Referenced in source (1)

• VisionTaskStages.run — beambot.stages.vision_task_stages

VisionTaskStages.__init__()

Construct the shared VisionEngine and initialize per-goal result fields.

Lifecycle · Source

__init__(self, rclpy_node, **vision_kwargs)

Parameter	Meaning
rclpy_node	Owning ROS node.
vision_kwargs	Keyword overrides forwarded directly to VisionEngine.

Errors: VisionEngine/configuration/camera initialization errors propagate.

Side effects: Constructs vision and ROS resources; sets unchecked vacuum_ok=True.

Referenced in source (1)

• VisionTaskActionServer.create_stages — beambot.action_servers.vision_task_server

Internal callbacks and helpers

VisionTaskStages._execute_joints()

Execute a joint-degree target, optional forward contact, and optional gripper state as separate tasks. Parsed goal constraints apply to the joint and contact moves.

Internal helper · Source

_execute_joints(self, target: JointTarget) -> 'str | None'

Parameter	Meaning
target	JointTarget with joints_deg, optional forward_distance in metres, gripper_group and terminal_state.

Returns: None on success or a stage-specific error string.

Errors: Malformed constraints JSON/data and pose/construction errors can propagate; build/planning/execution failures otherwise return a contextual error.

Side effects: Plans and executes up to three separate arm/gripper tasks.

Referenced in source (1)

• VisionTaskStages._execute_motion_target — beambot.stages.vision_task_stages

VisionTaskStages._execute_cartesian()

Execute a bare approach through VisionEngine, or combine a PTP/LIN fallback approach, gripper action and retreat in one task. Parsed path constraints reach the bare approach and the combined approach/retreat stages.

Internal helper · Source

_execute_cartesian(self, target: CartesianTarget) -> 'str | None'

Parameter	Meaning
target	CartesianTarget containing PoseStamped, IK frame and optional gripper/retreat fields.

Returns: None on execution success; retreat or motion error string otherwise.

Errors: Malformed constraints JSON/data and stage errors propagate; missing retreat returns an error.

Side effects: Queries IK, plans and executes arm/gripper motion; bare approaches use the engine’s standalone path.

Referenced in source (1)

• VisionTaskStages._execute_motion_target — beambot.stages.vision_task_stages

VisionTaskStages._move_to_scan()

When scan_pose is present, optionally add a release action for pre_open, then execute motion to that named joint pose.

Internal helper · Source

_move_to_scan(self, goal) -> 'str | None'

Parameter	Meaning
goal	Vision task goal with scan_pose, poses_json and optional constraints/gripper states.

Returns: None for no scan pose or success; pose/decode/position error string otherwise.

Errors: Invalid pose JSON is handled; constraints/gripper JSON and construction exceptions propagate.

Side effects: May open the gripper and move the arm before perception, including detect-only requests.

Referenced in source (1)

• VisionTaskStages.run — beambot.stages.vision_task_stages

VisionTaskStages._parse_scan_positions()

Validate the flattened scan-position length and divide it into six-joint lists without unit conversion.

Internal helper · Source

_parse_scan_positions(self, goal) -> 'list | None'

Parameter	Meaning
goal	Goal with num_scan_positions and scan_positions_flat in radians.

Returns: List of six-value scan positions, or None for nonpositive count or length mismatch.

Errors: Length mismatch is logged as a fallback; malformed iterable/count types can raise.

Side effects: Logs multi-position mode or invalid-length warning.

Referenced in source (1)

• VisionTaskStages.run — beambot.stages.vision_task_stages