Skip to content

compas_fab.backends.interfaces ¤

Interfaces required to integrate backends into the simulation, planning and execution pipeline of COMPAS FAB.

A backend implementation pairs a ClientInterface with a PlannerInterface subclass, and overrides planner methods by implementing the relevant BackendFeature subclasses (CheckCollision, ForwardKinematics, InverseKinematics, PlanCartesianMotion, PlanMotion, SetRobotCell, SetRobotCellState).

Classes¤

BackendFeature ¤

BackendFeature(client=None)

Base class for all backend features that are implemented by a backend client.

Classes that inherit from this class are mixed-in when creating the planner backend interface. Hence the the mixed-in class can access the attributes and other mix-ins functions of planner.

The implemented feature classes can assume that self is an instance of the planner backend interface. IDE code completion and type hints can be activated by adding a line such as planner : MoveItPlanner = self.

Attributes:

  • client (:class:`compas_fab.backends.interfaces.ClientInterface`) –

    The backend client that supports this feature.

CheckCollision ¤

CheckCollision(client=None)

Mix-in interface for implementing a planner's collision check feature.

Methods:¤

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

Check if the robot cell is in collision at the specified state.

Different planners may have different criteria for collision checking, check the planner's documentation for details.

Parameters:

  • robot_cell_state (RobotCellState) –

    The robot cell state to check for collision.

  • options (dict | None, default: None ) –

    Dictionary containing kwargs for arguments specific to the client being queried.

Returns:

  • None –

    If there is collision, the function will raise exception, otherwise it will return None.

Raises:

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

    If collision is detected.

ClientInterface ¤

ClientInterface()

Interface for implementing backend clients.

Attributes:

  • robot_cell (RobotCell) –

    The robot cell instance last set on the client.

  • robot_cell_state (RobotCellState) –

    The robot cell state instance last set on the client.

  • robot_model (RobotModel) –

    Equivalent to robot_cell.robot_model.

  • robot_semantics (RobotSemantics) –

    Equivalent to robot_cell.robot_semantics.

ForwardKinematics ¤

ForwardKinematics(client=None)

Mix-in interface for implementing a planner's forward kinematics feature.

Methods:¤

forward_kinematics ¤
forward_kinematics(
    robot_cell_state: RobotCellState,
    target_mode: TargetMode,
    group: str | None = None,
    native_scale: float | None = None,
    options: dict | None = None,
) -> 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).

Parameters:

  • robot_cell_state (RobotCellState) –

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

  • target_mode (TargetMode) –

    The target mode to select which frame to return.

  • group (str | None, default: None ) –

    The planning group of the robot. Defaults to the robot's main planning group.

  • native_scale (float | None, default: None ) –

    The scaling factor to apply to the resulting frame. It is defined as user_object_value * native_scale = meter_object_value. For example, if the resulting frame is to be used in a millimeters environment, native_scale should be set to '0.001'. Defaults to None, which means no scaling is applied.

  • options (dict | None, default: None ) –

    Dictionary containing planner-specific options. See the planner's ForwardKinematics documentation for supported options.

Returns:

  • class:`Frame` –

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

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

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

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

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

Parameters:

  • robot_cell_state (RobotCellState) –

    The robot cell state describing the robot cell.

  • link_name (str | None, default: None ) –

    The name of the link to calculate the forward kinematics for. Defaults to the last link of the provided planning group.

  • native_scale (float | None, default: None ) –

    The scaling factor to apply to the resulting frame. It is defined as user_object_value * native_scale = meter_object_value. For example, if the resulting frame is to be used in a millimeters environment, native_scale should be set to '0.001'. Defaults to None, which means no scaling is applied.

  • options (dict | None, default: None ) –

    Dictionary containing planner-specific options. See the planner's ForwardKinematics documentation for supported options.

InverseKinematics ¤

InverseKinematics()

Mix-in interface for implementing a planner's inverse kinematics feature.

Methods:¤

inverse_kinematics ¤
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 to False.

Raises:

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

    If no configuration can be found.

Returns:

  • obj:`compas_robots.Configuration` –

    The calculated configuration.

iter_inverse_kinematics ¤
iter_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.

