CollisionCheck

Introduction

The CollisionCheck module is an optional on-board module of the rc_cube and is licensed with any of the modules ItemPick and BoxPick or CADMatch and SilhouetteMatch. Otherwise it requires a separate CollisionCheck license to be purchased.

The module provides an easy way to check if a gripper is in collision with a load carrier, the point cloud (ony in combination with CADMatch), or other detected objects (only in combination with CADMatch and SilhouetteMatch). It is integrated with the ItemPick and BoxPick and CADMatch and SilhouetteMatch modules, but can be used as standalone product. The models of the grippers for collision checking have to be defined in the GripperDB module.

Warning

Collisions are checked only between the load carrier and the gripper, not the robot itself, the flange, other objects or the item located in the robot gripper. Only in combination with CADMatch and SilhouetteMatch, and only in case the selected template contains a collision geometry and check_collisions_with_matches is enabled in the respective detection module, also collisions between the gripper and other detected objects will be checked. Collisions with objects that cannot be detected will not be checked. Only in combination with CADMatch and SilhouetteMatch and only if check_collisions_with_point_cloud is enabled in the respective detection module, collisions between the gripper and a watertight version of the point cloud will be checked.

Note

This module is pipeline specific. Changes to its settings or parameters only affect the respective camera pipeline and have no influence on other pipelines running on the rc_cube.

Table 45 Specifications of the CollisionCheck module
Collision checking with detected load carrier, detected objects (only CADMatch and SilhouetteMatch), baseplane (only SilhouetteMatch), point cloud (only CADMatch)
Collision checking available in ItemPick and BoxPick, CADMatch and SilhouetteMatch

Collision checking

Stand-alone collision checking

The check_collisions service call triggers collision checking between the chosen gripper and the provided load carriers for each of the provided grasps. Checking collisions with other objects or the point cloud is not possible with the stand-alone check_collisions service. The CollisionCheck module checks if the chosen gripper is in collision with at least one of the load carriers, when the TCP of the gripper is positioned in the grasp position. It is possible to check the collision with multiple load carriers simultaneously. The grasps which are in collision with any of the defined load carriers will be returned as colliding.

The pre_grasp_offset can be used for additional collision checking. The pre-grasp offset \(P_{off}\) is the offset between the grasp point \(P_{grasp}\) and the pre-grasp position \(P_{pre}\) in the grasp’s coordinate frame (see Fig. 34). If the pre-grasp offset is defined, the grasp will be detected as colliding if the gripper is in collision at any point during motion from the pre-grasp position to the grasp position (assuming a linear movement).

_images/pre_grasp_offset.svg

Fig. 34 Illustration of the pre-grasp offset parameter for collision checking. In this case, the pre-grasp position as well as the grasp position are collision free. However, the trajectory between these poses would have collisions. Thus, this grasp pose would be marked as colliding.

Collision checking within other modules

Collision checking is integrated in the following modules’ services:

Each of these services can take a collision_detection argument consisting of the gripper_id of the default gripper and the pre_grasp_offset as described in the previous section Stand-alone collision checking. The default gripper given by the gripper_id argument is only used for grasp points which do not have an individual gripper ID assigned. When the collision_detection argument is given, these services only return the grasps at which the gripper is not in collision or which could not be checked for collisions. When a load carrier ID is provided to these services, collision checking will always be performed between the gripper and the load carrier. Additional collision check features can be enabled depending on the module.

Only for CADMatch and SilhouetteMatch, and only in case the selected template contains a collision geometry and check_collisions_with_matches is enabled in the respective detection module, grasp points at which the gripper would be in collision with other detected objects are also rejected. The object on which the grasp point to be checked is located, is excluded from the collision check.

When a gripper is defined for a grasp point in the object template for CADMatch and SilhouetteMatch, then this gripper will be used for collision checking at that specific grasp point instead of the default gripper defined in the collision_detection argument of the detect_object service (see Setting of grasp points). The grasps returned by the detect_object service contain a flag collision_checked, indicating whether the grasp was checked for collisions, and the field gripper_id. If collision_checked is true, the returned gripper_id contains the ID of the gripper that was used for the collision check. That is the ID of the gripper defined for that specific grasp, or, if empty, the gripper that was given in the collision_detection argument of the request. If collision_checked is false, the returned gripper_id is the gripper ID that was defined for that grasp.

In SilhouetteMatch, collisions between the gripper and the base plane can be checked, if check_collisions_with_base_plane is enabled in SilhouetteMatch.

