Backend classes for simulation, planning and execution.
Submodules group classes by backend family:
- ROS + MoveIt:
RosClient,MoveItPlanner,RosFileServerLoader,HttpFileServerLoader. - PyBullet:
PyBulletClient,PyBulletPlanner. - Analytical:
AnalyticalKinematicsPlannerwith robot-specific solvers (e.g.UR10eKinematics).
See the backend architecture guide for details about integrating new backends.
Classes¤
Analytical IK solver for the ABB IRB4600 40/255 robot.
Callable to calculate the robot's inverse kinematics for a given frame.
Notes
This works only for industrial robot arms with six revolute joints.
If check_collision is True, it is required to use a client
that supports "check_collision", so for now only the PyBulletClient.
Methods:¤
inverse_kinematics(
target: Target,
robot_cell_state: RobotCellState | None = None,
group: str | None = None,
options: dict | None = None,
) -> Configuration
Calculate the robot's inverse kinematic for a given frame.
The default implementation is based on the iter_inverse_kinematics method. Calling this method 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.
The starting state describes the robot cell's state at the moment of the calculation. The robot's configuration is taken as the starting configuration. If a tool is attached to the planning group, the tool's coordinate frame is used.
Parameters:
-
target(Target) –The target to calculate the inverse kinematics for.
-
robot_cell_state(RobotCellState | None, default:None) –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.
-
options(dict | None, default:None) –Dictionary containing kwargs for arguments specific to the client being queried.
"verbose": (:obj:bool, optional) Whether or not to print verbose output. Defaults toFalse.
Raises:
-
:class:`compas_fab.backends.exceptions.InverseKinematicsError`–If no configuration can be found.
Returns:
-
obj:`compas_robots.Configuration`–The calculated configuration.
inverse_kinematics_ordered(
frame_WCF: Frame, group: str | None = None, options: dict | None = None
) -> Generator[Configuration | None, None, None]
Calculate the robot's inverse kinematic (IK) for a given frame.
The IK for 6-axis industrial robots returns by default 8 possible solutions.
These solutions have an order. That means that if you call IK on two
subsequent frames and compare the 8 configurations of the first frame
with the 8 configurations of the second frame at their respective indices,
then these configurations are "close" to one another. For this reason,
for certain use cases, e.g. for cartesian path planning, it makes sense
to keep the order of solutions. This can be achieved by setting the
optional parameter keep_order to True. The configurations that
are in collision or outside joint boundaries are then not removed from
the list of solutions, they are set to None.
Parameters:
-
frame_WCF(Frame) –The frame to calculate the inverse for.
-
group(str | None, default:None) –The planning group used for determining the end effector and labeling the
start_configuration. Defaults to the robot's main planning group. -
options(dict | None, default:None) –Dictionary containing the following key-value pairs:
"solver": (:obj:str) The solver to use to calculate IK."check_collision": (:obj:str, optional ) WhenTrue, checks if the robot is in collision. Defaults toFalse."keep_order": (:obj:str, optional ) WhenFalse, removes theNone- solutions. Defaults toFalse.
Yields:
-
obj:`compas_robots.Configuration`–One of the possible IK configurations that reaches the target. If
"keep_order"isTrueresult may containNone.
Notes
This will only work with robots that have 6 revolute joints.
This function will yield exactly 8 times, if "keep_order" is True.
Raises:
-
ValueError–If the solver to solve the kinematics has not been passed.
-
InverseKinematicsError–If no IK solution could be found by the kinematic solver.
iter_inverse_kinematics(
target: Target,
start_state: RobotCellState,
group: str | None = None,
options: dict | None = None,
) -> Generator[Configuration | None, None, None]
Calculate the robot's inverse kinematic for a given target.
An iterator is returned that yields configurations.
AnalyticalKinematics(
base_frame: Frame | None = None,
flange_frame: Frame | None = None,
joint_offsets: list[float] | None = None,
)
Base class for analytical kinematics solvers.
This class is meant to be subclassed by kinematics solvers specific to a robot. Note that robot models in compas comply to URDF standards, which allows for arbitrary robot chains, however this is not the case in analytical kinematics. Even for 6R robots, whose kinematic chain that can be represented by a DH table used for analytical kinematics, the base and flange frames can differ from the URDF model. Individual joint values may also differ from the one defined by URDF by a constant offset.
In order to match the behavior of the analytical kinematics solver with planners that uses the URDF model, the AnalyticalKinematics class provides the attributes to
Attributes:
-
base_frame–The base frame of the analytical robot relative to the world coordinate system. This should be the same as the base frame of the robot in the URDF model. Defaults to no offset.
-
flange_frame–The end-effector frame of the robot relative to the last joint of the analytical robot. This should match the end effector of the robot in the URDF model. Defaults to no offset.
-
joint_offsets–The offset to be added to each joint value of the analytical robot to match the URDF model.
J_robotmodel = J_analytical + joint_offsetsDefaults to no offset.
Dummy client when running Analytical Inverse Kinematics without a client.
This client does not have any functionality, it is only used to hold
AnalyticalKinematicsPlanner(
kinematics_solver: AnalyticalKinematics, verbose: bool | None = False
)
Analytical Inverse Kinematics Planner utilize analytical kinematics to provide fast and accurate FK, IK and Cartesian motion planning.
This planner only support robots whose inverse kinematics is available through AnalyticalKinematics, such as OffsetWristKinematics and SphericalWristKinematics types. Note that the kinematics is not necessary equivalent to the same robot defined with URDF, the difference is in the base frame of the robot and the flange frames. For full list of implemented solvers, see the solvers module.
The analytical nature of the kinematics solver allows for fast and accurate calculations of the forward and inverse kinematics.
There is no collision checking available in this planner, it is also not possible to plan for collision-free IK configuration or trajectory. It is therefor also not possible to provide a robot cell with tools or rigid bodies. If collision checking is required, consider using the AnalyticalPyBulletPlanner.
In many cases, analytical solvers are able to provide multiple solutions for the inverse kinematics problem.
The iter_inverse_kinematics method will return an iterator that yields all possible solutions,
while the inverse_kinematics method will return one solution at a time.
Attributes¤
property
¤
The robot cell currently loaded into the client. None if no cell has been loaded yet.
Delegates to self.client.robot_cell so every backend planner exposes
the same accessor without each one having to re-implement it.
property
¤
The current robot cell state held by the client. None if no state has been set yet.
Methods:¤
Default method for planner.
Raises:
-
BackendFeatureNotSupportedError–Planner does not have this feature.
forward_kinematics(
robot_cell_state: RobotCellState,
target_mode: TargetMode,
scale: float | None = None,
group: str | None = None,
options: dict | None = None,
) -> Frame
Calculate the forward kinematics for a given joint configuration.
forward_kinematics_to_link(
robot_cell_state: RobotCellState,
link_name: str,
scale: float | None = None,
group: str | None = None,
options: dict | None = None,
) -> Frame
Calculate the forward kinematics for a given joint configuration to a specific link.
This method is not supported by AnalyticalKinematicsPlanner.
inverse_kinematics(
target: Target,
robot_cell_state: RobotCellState | None = None,
group: str | None = None,
options: dict | None = None,
) -> Configuration
Calculate the robot's inverse kinematic for a given frame.
The default implementation is based on the iter_inverse_kinematics method. Calling this method 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.
The starting state describes the robot cell's state at the moment of the calculation. The robot's configuration is taken as the starting configuration. If a tool is attached to the planning group, the tool's coordinate frame is used.
Parameters:
-
target(Target) –The target to calculate the inverse kinematics for.
-
robot_cell_state(RobotCellState | None, default:None) –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.
-
options(dict | None, default:None) –Dictionary containing kwargs for arguments specific to the client being queried.
"verbose": (:obj:bool, optional) Whether or not to print verbose output. Defaults toFalse.
Raises:
-
:class:`compas_fab.backends.exceptions.InverseKinematicsError`–If no configuration can be found.
Returns:
-
obj:`compas_robots.Configuration`–The calculated configuration.
inverse_kinematics_ordered(
frame_WCF: Frame, group: str | None = None, options: dict | None = None
) -> Generator[Configuration | None, None, None]
Calculate the robot's inverse kinematic (IK) for a given frame.
The IK for 6-axis industrial robots returns by default 8 possible solutions.
These solutions have an order. That means that if you call IK on two
subsequent frames and compare the 8 configurations of the first frame
with the 8 configurations of the second frame at their respective indices,
then these configurations are "close" to one another. For this reason,
for certain use cases, e.g. for cartesian path planning, it makes sense
to keep the order of solutions. This can be achieved by setting the
optional parameter keep_order to True. The configurations that
are in collision or outside joint boundaries are then not removed from
the list of solutions, they are set to None.
Parameters:
-
frame_WCF(Frame) –The frame to calculate the inverse for.
-
group(str | None, default:None) –The planning group used for determining the end effector and labeling the
start_configuration. Defaults to the robot's main planning group. -
options(dict | None, default:None) –Dictionary containing the following key-value pairs:
"solver": (:obj:str) The solver to use to calculate IK."check_collision": (:obj:str, optional ) WhenTrue, checks if the robot is in collision. Defaults toFalse."keep_order": (:obj:str, optional ) WhenFalse, removes theNone- solutions. Defaults toFalse.
Yields:
-
obj:`compas_robots.Configuration`–One of the possible IK configurations that reaches the target. If
"keep_order"isTrueresult may containNone.
Notes
This will only work with robots that have 6 revolute joints.
This function will yield exactly 8 times, if "keep_order" is True.
Raises:
-
ValueError–If the solver to solve the kinematics has not been passed.
-
InverseKinematicsError–If no IK solution could be found by the kinematic solver.
iter_inverse_kinematics(
target: Target,
start_state: RobotCellState,
group: str | None = None,
options: dict | None = None,
) -> Generator[Configuration | None, None, None]
Calculate the robot's inverse kinematic for a given target.
An iterator is returned that yields configurations.
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.
-
options(dict | None, default:None) –Dictionary containing the key-value pairs that are passed to
PlannerInterface.iter_inverse_kinematics
Returns:
-
class:`compas_fab.robots.JointTrajectory`–The calculated trajectory.
Notes
This will only work with robots that have 6 revolute joints.
Default method for planner.
Raises:
-
BackendFeatureNotSupportedError–Planner does not have this feature.
set_robot_cell(
robot_cell: RobotCell,
robot_cell_state: RobotCellState = None,
options: dict | None = None,
)
Pass the models in the robot cell to the Analytical Planner.
The planner will use the tool information for frame transformation.
Note that the Analytical Planner does not support collision checking. Therefore, the geometry of the robot, tools and rigid bodies in the robot cell are not checked.
Parameters:
-
robot_cell(RobotCell) –The robot cell to set for the planner.
-
robot_cell_state(RobotCellState, default:None) –The robot cell state to set for the planner.
-
options(dict | None, default:None) –This input is not used by the AnalyticalClient.
Notes
If the robot_cell_state is provided, it will be stored in the client for later use.
set_robot_cell_state(robot_cell_state: RobotCellState)
The Analytical Planner does not have collision checking ability, therefore it does not really need
the robot cell state. This function simply serves as the landing point for other BackendFeature to
safely call planner.set_robot_cell_state without having to check if the planner actually supports it.
The given RobotCellState object is stored on the client by reference.
Pass robot_cell_state.copy() if you intend to mutate the object after this call.
Methods:¤
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.
-
options(dict | None, default:None) –Dictionary containing the key-value pairs that are passed to
PlannerInterface.iter_inverse_kinematics
Returns:
-
class:`compas_fab.robots.JointTrajectory`–The calculated trajectory.
Notes
This will only work with robots that have 6 revolute joints.
Combination of PyBullet as the client for Collision Detection and Analytical Inverse Kinematics.
Attributes¤
property
¤
Indicates whether the client has an active connection.
Returns:
-
obj:`bool`–Trueif connected,Falseotherwise.
property
¤
robot_cell: RobotCell
The robot cell that is currently loaded in the PyBullet server.
It represents the last RobotCell that was passed to planner.set_robot_cell().
In order to avoid side effects, the RobotCell object is a copy of the original object passed to the client. Do not modify the returned object here.
property
¤
robot_cell_state: RobotCellState
The state of the robot cell that is currently loaded in the PyBullet server.
It represents the last RobotCellState that was passed to planner.set_robot_cell_state().
In order to avoid side effects, the RobotCellState object is a copy of the original object. passed to the client. Do not modify the returned object here.
There is typically no reason to access this directly, as the state is managed by the client. The state is also updated during the beginning of each CC, FK, IK and planning request. However, it can be useful for debugging. The planner uses this function internally for comparing object states that was changed.
property
¤
unordered_disabled_collisions: set
Returns the set of disabled collisions between robot links.
Methods:¤
connect(
shadows: bool = True,
color: tuple[float, float, float] | None = None,
width: int | None = None,
height: int | None = None,
verbose: bool = False,
enable_debug_gui: bool = False,
)
Connect from the PyBullet server.
Parameters:
-
shadows(bool, default:True) –Display shadows in the GUI. Defaults to
True. -
color(tuple[float, float, float] | None, default:None) –Set the background color of the GUI. Defaults to
None. -
width(int | None, default:None) –Set the width in pixels of the GUI. Defaults to
None. -
height(int | None, default:None) –Set the height in pixels of GUI. Defaults to
None. -
verbose(bool, default:False) –Enable verbose output. Defaults to
False. -
enable_debug_gui(bool, default:False) –Enable the GUI sidebar and parameter views. Defaults to
False.
Returns:
-
``None``–
robot_model_to_urdf(robot_model: RobotModel, concavity: bool = False) -> str
Converts a robot_model to a URDF package.
Parameters:
-
robot_model(RobotModel) –The robot_model to be saved for use with PyBullet.
-
concavity(bool, default:False) –When
False(the default), the mesh will be loaded as its convex hull for collision checking purposes. WhenTrue, a non-static mesh will be decomposed into convex parts using v-HACD.
Returns:
-
obj:`str`–The file path to the robot model URDF package.
Raises:
-
:exc:`Exception`–If geometry has not been loaded.
By default, the physics server will not step the simulation,
unless you explicitly send a step_simulation command. This
method will perform all the actions in a single forward dynamics
simulation step such as collision detection, constraint solving
and integration. The timestep is 1/240 second.
AnalyticalPyBulletPlanner(
client: PyBulletClient, kinematics_solver: AnalyticalKinematics
)
Combination of PyBullet as the client for Collision Detection and Analytical Inverse Kinematics.
This planner is based on the the PyBullet client for collision detection and use the analytical inverse kinematics for the calculation of the robot's inverse kinematics.
Similar to calling other analytical inverse kinematics solvers, this planner supports only robots whose inverse kinematics is available through AnalyticalKinematics, such as OffsetWristKinematics and SphericalWristKinematics types.
Attributes¤
property
¤
The robot cell currently loaded into the client. None if no cell has been loaded yet.
Delegates to self.client.robot_cell so every backend planner exposes
the same accessor without each one having to re-implement it.
property
¤
The current robot cell state held by the client. None if no state has been set yet.
Methods:¤
check_collision(state: RobotCellState, options: dict | None = None)
Checks whether the current robot cell state with the given configuration is in collision.
The collision check involves the following steps:
- Check for collisions between each robot link.
- Check for collisions between each robot link and each tool.
- Check for collisions between each robot link and each rigid body.
- Check for collisions between each attached rigid body and all other rigid bodies.
- Check for collisions between each tool and each rigid body.
In each of the above steps, the collision check is skipped if the collision is allowed by the semantics of the robot, tool, or rigid body. For details, see in-line comments in code.
The passed state is stored by reference on the client while this function updates the planner
state. Pass state.copy() if you intend to mutate it after this call.
A collision report is returned with the CollisionCheckError exception message.
Following the fail-fast principle, the exception is raised when the first collision is detected.
The rest of the collision pairs are therefore not checked.
Setting the full_report option to True will change this behavior, forcing the collision
check to continue even after a collision is detected. In this case, a detailed report is returned
with all failing collision pairs. This can be useful for debugging.
configuration : :class:compas_fab.robots.Configuration
Configuration to be checked for collisions. If None is given, the current
configuration will be checked. Defaults to None.
verbose : :obj:bool
When True, additional information is printed. Defaults to False.
full_report : :obj:bool
A collision report is returned with the CollisionCheckError exception message.
Typically, the exception is raised on the first collision detected and the rest of
the collision pairs are not checked.
If full_report is set to True, the exception will be raised after all
collision pairs are checked, and the report will contain all failing collision pairs.
Defaults to False.
Parameters:
-
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. -
options(dict | None, default:None) –Dictionary containing the following key-value pairs:
"verbose": (:obj:bool, optional) WhenTrue, additional information is printed. Note that this significantly reduces performance. Defaults toFalse."full_report": (:obj:bool, optional) WhenTrue, all collision pairs are checked even when one encountered a collision. Defaults toFalse.
Raises:
-
CollisionCheckError–If the robot is in collision. The exception message contains a collision report.
check_collision_for_attached_objects_in_planning_group(
state: RobotCellState, group: str, planner_coordinate_frame: Frame, options=None
)
A highly specific function for checking whether the attached tool and workpiece(s) for a particular target is in collision with stationary objects. This function is typically called by planning functions as part of a input sanity check or for checking whether targets are valid before motion planning.
This function is not a complete collision check but is intended to return quickly for input validation purposes. Because this function is used before motion planning, the robot configuration is not available.
The main difference between this function and the typical check_collision function is that this function only checks for collision
between the attached objects (tools and rigid bodies) and the stationary objects (other rigid bodies and tools) in the robot cell.
Only the attached objects that are related to the group and target are checked.
The robot is not checked for collision.
Internally this function depends on
:meth:~compas_fab.backends.pybullet.backend_features.PyBulletSetRobotCellState.set_robot_cell_state() and
:meth:~compas_fab.backends.pybullet.backend_features.PyBulletSetRobotCellState.set_attached_tool_and_rigid_body_state()
for setting the object states to the backend.
It will create a temporary robot_cell_state where the objects with unknown states are hidden and call
:meth:~compas_fab.backends.pybullet.backend_features.PyBulletCheckCollision.check_collision()
with only the cc4 and cc5 steps enabled.
Default method for planner.
Raises:
-
BackendFeatureNotSupportedError–Planner does not have this feature.
forward_kinematics(
robot_cell_state: RobotCellState,
target_mode: TargetMode,
group: str | None = None,
native_scale: float | None = None,
options: dict | None = None,
) -> Frame
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).
Collision checking is not performed during the calculation. Consider using the
:meth:compas_fab.backends.PyBulletCheckCollision.check_collision method to check for collisions.
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 Configuration object must includejoint_names. 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_scaleshould be set to'0.001'. Defaults to None, which means no scaling is applied. -
options(dict | None, default:None) –Dictionary for passing planner specific options. Currently unused.
Returns:
-
class:`Frame`–The frame in the world's coordinate system (WCF).
Raises:
-
:class:`compas_fab.backends.TargetModeMismatchError`–If the selected TargetMode is not possible with the provided robot cell state.
forward_kinematics_to_link(
robot_cell_state: RobotCellState,
link_name: str | None = None,
native_scale: float | None = None,
options: dict | None = None,
)
Calculate the Link Coordinate Frame (LCF) to return. 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's
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_scaleshould be set to'0.001'. Defaults to None, which means no scaling is applied. -
options(dict | None, default:None) –Dictionary for passing planner specific options. Currently unused.
inverse_kinematics(
target: Target,
robot_cell_state: RobotCellState | None = None,
group: str | None = None,
options: dict | None = None,
) -> Configuration
Calculate the robot's inverse kinematic for a given frame.
The default implementation is based on the iter_inverse_kinematics method. Calling this method 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.
The starting state describes the robot cell's state at the moment of the calculation. The robot's configuration is taken as the starting configuration. If a tool is attached to the planning group, the tool's coordinate frame is used.
Parameters:
-
target(Target) –The target to calculate the inverse kinematics for.
-
robot_cell_state(RobotCellState | None, default:None) –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.
-
options(dict | None, default:None) –Dictionary containing kwargs for arguments specific to the client being queried.
"verbose": (:obj:bool, optional) Whether or not to print verbose output. Defaults toFalse.
Raises:
-
:class:`compas_fab.backends.exceptions.InverseKinematicsError`–If no configuration can be found.
Returns:
-
obj:`compas_robots.Configuration`–The calculated configuration.
inverse_kinematics_ordered(
frame_WCF: Frame, group: str | None = None, options: dict | None = None
) -> Generator[Configuration | None, None, None]
Calculate the robot's inverse kinematic (IK) for a given frame.
The IK for 6-axis industrial robots returns by default 8 possible solutions.
These solutions have an order. That means that if you call IK on two
subsequent frames and compare the 8 configurations of the first frame
with the 8 configurations of the second frame at their respective indices,
then these configurations are "close" to one another. For this reason,
for certain use cases, e.g. for cartesian path planning, it makes sense
to keep the order of solutions. This can be achieved by setting the
optional parameter keep_order to True. The configurations that
are in collision or outside joint boundaries are then not removed from
the list of solutions, they are set to None.
Parameters:
-
frame_WCF(Frame) –The frame to calculate the inverse for.
-
group(str | None, default:None) –The planning group used for determining the end effector and labeling the
start_configuration. Defaults to the robot's main planning group. -
options(dict | None, default:None) –Dictionary containing the following key-value pairs:
"solver": (:obj:str) The solver to use to calculate IK."check_collision": (:obj:str, optional ) WhenTrue, checks if the robot is in collision. Defaults toFalse."keep_order": (:obj:str, optional ) WhenFalse, removes theNone- solutions. Defaults toFalse.
Yields:
-
obj:`compas_robots.Configuration`–One of the possible IK configurations that reaches the target. If
"keep_order"isTrueresult may containNone.
Notes
This will only work with robots that have 6 revolute joints.
This function will yield exactly 8 times, if "keep_order" is True.
Raises:
-
ValueError–If the solver to solve the kinematics has not been passed.
-
InverseKinematicsError–If no IK solution could be found by the kinematic solver.
iter_inverse_kinematics(
target: Target,
start_state: RobotCellState = None,
group: str | None = None,
options: dict | None = None,
) -> Generator[Configuration | None, None, None]
Calculate the robot's inverse kinematic for a given target.
An iterator is returned that yields configurations.
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.
-
options(dict | None, default:None) –Dictionary containing the key-value pairs that are passed to
PlannerInterface.iter_inverse_kinematics
Returns:
-
class:`compas_fab.robots.JointTrajectory`–The calculated trajectory.
Notes
This will only work with robots that have 6 revolute joints.
Default method for planner.
Raises:
-
BackendFeatureNotSupportedError–Planner does not have this feature.
set_attached_tool_and_rigid_body_state(
state: RobotCellState, group: str, planner_coordinate_frame: Frame
)
Change the state of the models in the robot cell that have already been set to the Pybullet client.
Similar to the :meth:set_robot_cell_state method, but affects only the tools and rigid bodies
that are attached to the specified group.
set_robot_cell(
robot_cell: RobotCell,
robot_cell_state: RobotCellState = None,
options: dict | None = None,
)
Pass the models in the robot cell to the Pybullet 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. It should be called only if the robot cell models have changed.
The RobotCell object passed to this method should not be modified after calling this method, as the client keeps a reference to it.
Parameters:
-
robot_cell(RobotCell) –The robot cell object containing the robot, tools, and other objects.
-
robot_cell_state(RobotCellState, default:None) –The state of the robot cell, including the robot's configuration.
-
options(dict | None, default:None) –Dictionary containing additional options. Unused at the moment.
set_robot_cell_state(robot_cell_state: RobotCellState)
Change the state of the models in the robot cell that have already been set to the Pybullet client.
This function is typically called by planning functions that accepts a start state as input. The user should not need to call this function directly.
The passed robot_cell_state is stored by reference on the client.
Pass robot_cell_state.copy() if you intend to mutate it after this call.
The robot cell state must match the robot cell set earlier by :meth:set_robot_cell.
If the robot_configuration is provided, the robot's configuration is updated and the position of the attached tools and rigid bodies are also updated accordingly. Otherwise, their positions are left unchanged.
For stationary (non-attached) tools and rigid bodies, their positions are updated according to the provided frames in the tool_state and rigid_body_state respectively.
Hidden tools and rigid bodies are not updated.
Notes
All the magic for transforming the attached objects happens here.
Indicates an exceptional state that caused an error within the backend engine.
Indicates that the selected backend does not support the selected feature.
Indicates that the selected backend feature does not support the selected target type.
Represents a future result of a long-running asynchronous operation that can be cancelled.
Methods:¤
Attempt to cancel the operation.
If the operation is currently being executed and cannot be cancelled
then the method will return False, otherwise the call will
be cancelled and the method will return True.
Return the feedback value returned by the instruction.
If the instruction has not yet returned feedback, it will wait
up to timeout seconds. If the timeout expires, the method
will raise an exception.
Indicates a collision check exception.
Attributes:
-
message(str) –The error message.
-
collision_pairs(list of tuple) –List of pairs of objects that are in collision.
Represents a future result value.
Futures are the result of asynchronous operations but allow to explicitely control when to block and wait for its completion.
HttpFileServerLoader(
base_url, ros=None, local_cache=False, local_cache_directory=None, timeout=TIMEOUT
)
Retrieves robot description and mesh files via HTTP and rosbridge topics.
Designed for the ROS 2 reference backend, where there is no equivalent of the
ROS 1 file_server package. Mesh files are fetched over plain HTTP from a
file server that exposes the ROS share directory (e.g. /opt/ros/<distro>/share/).
A package://my_pkg/path/to/foo.stl reference becomes
<base_url>/my_pkg/path/to/foo.stl. The URDF and SRDF are read from rosbridge
topics (/robot_description and /robot_description_semantic), which are
published by robot_state_publisher and move_group respectively.
Parameters:
-
base_url–Base URL of the HTTP file server, e.g.
http://localhost:9190. -
ros–The ROS client. Required to load URDF/SRDF from topics.
-
local_cache–Trueto store a local copy of the fetched files. Defaults toFalse. -
local_cache_directory–Directory to store cached files. Only used if
local_cacheisTrue. Defaults to~/robot_description. -
timeout–Network timeout, in seconds, for HTTP requests and topic subscription. Defaults to
10.
Methods:¤
Load meshes from the given package:// URL via the HTTP file server.
A single mesh URL can yield multiple meshes depending on the format.
Parameters:
-
url–Mesh URL (
package://...). -
precision–Precision for parsing geometric data.
Returns:
-
list[:class:`compas.datastructures.Mesh`]–List of meshes.
Load an SRDF model from a rosbridge topic.
Parameters:
-
topic–Name of the topic carrying the SRDF. Defaults to
/robot_description_semantic. -
message_type–ROS message type. Defaults to
std_msgs/msg/String(ROS 2 convention).
Returns:
-
str–SRDF model of the robot currently loaded in ROS.
Load a URDF model from a rosbridge topic.
robot_state_publisher publishes the URDF as a latched (transient_local)
std_msgs/String topic, so late subscribers still receive the description.
Parameters:
-
topic–Name of the topic carrying the URDF. Defaults to
/robot_description. -
message_type–ROS message type. Defaults to
std_msgs/msg/String(ROS 2 convention).
Returns:
-
str–URDF model of the robot currently loaded in ROS.
Indicates that no IK solution could be found by the kinematic solver.
MPInterpolationInCollisionError(
message, target=None, collision_pairs=None, partial_trajectory=None
)
Indicates that the interpolated trajectory is in collision.
Attributes:
-
message(str) –The error message.
-
target(Frame) –The target that is in collision.
-
collision_pairs(list of tuple) –List of pairs of objects that are in collision.
-
partial_trajectory(JointTrajectory) –The partial trajectory that was generated before the collision.
MPMaxJumpError(
message=None,
joint_name=None,
joint_type=None,
joint_values_a=None,
joint_values_b=None,
value_difference=None,
value_threshold=None,
)
Indicates that the distance between two consecutive JointTrajectoryPoint is too large.
Indicates that no plan could be found by the motion planner.
Indicates that the motion planning search timed out.
Indicates that the start state is in collision.
Attributes:
-
message(str) –The error message.
-
start_state(RobotCellState) –The start state that is in collision.
-
collision_pairs(list of tuple) –List of pairs of objects that are in collision.
Implement the planner backend interface based on MoveIt!
Attributes¤
property
¤
The robot cell currently loaded into the client. None if no cell has been loaded yet.
Delegates to self.client.robot_cell so every backend planner exposes
the same accessor without each one having to re-implement it.
property
¤
The current robot cell state held by the client. None if no state has been set yet.
Methods:¤
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_configurationis 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
Noneif 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_pairscarries them.
Default method for planner.
Raises:
-
BackendFeatureNotSupportedError–Planner does not have this feature.
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_scaleshould 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).
Asynchronous handler of MoveIt FK service.
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_scaleshould 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.
Retrieve the planning scene.
Parameters:
-
options(dict, default:None) –Unused parameter.
Returns:
-
class:`compas_fab.backends.ros.messages.moveit_msgs.PlanningScene`–
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
optionsparameter in :meth:iter_inverse_kinematicsfor 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(
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 to100."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 to3e-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 to1e-3."return_full_configuration": (:obj:bool, optional) Whether or not to return the full configuration. Defaults toFalse."verbose": (:obj:bool, optional) Whether or not to print verbose output. Defaults toFalse."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 toTrue. The legacy key"allow_collision"(inverted meaning) is also accepted for backward compatibility."constraints": (:obj:listof :class:compas_fab.robots.Constraint, optional) An extra set of MoveIt constraints where the final link of the planning group must satisfy. Defaults toNone."timeout": (:obj:int, optional) Maximum allowed time for one inverse kinematic calculation by the backend. Ifmax_resultsis greater than 1, this timeout is applied to each calculation. Unit is seconds. Defaults to2. 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_collisionis enabled and the configuration is in collision. This is only raised ifmax_resultsis 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.
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 to0.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 is0, '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 toTrue."path_constraints": (:obj:listof :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 toNone."attached_collision_meshes": (:obj:listof :class:compas_fab.robots.AttachedCollisionMesh) Defaults toNone.
Returns:
-
class:`compas_fab.robots.JointTrajectory`–The calculated trajectory.
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(
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
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:listof :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 toNone."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 above1will run many additional motion plans, and will report the shortest solution as the final result. Defaults to1.'allowed_planning_time': (:obj:float) The number of seconds allowed to perform the planning. Defaults to2."max_velocity_scaling_factor": (:obj:float) Defaults to1."max_acceleration_scaling_factor": (:obj:float) Defaults to1.
Returns:
-
class:`compas_fab.robots.JointTrajectory`–The calculated trajectory.
Resets the planning scene, removing all added collision meshes.
Parameters:
-
options(dict, default:None) –Unused parameter.
Returns:
-
``None``–
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.
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.
Indicates that the selected planning group does not exist in the robot model.
For example, if the robot model does not have a planning group with the name provided.
Exception raised when a problem is caused by a planning group.
Attributes:
-
group_name(str) –The name of the planning group.
-
joint_names(list of str) –The names of the joints in the planning group.
-
link_names(list of str) –The names of the links in the planning group.
PyBulletClient(
connection_type: str = "gui", verbose: bool = False, enable_debug_gui: bool = False
)
Interface to use pybullet as backend.
:class:compas_fab.backends.PyBulletClient is a context manager type, so it's best
used in combination with the with statement to ensure
resource deallocation.
Thanks to Yijiang Huang and his work in pybullet_planning
<https://github.com/yijiangh/pybullet_planning>_ for much inspiration.
Parameters:
-
connection_type(str, default:'gui') –Sets the connection type.
'gui'for a graphical user interface (default).'direct'mode will create a headless physics engine and directly communicates with it.'shared_memory','udp', and'tcp'are not supported. -
verbose(bool, default:False) –Use verbose logging. Defaults to
False.
Attributes:
-
verbose–Use verbose logging.
-
rigid_bodies_puids(dict[str, list[int]]) –Dictionary of rigid bodies and their PyBullet ids.
Examples:
>>> from compas_fab.backends import PyBulletClient
>>> with PyBulletClient(connection_type="direct") as client:
... print("Connected: %s" % client.is_connected)
Connected: True
Attributes¤
property
¤
Indicates whether the client has an active connection.
Returns:
-
obj:`bool`–Trueif connected,Falseotherwise.
property
¤
robot_cell: RobotCell
The robot cell that is currently loaded in the PyBullet server.
It represents the last RobotCell that was passed to planner.set_robot_cell().
In order to avoid side effects, the RobotCell object is a copy of the original object passed to the client. Do not modify the returned object here.
property
¤
robot_cell_state: RobotCellState
The state of the robot cell that is currently loaded in the PyBullet server.
It represents the last RobotCellState that was passed to planner.set_robot_cell_state().
In order to avoid side effects, the RobotCellState object is a copy of the original object. passed to the client. Do not modify the returned object here.
There is typically no reason to access this directly, as the state is managed by the client. The state is also updated during the beginning of each CC, FK, IK and planning request. However, it can be useful for debugging. The planner uses this function internally for comparing object states that was changed.
property
¤
unordered_disabled_collisions: set
Returns the set of disabled collisions between robot links.
Methods:¤
connect(
shadows: bool = True,
color: tuple[float, float, float] | None = None,
width: int | None = None,
height: int | None = None,
verbose: bool = False,
enable_debug_gui: bool = False,
)
Connect from the PyBullet server.
Parameters:
-
shadows(bool, default:True) –Display shadows in the GUI. Defaults to
True. -
color(tuple[float, float, float] | None, default:None) –Set the background color of the GUI. Defaults to
None. -
width(int | None, default:None) –Set the width in pixels of the GUI. Defaults to
None. -
height(int | None, default:None) –Set the height in pixels of GUI. Defaults to
None. -
verbose(bool, default:False) –Enable verbose output. Defaults to
False. -
enable_debug_gui(bool, default:False) –Enable the GUI sidebar and parameter views. Defaults to
False.
Returns:
-
``None``–
robot_model_to_urdf(robot_model: RobotModel, concavity: bool = False) -> str
Converts a robot_model to a URDF package.
Parameters:
-
robot_model(RobotModel) –The robot_model to be saved for use with PyBullet.
-
concavity(bool, default:False) –When
False(the default), the mesh will be loaded as its convex hull for collision checking purposes. WhenTrue, a non-static mesh will be decomposed into convex parts using v-HACD.
Returns:
-
obj:`str`–The file path to the robot model URDF package.
Raises:
-
:exc:`Exception`–If geometry has not been loaded.
By default, the physics server will not step the simulation,
unless you explicitly send a step_simulation command. This
method will perform all the actions in a single forward dynamics
simulation step such as collision detection, constraint solving
and integration. The timestep is 1/240 second.
Implement the planner backend interface for PyBullet.
Attributes¤
property
¤
The robot cell currently loaded into the client. None if no cell has been loaded yet.
Delegates to self.client.robot_cell so every backend planner exposes
the same accessor without each one having to re-implement it.
property
¤
The current robot cell state held by the client. None if no state has been set yet.
Methods:¤
check_collision(state: RobotCellState, options: dict | None = None)
Checks whether the current robot cell state with the given configuration is in collision.
The collision check involves the following steps:
- Check for collisions between each robot link.
- Check for collisions between each robot link and each tool.
- Check for collisions between each robot link and each rigid body.
- Check for collisions between each attached rigid body and all other rigid bodies.
- Check for collisions between each tool and each rigid body.
In each of the above steps, the collision check is skipped if the collision is allowed by the semantics of the robot, tool, or rigid body. For details, see in-line comments in code.
The passed state is stored by reference on the client while this function updates the planner
state. Pass state.copy() if you intend to mutate it after this call.
A collision report is returned with the CollisionCheckError exception message.
Following the fail-fast principle, the exception is raised when the first collision is detected.
The rest of the collision pairs are therefore not checked.
Setting the full_report option to True will change this behavior, forcing the collision
check to continue even after a collision is detected. In this case, a detailed report is returned
with all failing collision pairs. This can be useful for debugging.
configuration : :class:compas_fab.robots.Configuration
Configuration to be checked for collisions. If None is given, the current
configuration will be checked. Defaults to None.
verbose : :obj:bool
When True, additional information is printed. Defaults to False.
full_report : :obj:bool
A collision report is returned with the CollisionCheckError exception message.
Typically, the exception is raised on the first collision detected and the rest of
the collision pairs are not checked.
If full_report is set to True, the exception will be raised after all
collision pairs are checked, and the report will contain all failing collision pairs.
Defaults to False.
Parameters:
-
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. -
options(dict | None, default:None) –Dictionary containing the following key-value pairs:
"verbose": (:obj:bool, optional) WhenTrue, additional information is printed. Note that this significantly reduces performance. Defaults toFalse."full_report": (:obj:bool, optional) WhenTrue, all collision pairs are checked even when one encountered a collision. Defaults toFalse.
Raises:
-
CollisionCheckError–If the robot is in collision. The exception message contains a collision report.
check_collision_for_attached_objects_in_planning_group(
state: RobotCellState, group: str, planner_coordinate_frame: Frame, options=None
)
A highly specific function for checking whether the attached tool and workpiece(s) for a particular target is in collision with stationary objects. This function is typically called by planning functions as part of a input sanity check or for checking whether targets are valid before motion planning.
This function is not a complete collision check but is intended to return quickly for input validation purposes. Because this function is used before motion planning, the robot configuration is not available.
The main difference between this function and the typical check_collision function is that this function only checks for collision
between the attached objects (tools and rigid bodies) and the stationary objects (other rigid bodies and tools) in the robot cell.
Only the attached objects that are related to the group and target are checked.
The robot is not checked for collision.
Internally this function depends on
:meth:~compas_fab.backends.pybullet.backend_features.PyBulletSetRobotCellState.set_robot_cell_state() and
:meth:~compas_fab.backends.pybullet.backend_features.PyBulletSetRobotCellState.set_attached_tool_and_rigid_body_state()
for setting the object states to the backend.
It will create a temporary robot_cell_state where the objects with unknown states are hidden and call
:meth:~compas_fab.backends.pybullet.backend_features.PyBulletCheckCollision.check_collision()
with only the cc4 and cc5 steps enabled.
Default method for planner.
Raises:
-
BackendFeatureNotSupportedError–Planner does not have this feature.
forward_kinematics(
robot_cell_state: RobotCellState,
target_mode: TargetMode,
group: str | None = None,
native_scale: float | None = None,
options: dict | None = None,
) -> Frame
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).
Collision checking is not performed during the calculation. Consider using the
:meth:compas_fab.backends.PyBulletCheckCollision.check_collision method to check for collisions.
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 Configuration object must includejoint_names. 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_scaleshould be set to'0.001'. Defaults to None, which means no scaling is applied. -
options(dict | None, default:None) –Dictionary for passing planner specific options. Currently unused.
Returns:
-
class:`Frame`–The frame in the world's coordinate system (WCF).
Raises:
-
:class:`compas_fab.backends.TargetModeMismatchError`–If the selected TargetMode is not possible with the provided robot cell state.
forward_kinematics_to_link(
robot_cell_state: RobotCellState,
link_name: str | None = None,
native_scale: float | None = None,
options: dict | None = None,
)
Calculate the Link Coordinate Frame (LCF) to return. 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's
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_scaleshould be set to'0.001'. Defaults to None, which means no scaling is applied. -
options(dict | None, default:None) –Dictionary for passing planner specific options. Currently unused.
inverse_kinematics(
target: FrameTarget,
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.
Pybullet's inverse kinematics solver accepts FrameTarget and PointAxisTarget as input. The planner is a gradient descent solver, the initial position of the robot (supplied in the robot_cell_state) affects the first search attempt. Subsequent attempts will start from a random configuration, so the results may vary.
For target-specific implementation details, see
:meth:_iter_inverse_kinematics_frame_target for
:class:compas_fab.robots.FrameTarget and
:meth:_iter_inverse_kinematics_point_axis_target for
:class:compas_fab.robots.PointAxisTarget.
Parameters:
-
target(FrameTarget) –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 kwargs for arguments specific to the underlying function being called. See the target-specific function's documentation for details.
Raises:
-
:class:`compas_fab.backends.exceptions.InverseKinematicsError`–If no configuration can be found.
-
:class:`compas_fab.backends.TargetModeMismatchError`–If the selected TargetMode is not possible with the provided robot cell state.
Returns:
-
obj:`compas_robots.Configuration`–One of the possible IK configurations that reaches the target.
iter_inverse_kinematics(
target: Target,
robot_cell_state: RobotCellState,
group: str | None = None,
options: dict | None = None,
)
Calculate the robot's inverse kinematic for a given target.
Parameters:
-
target(Target) –The Frame Target to calculate the inverse for.
-
robot_cell_state(RobotCellState) –The starting state to calculate the inverse kinematics for.
-
group(str | None, default:None) –The planning group used for determining the end effector and labeling the
start_configuration. Defaults to the robot's main planning group. -
options(dict | None, default:None) –Dictionary containing the following key-value pairs:
Raises:
-
:class: `compas_fab.backends.exceptions.InverseKinematicsError`–If no configuration can be found.
-
:class:`compas_fab.backends.TargetModeMismatchError`–If the selected TargetMode is not possible with the provided robot cell state.
Yields:
-
obj:`compas_robots.Configuration`–One of the possible IK configurations that reaches the target.
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) for Waypoints.
Supports FrameWaypoints and PointAxisWaypoints.
For more information such as target specific behaviors, see
:meth:~compas_fab.backends.PyBulletClient.plan_cartesian_motion_point_axis_waypoints for
:class:~compas_fab.robots.PointAxisWaypoints and
:meth:~compas_fab.backends.PyBulletClient.plan_cartesian_motion_frame_waypoints for
:class:~compas_fab.robots.FrameWaypoints.
Note that the starting state of the robot cell must match with the objects in the robot cell
previously set using :meth:compas_fab.backends.PyBulletClient.set_robot_cell.
When a tool is attached to the planning group (specified in the start_state), it is possible
to use Waypoints.target_mode = TargetMode.TOOL.
When a workpiece is attached to the said tool, it is possible to use
Waypoints.target_mode = TargetMode.WORKPIECE.
The robot's full configuration, i.e. values for all configurable joints of the entire robot,
must be provided in the start_state.robot_configuration parameter.
The waypoints parameter is used to defined single or multiple segments of path,
it is not necessary to include the starting pose in the waypoints,
doing so may result in a redundant trajectory point.
Each path segment is interpolated linearly in Cartesian space, where position is interpolated linearly in Cartesian space and orientation is interpolated spherically using quaternion interpolation.
If the planning is successful, the function will return a :class:compas_fab.robots.JointTrajectory object,
which contains the start_configuration (same as input) and a list of :class:compas_fab.robots.JointTrajectoryPoint.
- Note that the first point in the trajectory will not repeat the start_configuration.
- Note that there may be one or more trajectory point for each path segment due to interpolation.
- Note that the returned trajectory does not separate the trajectory points into segments based on the waypoints. If the user wants to separate the path into segments, they should consider calling this function multiple times.
The check_collision parameter can be used to enable or disable collision checking during the planning process.
If enabled, the planner will check for collision at each trajectory point
similar to the :meth:compas_fab.backends.PyBulletClient.check_collision method.
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 additional options, see specific planner for details.
"check_collision": (:obj:str, optional) WhenTrue, :meth:compas_fab.backends.PyBulletCheckCollision.check_collisionwill be called. Defaults toTrue. Setting this to False may help during interactive debugging.
Returns:
-
class:`compas_fab.robots.JointTrajectory`–The calculated trajectory.
Raises:
-
:class:`compas_fab.backends.CollisionCheckError`–If
check_collisionis enabled and one of the configurations in the path is in collision. -
:class:`compas_fab.backends.InverseKinematicsError`–Indicates that one point along the path has no IK solution.
-
:class:`compas_fab.backends.TargetModeMismatchError`–If the selected TargetMode is not possible with the provided robot cell state.
Notes
This planning function is synchronous, meaning that it will block the main thread until the planning is complete. If the user wants to run the planning in the background and be able to cancel it, they should consider wrapping this function in a separate thread or process.
plan_cartesian_motion_frame_waypoints(
waypoints: FrameWaypoints,
start_state: RobotCellState,
group: str | None = None,
options: dict | None = None,
) -> JointTrajectory
Calculates a cartesian motion path (linear in tool space) for Frame Waypoints.
See :meth:~plan_cartesian_motion for the generic description of the planning function.
The following description is specific for Frame Waypoints.
The interpolation for Frame Waypoints is done in Cartesian space, meaning each segment (between two target_frames) creates a straight line in Cartesian space. The frame being interpolated is specified by the target_mode of the waypoints.
The planner will attempt to create equally spaced trajectory points between the waypoints.
The spacing is controlled by the max_step_distance and max_step_angle parameters.
These parameters are useful for controlling the smoothness of the trajectory.
However, even when two points are close in Cartesian space,
their joint positions may still be far apart.
This can be dangerous for the robot, as it may cause sudden high-speed jumps in
joint space, and large gaps in the collision checking process.
To prevent this, the planner will check whether the jump between each consecutive
joint position is within the maximum allowed distance specified by the
max_jump_prismatic and max_jump_revolute parameters.
If the jump is too large, the planner will subdivide the interpolation until the
jump is within the limits.
When this happens, the spacing between the interpolated points will no longer be equal.
The subdivision process have a maximum limit to prevent the planner from
subdividing indefinitely, such as the case near singularities.
This is controlled by the min_step_distance and min_step_angle parameters.
Typically, this is set to a small value 8 to 16 times smaller than the max_step parameters.
When the interpolation cannot be subdivided further, it is an indication that the robot
cannot reach the next point without making a large jump in joint space.
In this case, the planner will raise a JointJumpError and stop the planning process.
The following parameters are used to control the interpolation process. The interpolator will respect these parameters and will not exceed them, if the interpolation cannot be done within these limits, the planner will raise an error and stop the planning process.
Notes
Users should call :meth:~PyBulletPlanCartesianMotion.plan_cartesian_motion instead of this method directly.
Doing so will ensure that necessary scaling and checks are performed.
This planning function is deterministic, meaning that the same input will always result in the same output. If this function fails, retrying with the same input will not change the result. When planning fails, the user can still obtain the partial trajectory by
The planner will not attempt to avoid collision even when check_collision is enabled.
It simply check for them and raise an error if a collision is found.
This planning function is not asynchronous, meaning that it will block the main thread until the planning is complete or an error is raised.
Parameters:
-
waypoints(FrameWaypoints) –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.
-
options(dict | None, default:None) –Dictionary containing the following key-value pairs:
"max_step_distance": (:obj:float, optional) The max Cartesian distance between two consecutive points in the result. Unit is in meters, defaults to0.01."max_step_angle": (:obj:float, optional) The max angular distance between two consecutive points in the result. Unit is in radians, defaults to0.1."min_step_distance": (:obj:float, optional) The min Cartesian distance between two consecutive points when the interpolation is subdivided. Unit is in meters, defaults to0.0001."min_step_angle": (:obj:float, optional) The min angular distance between two consecutive points when the interpolation is subdivided. Unit is in radians, defaults to0.0001."max_jump_prismatic": (:obj:float, optional) The maximum allowed distance of prismatic joint positions between consecutive trajectory points. Unit is in meters, defaults to0.1. Setting this to0will disable this check."max_jump_revolute": (:obj:float, optional) The maximum allowed distance of revolute and continuous joint positions between consecutive trajectory points. Unit is in radians, defaults to :math:\pi / 2(90 degrees). Setting this to0will disable this check."check_collision": (:obj:bool, optional) Whether or not to avoid collision. Defaults toTrue."verbose": (:obj:bool, optional) Whether or not to print verbose output. Defaults toFalse."skip_preplanning_collision_check": (:obj:bool, optional) Whether or not to skip the target check before planning. Defaults toFalse. The preplanning check in intended to provide a fail-fast feedback for the user. However, if there are many targets in the waypoints, the check maybe more time consuming than the benefit it provides.
Returns:
-
class:`compas_fab.robots.JointTrajectory`–The calculated trajectory.
Raises:
-
:class:`compas_fab.backends.MPInterpolationInCollisionError`–If
check_collisionis enabled and the configuration is in collision. The partially planned trajectory before the collision is returned. The offending target and collision pairs are also returned. -
:class:`compas_fab.backends.MPNoIKSolutionError`–If no IK solution could be found by the kinematic solver. The partially planned trajectory before the unreachable target is returned. The unreachable target frame is returned.
-
:class:`compas_fab.backends.MPMaxJumpError`–If the joint positions between two consecutive points exceed the maximum allowed distance and the interpolation cannot be subdivided further due to the
min_step_*parameter. The joint name, type, values, and the difference are returned. -
:class:`compas_fab.backends.MPStartStateInCollisionError`–If the start state is in collision. This is part of a sanity check before the planning process.
plan_cartesian_motion_point_axis_waypoints(
waypoints: PointAxisWaypoints,
start_state: RobotCellState,
group: str | None = None,
options: dict | None = None,
) -> JointTrajectory
Calculates a cartesian motion path (linear in tool space) for Point Axis Waypoints.
Similar to the :meth:~plan_cartesian_motion_frame_waypoints method, this method calculates a cartesian motion path
(linear in tool space) for Point Axis Waypoints. The main difference is that the interpolation is
performed with the point and axis of the target. The main application of this function is
for 3D printing, milling, or other applications where the tool is cylindrical and must follow a specific path.
Users should select the correct target_mode in the waypoints to ensure that the planner interpolates correctly,
It is common to use TargetMode.TOOL for the example applications mentioned above, such that the reference frame
is the tool coordinate frame (TCF).
Note that the Z axis of the reference frame is aligned with the axis of the target.
Users who wish to use other axis should consider redefining the ToolModel.frame in their tools.
Users can choose to provide waypoints densely or sparsely. High density waypoints will allow the user to control precisely the path of the tool, such as when following a curve. This is because the planner is guaranteed to generate a JointTrajectoryPoint exactly at each waypoint. Sparse waypoints is suitable when the tool traces a straight line, the planner will create interpolated points between the waypoints automatically.
The interpolated points and axis have regular spacing between each waypoint segment.
The interpolation spacing is controlled by the max_step_distance and max_step_angle options,
they control the distance between points and the angle between axis. This setting affects the smoothness
of the trajectory.
Unlike the Cartesian motion planning with Frame Waypoints, the planner will not perform sub-division
of the interpolation when the joint jump is too large. It will simply reject the IK solution and try a different
tool orientation. Therefore, the user should not set the max_jump parameters too low, as it may prevent the
planner from finding a solution. For application that are not bounded by the joint speed, the user can set the
max_jump parameters to a high value (e.g. 0.1 meter and 1 pi radian), simply as a means to avoid sudden joint flips.
For applications that require a specific tool speed, the user can use the max_jump parameters as a rudimentary way of constraining the maximum difference between two consecutive points, hence keeping speed within the desired range.
The planning algorithm starts searching from the starting configuration and iteratively tries to find the next IK solution in the forward direction. When searching for the next IK solution, the planner will use the last configuration to perform a gradient decent, this is to ensure that the next configuration is close to the last one. However, this also limits the planner to not be able to jump to another configuration (e.g. from elbow up to elbow down). Users should therefore be aware that the planner is incomplete and may not find certain solutions even if one exists.
Because of the iterative search, the search space and searching time is highly sensitive to the starting configuration. A good starting configuration can greatly reduce the search time, while a bad starting configuration can make the search impossible. In general the user should provide a starting configuration that is likely to transition smoothly to all the waypoints.
The planner can be configured to sample the starting configuration to improve the chance of finding a solution,
this is controlled by the sample_start_configuration option. If enabled, the planner will treat the starting
configuration as an freely rotatable point-axis target. If a solution is found, the sampled configuration will be
returned in trajectory.start_configuration. In this mode, the start_state.robot_configuration is ignored.
Notes
Users should call :meth:~PyBulletPlanCartesianMotion.plan_cartesian_motion instead of this method directly.
Doing so will ensure that necessary scaling and checks are performed.
Parameters:
-
waypoints(PointAxisWaypoints) –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.
-
options(dict | None, default:None) –Dictionary containing the following key-value pairs:
"max_step_distance": (:obj:float, optional) The max Cartesian distance between two consecutive points in the result. Unit is in meters, defaults to0.01."max_step_angle": (:obj:float, optional) The max angular distance between two consecutive points in the result. Unit is in radians, defaults to0.1."sample_start_configuration": (:obj:bool, optional) Whether or not to sample the start configuration. Defaults toFalse."check_collision": (:obj:bool, optional) Whether or not to avoid collision. Defaults toTrue."max_jump_prismatic": (:obj:float, optional) The maximum allowed distance of prismatic joint positions between consecutive trajectory points. Unit is in meters, defaults to0.1. Setting this to0will disable this check."max_jump_revolute": (:obj:float, optional) The maximum allowed distance of revolute and continuous joint positions between consecutive trajectory points. Unit is in radians, defaults to :math:\pi / 2(90 degrees). Setting this to0will disable this check."check_collision": (:obj:bool, optional) Whether or not to avoid collision. Defaults toTrue."verbose": (:obj:bool, optional) Whether or not to print verbose output. Defaults toTrue."skip_preplanning_collision_check": (:obj:bool, optional) Whether or not to skip the target check before planning. Defaults toTrue. The preplanning check in intended to provide a fail-fast feedback for the user. However, if there are many targets in the waypoints, the check maybe more time consuming than the benefit it provides. Because this planner is often used for 3D printing, milling, etc. the user is likely to provide dense waypoints, therefore this check is disabled by default.
Returns:
-
class:`compas_fab.robots.JointTrajectory`–The calculated trajectory.
Raises:
-
:class:`compas_fab.backends.MPNoIKSolutionError`–If no IK solution could be found by the kinematic solver. The partially planned trajectory before the unreachable target is returned. The unreachable target frame is returned.
Default method for planner.
Raises:
-
BackendFeatureNotSupportedError–Planner does not have this feature.
set_attached_tool_and_rigid_body_state(
state: RobotCellState, group: str, planner_coordinate_frame: Frame
)
Change the state of the models in the robot cell that have already been set to the Pybullet client.
Similar to the :meth:set_robot_cell_state method, but affects only the tools and rigid bodies
that are attached to the specified group.
set_robot_cell(
robot_cell: RobotCell,
robot_cell_state: RobotCellState = None,
options: dict | None = None,
)
Pass the models in the robot cell to the Pybullet 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. It should be called only if the robot cell models have changed.
The RobotCell object passed to this method should not be modified after calling this method, as the client keeps a reference to it.
Parameters:
-
robot_cell(RobotCell) –The robot cell object containing the robot, tools, and other objects.
-
robot_cell_state(RobotCellState, default:None) –The state of the robot cell, including the robot's configuration.
-
options(dict | None, default:None) –Dictionary containing additional options. Unused at the moment.
set_robot_cell_state(robot_cell_state: RobotCellState)
Change the state of the models in the robot cell that have already been set to the Pybullet client.
This function is typically called by planning functions that accepts a start state as input. The user should not need to call this function directly.
The passed robot_cell_state is stored by reference on the client.
Pass robot_cell_state.copy() if you intend to mutate it after this call.
The robot cell state must match the robot cell set earlier by :meth:set_robot_cell.
If the robot_configuration is provided, the robot's configuration is updated and the position of the attached tools and rigid bodies are also updated accordingly. Otherwise, their positions are left unchanged.
For stationary (non-attached) tools and rigid bodies, their positions are updated according to the provided frames in the tool_state and rigid_body_state respectively.
Hidden tools and rigid bodies are not updated.
Notes
All the magic for transforming the attached objects happens here.
Interface to use ROS as backend via the rosbridge.
The connection is managed by roslibpy.
:class:.RosClient is a context manager type, so it's best
used in combination with the with statement to ensure
resource deallocation.
Parameters:
-
host(str, default:'localhost') –ROS bridge host. Defaults to
localhost. -
port(int, default:9090) –Port of the ROS Bridge. Defaults to
9090. -
is_secure(bool, default:False) –Trueto indicate it should use a secure web socket, otherwiseFalse. -
**kwargs–Additional keyword arguments forwarded as-is to
roslibpy.Ros. Notablytransport(roslibpy >= 2.1) selects the per-connection transport backend:"twisted"(default on most platforms),"asyncio"(opt-in, requirespip install roslibpy[asyncio]), or"cli"(auto-selected on IronPython). When omitted the choice falls through to theROSLIBPY_TRANSPORTenv var and :func:roslibpy.set_default_transport. Seeroslibpy.commfor the full precedence rules. Only pass arguments your installed roslibpy version supports.
Examples:
Attributes¤
property
¤
Retrieves the ROS version to which the client is connected (e.g. noetic, jazzy).
Modern rosapi exposes /rosapi/get_ros_version for both ROS 1 and
ROS 2. Older ROS 1 deployments also expose a global /rosdistro
parameter, which remains as a fallback for compatibility.
Methods:¤
execute_joint_trajectory(
joint_trajectory,
action_name="/execute_trajectory",
callback=None,
errback=None,
feedback_callback=None,
timeout=60000,
)
Execute a joint trajectory via the MoveIt infrastructure.
Notes
This method does not support Multi-DOF Joint Trajectories.
Parameters:
-
joint_trajectory(:class:`compas_fab.robots.JointTrajectory`) –Instance of joint trajectory.
-
callback(callable, default:None) –Function to be invoked when the goal is completed, requires one positional parameter
result. -
action_name(string, default:'/execute_trajectory') –ROS action name, defaults to
/execute_trajectory. -
errback(callable, default:None) –Function to be invoked in case of error or timeout, requires one position parameter
exception. -
feedback_callback(callable, default:None) –Function to be invoked during execution to provide feedback.
-
timeout(int, default:60000) –Timeout for goal completion in milliseconds.
Returns:
-
class:`CancellableFutureResult`–An instance of a cancellable future result.
follow_joint_trajectory(
joint_trajectory,
action_name="/joint_trajectory_action",
callback=None,
errback=None,
feedback_callback=None,
timeout=60000,
)
Follow the joint trajectory as computed by MoveIt planner.
Parameters:
-
joint_trajectory(:class:`compas_fab.robots.JointTrajectory`) –Instance of joint trajectory. Note: for backwards compatibility, this supports a ROS Msg being passed as well.
-
action_name(string, default:'/joint_trajectory_action') –ROS action name, defaults to
/joint_trajectory_actionbut some drivers need/follow_joint_trajectory. -
callback(callable, default:None) –Function to be invoked when the goal is completed, requires one positional parameter
result. -
errback(callable, default:None) –Function to be invoked in case of error or timeout, requires one position parameter
exception. -
feedback_callback(callable, default:None) –Function to be invoked during execution to provide feedback.
-
timeout(int, default:60000) –Timeout for goal completion in milliseconds.
Returns:
-
class:`CancellableTask`–An instance of a cancellable tasks.
load_robot_cell(
load_geometry: bool = False,
urdf_param_name: str = "/robot_description",
srdf_param_name: str = "/robot_description_semantic",
precision: int = None,
local_cache_directory: str | None = None,
http_file_server_base_url: str | None = None,
)
Load the robot cell (including model and semantics) from ROS.
The robot celL is set in client.robot_cell and returned.
Parameters:
-
load_geometry(bool, default:False) –Trueto load the robot's geometry, otherwiseFalseto load only the model and semantics. -
urdf_param_name(str, default:'/robot_description') –Parameter name where the URDF is defined. If not defined, it will default to
/robot_description. -
srdf_param_name(str, default:'/robot_description_semantic') –Parameter name where the SRDF is defined. If not defined, it will default to
/robot_description_semantic. -
precision(int, default:None) –Defines precision for importing/loading meshes. Defaults to
compas.tolerance.TOL.precision. -
local_cache_directory(str | None, default:None) –Directory where the robot description (URDF, SRDF and meshes) are stored. This differs from the directory taken as parameter by the :class:
RosFileServerLoaderin that it points directly to the specific robot package, not to a global workspace storage for all robots. If not assigned, the robot will not be cached locally. -
http_file_server_base_url(str | None, default:None) –Base URL of the HTTP file server used by ROS 2 to resolve
package://mesh URLs. Defaults tohttp://<rosbridge-host>:9190.
Examples:
Wraps an exception that occurred on the communication with ROS.
Allows to retrieve the mesh files specified in the robot model from the ROS File Server. Optionally, it stores them on the local file system, allowing for faster re-loads as well as enabling them to be loaded by the local package loaders afterwards.
Parameters:
-
ros(:class:`compas_fab.backends.RosClient`, default:None) –The ROS client.
-
local_cache(bool, default:False) –Trueto store a local copy of the ROS files, otherwiseFalse. Defaults toFalse. -
local_cache_directory(str, default:None) –Directory name to store the cached files. Only used if
local_cacheisTrue. Defaults to~/robot_description.
Methods:¤
Load the mesh from the given URL.
.. deprecated:: 0.23
Use :meth:load_meshes instead.
Parameters:
-
url(str) –Mesh URL
Returns:
-
class:`compas.datastructures.Mesh`–Instance of a mesh.
Load meshes from the given URL in the ROS file server.
A single mesh url can contain multiple meshes depending on the format.
Parameters:
-
url(str) –Mesh URL
-
precision–The precision for parsing geometric data.
Returns:
-
list[:class:`compas.datastructures.Mesh`]–List of meshes.
Wraps an exception that occurred on validation of a ROS response.
Analytical IK solver for the Stäubli TX2 60L robot.
Indicates that the selected TargetMode is not possible with the provided robot cell state.
For example, if the robot cell state does not have a tool attached to the robot,
but the TargetMode is set to Target.TOOL.