Backend clients

This document details the architecture used to implement backend clients and backend features.

To maintain consistency from one backend client to another and to promote modularity, we make use of several interfaces. Any new backend client should inherit from ClientInterface and make use of the PlannerInterface. Methods for connecting, disconnecting, and generally managing the client state are a part of the client, while any methods for planning, scene management or kinematics are attached to the planner. Eventually, methods for execution and control will be included in the ControlInterface, but for now, such methods and attributes will be left with the client.

The PlannerInterface serves as a template for any client-specific planner, providing default behavior for each of the methods listed within. When a developer wishes to override any of these defaults, they should make use of the appropriate backend feature interface from backends/interfaces.py. The file interfaces.py consists of a collection of classes, any implementation of which is callable through its __call__ magic method. For example:

from compas.geometry import Frame
from compas_fab.backends.interfaces import InverseKinematics

class ExampleInverseKinematics(InverseKinematics):
    def inverse_kinematics(self, robot,
                           frame_WCF,
                           start_configuration=None,
                           group=None,
                           options=None):
        # insert fancy code here
        pass

can be instantiated and called in the following manner:

calculate_example_ik = ExampleInverseKinematics()
frame = Frame([0, 0, 0], [1, 0, 0], [0, 1, 0])
ik_result = calculate_example_ik(robot, frame)
# or equivalently:
ik_result = calculate_example_ik.inverse_kinematics(robot, frame)

These backend feature interfaces exist in part to enforce a common signature across all implementations of, say, inverse_kinematics for greater end-user ease. Please adhere to the types listed for the arguments and return values listed in the documentation for the backend features as much as possible.

These interfaces as exist to allow mixing and matching of the backend features of various clients to suit the performance and overhead requirements of the end-user. To illustrate this last point, consider the following example, where the backend of ClientA is very efficient at computing inverse kinematics and has no feature to plan motion, while the backend of ClientB is slow to compute inverse kinematics but can plan motion:

with ClientA() as client_a, ClientB() as client_b:
    inverse_kinematics = ClientAInverseKinematics(client_a)
    plan_motion = ClientBPlanMotion(client_b)

Here we can assign the inverse kinematics to be calculated by the backend of ClientA, while the motion planning is calculated by the backend of ClientB. (We assume ClientA and ClientB inherit from ClientInterface and that ClientAInverseKinematics and ClientBPlanMotion inherit from InverseKinematics and PlanMotion, resp.)

Backend interfaces

This package defines the interfaces required to integrate backends into the simulation, planning and execution pipeline of COMPAS FAB.

Client interfaces

ClientInterface

Interface for all backend clients.

PlannerInterface

Interface for all planners associated with a backend client.

Feature interfaces

BackendFeature

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

ForwardKinematics

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

InverseKinematics

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

PlanMotion

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

PlanCartesianMotion

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

Planning scene interfaces

GetPlanningScene

Mix-in interface for implementing a planner's get planning scene feature.

AddCollisionMesh

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

AppendCollisionMesh

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

RemoveCollisionMesh

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

AddAttachedCollisionMesh

Mix-in interface for implementing a planner's add attached collision mesh feature.

RemoveAttachedCollisionMesh

Mix-in interface for implementing a planner's remove attached collision mesh feature.

ResetPlanningScene

Mix-in interface for implementing a planner's reset planning scene feature.

Implemented backend features

The following backend features are implemented for the ROS backend:

ROS backend features

MoveItAddAttachedCollisionMesh

Callable to add a collision mesh and attach it to the robot.

MoveItAddCollisionMesh

Callable to add a collision mesh to the planning scene.

MoveItAppendCollisionMesh

Callable to append a collision mesh to the planning scene.

MoveItForwardKinematics

Callable to calculate the robot's forward kinematic.

MoveItInverseKinematics

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

MoveItPlanCartesianMotion

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

MoveItPlanMotion

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

MoveItPlanningScene

Callable to retrieve the planning scene.

MoveItRemoveAttachedCollisionMesh

Callable to remove an attached collision mesh from the robot.

MoveItRemoveCollisionMesh

Callable to remove a collision mesh from the planning scene.

MoveItResetPlanningScene

Callable to add a collision mesh to the planning scene.

The following backend features are implemented for the PyBullet backend:

PyBullet backend features

PyBulletAddAttachedCollisionMesh

Callable to add a collision mesh and attach it to the robot.

PyBulletAddCollisionMesh

Callable to add a collision mesh to the planning scene.

PyBulletAppendCollisionMesh

Callable to append a collision mesh to the planning scene.

PyBulletForwardKinematics

Callable to calculate the robot's forward kinematic.

PyBulletInverseKinematics

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

PyBulletRemoveAttachedCollisionMesh

Callable to remove an attached collision mesh from the robot.

PyBulletRemoveCollisionMesh

Callable to remove a collision mesh from the planning scene.