compas_fab.backends.ros.backend_features ¤

Backend feature implementations for the ROS + MoveIt backend.

Classes¤

MoveItCheckCollision ¤

MoveItCheckCollision(client=None)

Callable to check a robot cell state for collisions using MoveIt.

Backed by MoveIt's /check_state_validity service (moveit_msgs/GetStateValidity), which runs a stateless collision + constraint check of the given configuration against the planning scene currently loaded into move_group - no planning, no IK.

Methods:¤

check_collision ¤

check_collision(robot_cell_state: RobotCellState, options: dict | None = None)

Check whether robot_cell_state is collision-free in MoveIt's planning scene.

Parameters:

robot_cell_state (RobotCellState) –

The robot cell state to check. Its robot_configuration is checked, and its tool / rigid-body attachment is reflected in the planning scene.
options (dict | None, default: None ) –
Dictionary containing the following key-value pairs:
- "group": (:obj:str, optional) The planning group to check. Defaults to the robot's main planning group.

Returns:

``None`` –

Returns None if the state is collision-free.

Raises:

:class:`compas_fab.backends.exceptions.CollisionCheckError` –

If the state is in collision (or otherwise invalid). The message lists the colliding body pairs reported by MoveIt, and collision_pairs carries them.

MoveItForwardKinematics ¤

MoveItForwardKinematics(client=None)

Callable to calculate the robot's forward kinematic.

Methods:¤

forward_kinematics ¤

forward_kinematics(
    robot_cell_state: RobotCellState,
    target_mode: TargetMode,
    group: str | None = None,
    native_scale: float | None = None,
    options: dict | None = None,
)

Calculate the target frame of the robot (relative to WCF) from the provided RobotCellState.

The returned coordinate frame is dependent on the chosen target_mode:

"Target.ROBOT" will return the planner coordinate frame (PCF).
"Target.TOOL" will return the tool coordinate frame (TCF) if a tool is attached.
"Target.WORKPIECE" will return the workpiece's object coordinate frame (OCF) if a workpiece is attached (via an attached tool).

Parameters:

robot_cell_state (RobotCellState) –

The robot cell state describing the robot cell. The attribute robot_configuration, must contain the full configuration of the robot corresponding to the planning group. The robot cell state should also reflect the attachment of tools, if any.
target_mode (TargetMode) –

The target mode to select which frame to return.
group (str | None, default: None ) –

The planning group of the robot. Defaults to the robot's main planning group.
native_scale (float | None, default: None ) –

The scaling factor to apply to the resulting frame. It is defined as user_object_value * native_scale = meter_object_value. For example, if the resulting frame is to be used in a millimeters environment, native_scale should be set to '0.001'. Defaults to None, which means no scaling is applied.
options (dict | None, default: None ) –
Dictionary containing the following key-value pairs:
- "base_link": (:obj:str) Name of the base link. Defaults to the model's root link.

Returns:

class:`Frame` –

The frame in the world's coordinate system (WCF).

forward_kinematics_async ¤

forward_kinematics_async(callback, errback, configuration, options)

Asynchronous handler of MoveIt FK service.

forward_kinematics_to_link ¤

forward_kinematics_to_link(
    robot_cell_state: RobotCellState,
    link_name: str | None = None,
    native_scale: float | None = None,
    options: dict | None = None,
)

Calculate the frame of the specified robot link from the provided RobotCellState.

This function operates similar to :meth:compas_fab.backends.PyBulletForwardKinematics.forward_kinematics, but allows the user to specify which link to return. The function will return the frame of the specified link relative to the world coordinate frame (WCF).

This can be convenient in scenarios where user objects (such as a camera) are attached to one of the robot's links and the user needs to know the position of the object relative to the world coordinate frame.

Parameters:

robot_cell_state (RobotCellState) –

The robot cell state describing the robot cell.
link_name (str | None, default: None ) –

The name of the link to calculate the forward kinematics for. Defaults to the last link of the provided planning group.
native_scale (float | None, default: None ) –

