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

Vision motion targets

Convert vision detections into Cartesian or joint targets for the vision-task coordinator.

beambot.vision.motion_target · Source

Perception and mapping · Guide · Symbol index

How it is used

VisionTaskStages selects a goal computer with get_goal_computer(). approach_pose converts a detected pose to a CartesianTarget; j6_snap adjusts a named pose’s final joint from a detected square-feature angle and returns a JointTarget.

These functions construct targets; the coordinator executes them afterward. snap_j6() is the small angle-only calculation beneath the joint-target path. Angles in JointTarget are degrees; Cartesian positions and forward distances use metres.

Related data types:

  • CartesianTarget: Frozen record describing an approach pose in base_link, its IK frame, and optional gripper action and named retreat.

  • JointTarget: Frozen record describing degree-valued joints with optional forward contact distance and terminal gripper state.

Start here

Callable

Purpose

get_goal_computer

Select one of the direct goal-computation functions.

compute_approach_pose

Convert a pose detection into a Cartesian target, including optional flange displacement and terminal/retreat settings.

compute_j6_snap

Copy a named six-joint pose and replace joint 6 with the calibrated angular correction.

snap_j6

Correct joint 6 using square-feature symmetry, keeping the angular correction in (-45,45] degrees.

Example

A square feature at 80° is equivalent to one at −10°. With no calibration offset, joint 6 therefore changes from 30° to 20°:

from beambot.vision.motion_target import snap_j6

assert snap_j6(base_j6_deg=30.0, angle_deg=80.0) == 20.0

This calculation does not check joint limits or execute motion. Importing the module requires ROS message types.

Functions

get_goal_computer()

Select one of the direct goal-computation functions.

Entry point · Source

get_goal_computer(name: str)

Parameter

Meaning

name

Exact key approach_pose or j6_snap.

Returns: The selected callable without invoking it.

Errors: KeyError with available choices for an unknown key.

Referenced in source (1)

compute_approach_pose()

Convert a pose detection into a Cartesian target, including optional flange displacement and terminal/retreat settings.

Function · Source

compute_approach_pose(detection, ctx)

Parameter

Meaning

detection

Pose detection passed to VisionEngine.compute_approach_pose(), normally PoseStamped in base_link.

ctx

Vision context with engine, goal geometry/tool fields, and a writable detect_only_pose attribute.

Returns: CartesianTarget, or None when detect_only is true. In detect-only mode the computed pose is stored in ctx.detect_only_pose.

Errors: Malformed gripper_states_json and delegated geometry/TF errors can propagate. An offset is applied only when direction is nonempty and distance is positive.

Side effects: Computes geometry and may query TF; writes ctx.detect_only_pose for detect-only requests. Does not execute the target. Terminal aliases are resolved through gripper_states_json, with literal-state fallback.

compute_j6_snap()

Copy a named six-joint pose and replace joint 6 with the calibrated angular correction.

Function · Source

compute_j6_snap(detection, ctx)

Parameter

Meaning

detection

Dictionary containing angle_mod90 in degrees.

ctx

Vision context with goal.target_pose, poses_json, k_offset, and optional forward/gripper settings; ctx.error receives missing-pose failures.

Returns: JointTarget containing degree-valued joints and optional forward distance/terminal state, or None when the named base pose is absent.

Errors: Missing base pose sets ctx.error and returns None. JSON parsing, missing angle, short joint lists, and numeric errors can raise. It does not check detect_only or joint limits.

Side effects: Logs the correction and may set ctx.error. Copies the base pose before replacing its final joint; no arm/gripper action is executed here.

snap_j6()

Correct joint 6 using square-feature symmetry, keeping the angular correction in (-45,45] degrees.

Function · Source

snap_j6(base_j6_deg: float, angle_deg: float, k_offset_deg: float=0.0) -> float

Parameter

Meaning

base_j6_deg

Original joint-6 angle in degrees.

angle_deg

Detected feature angle in degrees.

k_offset_deg

Calibration angle added before the modulo-90 correction, in degrees.

Returns: base_j6_deg plus the normalized correction. The final joint angle itself is not wrapped.

Errors: No finite-value, type, or joint-limit validation; arithmetic errors propagate.

Example

from beambot.vision.motion_target import snap_j6
assert snap_j6(-180, 80) == -190.0      # -10-degree correction
assert snap_j6(-180, 45) == -135.0      # +45 is retained
assert snap_j6(-180, 80, 10) == -180.0  # 90 degrees is symmetric
Referenced in source (1)