Collisions between the gripper and a watertight version of the point cloud can be checked in CADMatch and SilhouetteMatch if check_collisions_with_point_cloud is enabled in the respective module.

Warning

Collisions are checked only between the load carrier and the gripper, not the robot itself, the flange or other objects. Only in combination with CADMatch and SilhouetteMatch, and only in case the selected template contains a collision geometry and check_collisions_with_matches is enabled in the respective detection module, also collisions between the gripper and other detected objects are checked. Collisions with objects that cannot be detected will not be checked. Only in combination with CADMatch and SilhouetteMatch, and only if check_collisions_with_point_cloud is enabled, collisions between the gripper and a watertight version of the point cloud are checked.

Only in combination with CADMatch and only if check_collisions_during_retraction is enabled in CADMatch and a load carrier and a pre-grasp offset are given, collisions between the object in the gripper and the walls of the given load carrier are checked along the linear trajectory from the grasp point to the pre-grasp pose.

The collision-check results are affected by run-time parameters, which are listed and explained further below.

Parameters

The CollisionCheck module is called rc_collision_check in the REST-API and is represented in the Web GUI in the desired pipeline under Configuration ‣ CollisionCheck. The user can explore and configure the rc_collision_check module’s run-time parameters, e.g. for development and testing, using the Web GUI or the REST-API interface.

Parameter overview

This module offers the following run-time parameters:

Table 46 The rc_collision_check module’s run-time parameters
Name Type Min Max Default Description
check_bottom bool false true true Whether to enable collision checking with the bottom of the load carrier
check_flange bool false true true Whether all grasps with the flange inside the load carrier should be marked as colliding
collision_dist float64 0.0 0.1 0.01 Minimum distance in meters between any element of the gripper and the load carrier or the base plane (only SilhouetteMatch) for a collision-free grasp

Description of run-time parameters

Each run-time parameter is represented by a row in the Web GUI’s Settings section in the desired pipeline under Configuration ‣ CollisionCheck. The name in the Web GUI is given in brackets behind the parameter name:

collision_dist (Collision Distance)

Minimal distance in meters between any part of the gripper and the load carrier and/or the base plane (only SilhouetteMatch) for a grasp to be considered collision free.

Note

The collision distance is not applied when checking collisions between the gripper and the point cloud, or the gripper and other detected objects. It is not applied when checking if the flange is inside the load carrier (check_flange), either.

Via the REST-API, this parameter can be set as follows.

PUT http://<host>/api/v2/pipelines/<0,1,2,3>/nodes/rc_collision_check/parameters?collision_dist=<value>
PUT http://<host>/api/v1/nodes/rc_collision_check/parameters?collision_dist=<value>

check_flange (Check Flange)

Performs an additional safety check as described in Robot flange radius. If this parameter is set, all grasps in which any part of the robot’s flange is inside the load carrier are marked as colliding.

Via the REST-API, this parameter can be set as follows.

PUT http://<host>/api/v2/pipelines/<0,1,2,3>/nodes/rc_collision_check/parameters?check_flange=<value>
PUT http://<host>/api/v1/nodes/rc_collision_check/parameters?check_flange=<value>

check_bottom (Check Bottom)

When this check is enabled the collisions will be checked not only with the side walls of the load carrier but also with its bottom. It might be necessary to disable this check if the TCP is inside the collision geometry (e.g. is defined inside a suction cup).

The load carrier bottom will always be excluded for the collision check between the object in the gripper and the load carrier during retraction in combination with CADMatch when check_collisions_during_retraction is enabled.

Via the REST-API, this parameter can be set as follows.

PUT http://<host>/api/v2/pipelines/<0,1,2,3>/nodes/rc_collision_check/parameters?check_bottom=<value>
PUT http://<host>/api/v1/nodes/rc_collision_check/parameters?check_bottom=<value>

Status values

The rc_collision_check module reports the following status values:

Table 47 The rc_collision_check module status values
Name Description
last_evaluated_grasps Number of evaluated grasps
last_collision_free_grasps Number of collision-free grasps
collision_check_time Collision checking runtime

Services

The user can explore and call the rc_collision_check module’s services, e.g. for development and testing, using REST-API interface or the rc_cube Web GUI.

The CollisionCheck module offers the following services.

reset_defaults

Resets all parameters of the module to its default values, as listed in above table.

Details

This service can be called as follows.