The scaling factor to apply to the resulting frame. It is defined as user_object_value * native_scale = meter_object_value. For example, if the resulting frame is to be used in a millimeters environment, native_scale should be set to '0.001'. Defaults to None, which means no scaling is applied.
options (dict | None, default: None ) –
Dictionary containing the following key-value pairs:
- "base_link": (:obj:str) Name of the base link. Defaults to the model's root link.

MoveItInverseKinematics ¤

MoveItInverseKinematics()

Callable to calculate the robot's inverse kinematics for a given frame.

Methods:¤

inverse_kinematics ¤

inverse_kinematics(
    target: FrameTarget | PointAxisTarget,
    robot_cell_state: RobotCellState,
    group: str | None = None,
    options: dict | None = None,
)

Calculate the robot's inverse kinematic for a given target.

The actual implementation can be found in the :meth:iter_inverse_kinematics method. Calling inverse_kinematics() will return the first solution found by the iterator, subsequent calls will return the next solution from the iterator. Once all solutions have been exhausted, the iterator will be re-initialized.

MoveIt's inverse kinematics solver accepts FrameTarget as input. (PointAxisTarget is not yet supported)

For target-specific implementation details, see :meth:_iter_inverse_kinematics_frame_target for :class:compas_fab.robots.FrameTarget.

Parameters:

target (FrameTarget | PointAxisTarget) –

The target to calculate the inverse kinematics for.
robot_cell_state (RobotCellState) –

The starting state to calculate the inverse kinematics for. The robot's configuration in the scene is taken as the starting configuration.
group (str | None, default: None ) –

The planning group used for calculation. Defaults to the robot's main planning group.
options (dict | None, default: None ) –

Dictionary containing arguments specific to the solver. See the options parameter in :meth:iter_inverse_kinematics for details.

Returns:

obj:`compas_robots.Configuration` –

One of the possible IK configurations that reaches the target.

Raises:

:class:`compas_fab.backends.exceptions.InverseKinematicsError` –

If no configuration can be found.
:class:`compas_fab.backends.exceptions.TargetModeMismatchError` –

If the selected TargetMode is not possible with the provided robot cell state.

iter_inverse_kinematics ¤

iter_inverse_kinematics(
    target: FrameTarget | PointAxisTarget,
    robot_cell_state: RobotCellState = None,
    group: str | None = None,
    options: dict | None = None,
)

Calculate the robot's inverse kinematic for a given target.

The MoveIt inverse kinematics solver make use of the IK solver pre-configured in the MoveIt config file.

This particular function wraps the MoveIt IK solver to provide a generator that can yield multiple IK solutions. The solver will make multiple attempts to find a solution. The first attempt will start from the robot's current configuration provided in the robot_cell_state. The subsequent attempts will start from a random configuration, so the results may vary between calls.

Parameters:

target (FrameTarget | PointAxisTarget) –

The target to calculate the inverse kinematics for.
robot_cell_state (RobotCellState, default: None ) –

The starting state to calculate the inverse kinematics for.
group (str | None, default: None ) –

The planning group used for calculation. Defaults to the robot's main planning group.
options (dict | None, default: None ) –
Dictionary containing the following key-value pairs:
- "max_results": (:obj:int) Maximum number of results to return. If set to 1, the solver will be deterministic, descending from the initial robot configuration. Defaults to 100.
- "solution_uniqueness_threshold_prismatic": (:obj:float, optional) The minimum distance between two solutions in the prismatic joint space to consider them unique. Units are in meters. Defaults to 3e-4.
- "solution_uniqueness_threshold_revolute": (:obj:float, optional) The minimum distance between two solutions in the revolute joint space to consider them unique. Units are in radians. Defaults to 1e-3.
- "return_full_configuration": (:obj:bool, optional) Whether or not to return the full configuration. Defaults to False.
- "verbose": (:obj:bool, optional) Whether or not to print verbose output. Defaults to False.
- "check_collision": (:obj:bool, optional) When True (default), MoveIt is asked to return only collision-free solutions; when False, in-collision solutions are accepted. Defaults to True. The legacy key "allow_collision" (inverted meaning) is also accepted for backward compatibility.
- "constraints": (:obj:list of :class:compas_fab.robots.Constraint, optional) An extra set of MoveIt constraints where the final link of the planning group must satisfy. Defaults to None.
- "timeout": (:obj:int, optional) Maximum allowed time for one inverse kinematic calculation by the backend. If max_results is greater than 1, this timeout is applied to each calculation. Unit is seconds. Defaults to 2. This value supersedes the "attempts" argument used before ROS Noetic.