This function returns a generator that yields possible solutions for the inverse kinematics problem. The generator will be exhausted after all possible solutions have been returned or when the maximum number of results has been reached.

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. Defaults to the robot's main planning group.

  • options (dict | None, default: None ) –

    Dictionary containing planner-specific arguments. See the planner's documentation for supported options. One of the supported options related to the iterator is:

    • "max_results": (:obj:int) Maximum number of results to return. Defaults to 100.
    • "verbose": (:obj:bool, optional) Whether or not to print verbose output. Defaults to False.

Raises:

Yields:

  • class:`compas_robots.Configuration` –

    The calculated configuration.

PlanCartesianMotion ¤

PlanCartesianMotion(client=None)

Mix-in interface for implementing a planner's plan cartesian motion feature.

Methods:¤

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

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

Parameters:

  • waypoints (Waypoints) –

    The waypoints for the robot to follow.

  • start_state (RobotCellState) –

    The starting state of the robot cell at the beginning of the motion. The attribute robot_configuration, must be provided.

  • group (str | None, default: None ) –

    The planning group used for calculation.

  • options (dict | None, default: None ) –

    Dictionary containing kwargs for arguments specific to the client being queried.

Returns:

  • class:`compas_fab.robots.JointTrajectory` –

    The calculated trajectory.

PlanMotion ¤

PlanMotion(client=None)

Mix-in interface for implementing a planner's plan motion feature.

Methods:¤

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

Calculates a motion path.

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 kwargs for arguments specific to the client being queried.

Returns:

  • class:`compas_fab.robots.JointTrajectory` –

    The calculated trajectory.

PlannerInterface ¤

PlannerInterface(client: ClientInterface | None = None)

Interface for implementing backend planners.

Planner is connected to a ClientInterface when initiated, and can access the client's robot instance. It is responsible for all planning services for the robot.

Parameters:

  • client (ClientInterface | None, default: None ) –

    The client instance associated with the planner. Typically this is set by the backend client during initialization using planner = PlannerInterface(client). Consult the chosen backend client for how to set this attribute.

Attributes:

  • client (ClientInterface) –

    The client instance associated with the planner. It cannot be changed after initialization. The client also keeps the .robot_cell and .robot_cell_state in memory.

Attributes¤

robot_cell property ¤
robot_cell

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.

robot_cell_state property ¤
robot_cell_state

The current robot cell state held by the client. None if no state has been set yet.

Methods:¤

check_collisions ¤
check_collisions(*args, **kwargs)

Default method for planner.

Raises:

forward_kinematics ¤
forward_kinematics(*args, **kwargs)

Default method for planner.

Raises:

inverse_kinematics ¤
inverse_kinematics(*args, **kwargs)

Default method for planner.

Raises:

iter_inverse_kinematics ¤
iter_inverse_kinematics(*args, **kwargs)

Default method for planner.

Raises:

plan_cartesian_motion ¤
plan_cartesian_motion(*args, **kwargs)

Default method for planner.

Raises:

plan_motion ¤
plan_motion(*args, **kwargs)

Default method for planner.

Raises:

set_robot_cell ¤
set_robot_cell(*args, **kwargs)

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. It should be called only if the robot cell models have changed.

Raises:

set_robot_cell_state ¤
set_robot_cell_state(*args, **kwargs)

Set the robot cell state to the client.

The client requires a robot cell state at the beginning of each planning request. This cell state must correspond to the robot cell set earlier by :meth:set_robot_cell.

This function is called automatically by planning functions that takes a start_state as input. Therefore it is typically not necessary for the user to call this function, except when used to trigger visualization using native backend canvas.

Raises:

SetRobotCell ¤

SetRobotCell(client=None)

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

Methods:¤

set_robot_cell ¤
set_robot_cell(
    robot_cell: RobotCell,
    robot_cell_state: RobotCellState | None = 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. It should be called only if the robot cell models have changed.

SetRobotCellState ¤

SetRobotCellState(client=None)

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

Methods:¤

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

Set the robot cell state to the client.

The client requires a robot cell state at the beginning of each planning request. This cell state must correspond to the robot cell set earlier by :meth:set_robot_cell.

This function is called automatically by planning functions that takes a RobotCellState as input. Therefore it is typically not necessary for the user to call this function, except when used to trigger visualization using native backend canvas.