PUT http://<host>/api/v2/pipelines/<0,1,2,3>/nodes/rc_collision_check/services/reset_defaults
PUT http://<host>/api/v1/nodes/rc_collision_check/services/reset_defaults
This service has no arguments.

The definition for the response with corresponding datatypes is:

{
  "name": "reset_defaults",
  "response": {
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

check_collisions (deprecated)

Triggers a collision check between a gripper and a load carrier.

Details

This service can be called as follows.

PUT http://<host>/api/v2/pipelines/<0,1,2,3>/nodes/rc_collision_check/services/check_collisions
PUT http://<host>/api/v1/nodes/rc_collision_check/services/check_collisions

Required arguments:

grasps: list of grasps that should be checked.

load_carriers: list of load carriers against which the collision should be checked. The fields of the load carrier definition are described in Detection of load carriers. The position frame of the grasps and load carriers has to be the same.

gripper_id: the id of the gripper that is used to check the collisions. The gripper has to be configured beforehand.

Optional arguments:

pre_grasp_offset: the offset in meters from the grasp position to the pre-grasp position in the grasp frame. If this argument is set, the collisions will not only be checked in the grasp point, but also on the path from the pre-grasp position to the grasp position (assuming a linear movement).

The definition for the request arguments with corresponding datatypes is:

{
  "args": {
    "grasps": [
      {
        "pose": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "pose_frame": "string",
        "uuid": "string"
      }
    ],
    "gripper_id": "string",
    "load_carriers": [
      {
        "id": "string",
        "inner_dimensions": {
          "x": "float64",
          "y": "float64",
          "z": "float64"
        },
        "outer_dimensions": {
          "x": "float64",
          "y": "float64",
          "z": "float64"
        },
        "pose": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "pose_frame": "string",
        "rim_thickness": {
          "x": "float64",
          "y": "float64"
        }
      }
    ],
    "pre_grasp_offset": {
      "x": "float64",
      "y": "float64",
      "z": "float64"
    }
  }
}

colliding_grasps: list of grasps in collision with one or more load carriers.

collision_free_grasps: list of collision-free grasps.

return_code: holds possible warnings or error codes and messages.

The definition for the response with corresponding datatypes is:

{
  "name": "check_collisions",
  "response": {
    "colliding_grasps": [
      {
        "pose": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "pose_frame": "string",
        "uuid": "string"
      }
    ],
    "collision_free_grasps": [
      {
        "pose": {
          "orientation": {
            "w": "float64",
            "x": "float64",
            "y": "float64",
            "z": "float64"
          },
          "position": {
            "x": "float64",
            "y": "float64",
            "z": "float64"
          }
        },
        "pose_frame": "string",
        "uuid": "string"
      }
    ],
    "return_code": {
      "message": "string",
      "value": "int16"
    }
  }
}

set_gripper (deprecated)

Persistently stores a gripper on the rc_cube.

This service is not available in API version 2. Use set_gripper in rc_gripper_db instead.

This service can be called as follows.

PUT http://<host>/api/v1/nodes/rc_collision_check/services/set_gripper

The definitions of the request and response are the same as described in set_gripper in rc_gripper_db.

get_grippers (deprecated)

Returns the configured grippers with the requested gripper_ids.

This service is not available in API version 2. Use get_grippers in rc_gripper_db instead.

This service can be called as follows.

PUT http://<host>/api/v1/nodes/rc_collision_check/services/get_grippers

The definitions of the request and response are the same as described in get_grippers in rc_gripper_db.

delete_grippers (deprecated)

Deletes the configured grippers with the requested gripper_ids.

This service is not available in API version 2. Use delete_grippers in rc_gripper_db instead.

This service can be called as follows.

PUT http://<host>/api/v1/nodes/rc_collision_check/services/delete_grippers

The definitions of the request and response are the same as described in delete_grippers in rc_gripper_db.

Return codes

Each service response contains a return_code, which consists of a value plus an optional message. A successful service returns with a return_code value of 0. Negative return_code values indicate that the service failed. Positive return_code values indicate that the service succeeded with additional information. The smaller value is selected in case a service has multiple return_code values, but all messages are appended in the return_code message.

The following table contains a list of common codes:

Table 48 Return codes of the CollisionCheck services
Code Description
0 Success
-1 An invalid argument was provided
-7 Data could not be read or written to persistent storage
-9 No valid license for the module
-10 New gripper could not be added as the maximum storage capacity of grippers has been exceeded
10 The maximum storage capacity of grippers has been reached
11 Existing gripper was overwritten