Raises:

:class:`compas_fab.backends.InverseKinematicsError` –

Indicates that no IK solution could be found by the kinematic solver after the maximum number of attempts (max_results). This can be caused by reachability or collision or both.
:class:`compas_fab.backends.TargetModeMismatchError` –

If the selected TargetMode is not possible with the provided robot cell state.
:class:`compas_fab.backends.CollisionCheckError` –

If check_collision is enabled and the configuration is in collision. This is only raised if max_results is set to 1. In this case, the solver is deterministic (descending from the initial robot configuration) and this error indicates that the problem is caused by collision and not because of reachability.

Yields:

obj:`compas_robots.Configuration` –

One of the possible IK configurations that reaches the target.

MoveItPlanCartesianMotion ¤

MoveItPlanCartesianMotion(client=None)

Callable to calculate a cartesian motion path (linear in tool space).

Methods:¤

plan_cartesian_motion ¤

plan_cartesian_motion(
    waypoints: Waypoints,
    start_state: RobotCellState,
    group: str | None = None,
    options: dict | None = None,
) -> JointTrajectory

Calculates a cartesian motion path (linear in tool space).

Parameters:

waypoints (Waypoints) –

The waypoints for the robot to follow.
start_state (RobotCellState) –

The starting state of the robot cell at the beginning of the motion. The attribute robot_configuration, must be provided.
group (str | None, default: None ) –

The planning group used for calculation. Defaults to the robot's main planning group.
options (dict | None, default: None ) –
Dictionary containing the following key-value pairs:
- "base_link": (:obj:str) Name of the base link.
- "link": (:obj:str, optional) The name of the link to calculate the forward kinematics for. Defaults to the group's end effector link.
- "max_step": (:obj:float, optional) The approximate distance between the calculated points. (Defined in the robot's units.) Defaults to 0.01.
- "jump_threshold": (:obj:float, optional) The maximum allowed distance of joint positions between consecutive points. If the distance is found to be above this threshold, the path computation fails. It must be specified in relation to max_step. If this threshold is 0, 'jumps' might occur, resulting in an invalid cartesian path. Defaults to :math:\pi / 2.
- "avoid_collisions": (:obj:bool, optional) Whether or not to avoid collisions. Defaults to True.
- "path_constraints": (:obj:list of :class:compas_fab.robots.Constraint, optional) Optional constraints that can be imposed along the solution path. Note that path calculation won't work if the start_configuration violates these constraints. Defaults to None.
- "attached_collision_meshes": (:obj:list of :class:compas_fab.robots.AttachedCollisionMesh) Defaults to None.

Returns:

class:`compas_fab.robots.JointTrajectory` –

The calculated trajectory.

plan_cartesian_motion_with_frame_waypoints_async ¤

plan_cartesian_motion_with_frame_waypoints_async(
    callback,
    errback,
    waypoints: FrameWaypoints,
    start_state: RobotCellState,
    group: str | None = None,
    options: dict | None = None,
)

Asynchronous handler of MoveIt cartesian motion planner service.

:class:compas_fab.robots.FrameWaypoints are converted to :class:compas_fab.backends.ros.messages.Pose that is native to ROS communication

plan_cartesian_motion_with_point_axis_waypoints_async ¤

plan_cartesian_motion_with_point_axis_waypoints_async(
    callback,
    errback,
    waypoints: PointAxisWaypoints,
    start_state: RobotCellState,
    group: str | None = None,
    options: dict | None = None,
)

Asynchronous handler of MoveIt cartesian motion planner service.

AFAIK MoveIt does not support planning for a relaxed axis under this

MoveItPlanMotion ¤

MoveItPlanMotion(client=None)

Callable to find a path in joint space for the robot to move from its start_configuration to the target.

Methods:¤

plan_motion ¤

plan_motion(
    target: Target,
    start_state: RobotCellState,
    group: str | None = None,
    options: dict | None = None,
)

Calculates a motion path.

The PyBullet Planner supports ConstraintSetTarget, ConfigurationTarget and FrameTarget.

Parameters:

target (Target) –

The goal for the robot to achieve.
start_state (RobotCellState) –

The starting state of the robot cell at the beginning of the motion. The attribute robot_configuration, must be provided.
group (str | None, default: None ) –

The name of the group to plan for. Defaults to the robot's main planning group.
options (dict | None, default: None ) –
Dictionary containing the following key-value pairs:
- "base_link": (:obj:str) Name of the base link. Defaults to the robot's root link.
- "path_constraints": (:obj:list of :class:compas_fab.robots.Constraint, optional) Optional constraints that can be imposed along the solution path. Note that path calculation won't work if the start_configuration violates these constraints. Defaults to None.
- "planner_id": (:obj:str) The name of the algorithm used for path planning. Defaults to 'RRTConnect'.
- "num_planning_attempts": (:obj:int, optional) Normally, if one motion plan is needed, one motion plan is computed. However, for algorithms that use randomization in their execution (like 'RRT'), it is likely that different planner executions will produce different solutions. Setting this parameter to a value above 1 will run many additional motion plans, and will report the shortest solution as the final result. Defaults to 1.
- 'allowed_planning_time': (:obj:float) The number of seconds allowed to perform the planning. Defaults to 2.
- "max_velocity_scaling_factor": (:obj:float) Defaults to 1.
- "max_acceleration_scaling_factor": (:obj:float) Defaults to 1.

Returns:

class:`compas_fab.robots.JointTrajectory` –

The calculated trajectory.

MoveItPlanningScene ¤

MoveItPlanningScene(client=None)

Callable to retrieve the planning scene.

Methods:¤

get_planning_scene ¤

get_planning_scene(options=None)

Retrieve the planning scene.

Parameters:

options (dict, default: None ) –

Unused parameter.

Returns:

class:`compas_fab.backends.ros.messages.moveit_msgs.PlanningScene` –

MoveItResetPlanningScene ¤

Callable to add a collision mesh to the planning scene.

Methods:¤

reset_planning_scene ¤

reset_planning_scene(options=None)

Resets the planning scene, removing all added collision meshes.

Parameters:

options (dict, default: None ) –

Unused parameter.

Returns:

``None`` –

MoveItSetRobotCell ¤

MoveItSetRobotCell(client=None)

Callable to add a collision mesh to the planning scene.

Methods:¤

set_robot_cell ¤

set_robot_cell(
    robot_cell: RobotCell,
    robot_cell_state: RobotCellState = None,
    options: dict | None = None,
)

Pass the models in the robot cell to the planning client.

The client keeps the robot cell models in memory and uses them for planning. Calling this method will override the previous robot cell in the client. This function will perform a comparison between the previous robot cell and not modify the objects that are identical and already in the planning scene. Note that the comparison can still be slow, therefore it should be called only if the robot cell models have changed.

Note that after modifying the robot cell, the robot_cell_state in the backend is undetermined. However, the next planning request will call set_robot_cell_state automatically to update the robot cell state.

Parameters:

robot_cell (RobotCell) –

The robot cell instance to set on the client.
robot_cell_state (RobotCellState, default: None ) –

The robot cell state instance to set on the client after setting the robot cell.
options (dict | None, default: None ) –

Unused.

MoveItSetRobotCellState ¤

MoveItSetRobotCellState(client=None)

Mix-in interface for implementing a planner's set robot cell state feature.

Methods:¤

set_robot_cell_state ¤

set_robot_cell_state(robot_cell_state: RobotCellState, options: dict | None = None)

Set the robot cell state to the client.

This function is called automatically by planning functions that takes a RobotCellState as input. In normal use cases, you should not need to call this function directly. However, one exception is when you want to set the robot cell state to the client for visualization purposes.

There are three steps to setting the robot cell state: 1. Remove all AttachedCollisionObjects from the robot state. 2. Update the position of all tools and rigid bodies in the scene. 3. Re-create AttachedCollisionObjects for all attached rigid bodies and tools.

Parameters:

robot_cell_state (RobotCellState) –

The robot cell state to set.
options (dict | None, default: None ) –

Unused.