Skip to main content
Version: 10

Set Collision Padding Globally or per Behavior

Required Version
This feature will not be released until MoveIt Pro version 10.3.

Link padding grows the collision geometry of every robot link by a distance in meters. Collision checks then keep that margin between the robot and world objects, and between the robot's own links. Mitigate Collision Tunneling covers when padding helps. This page covers where a Behavior gets its padding from.

Two Levels of Padding​

LevelWhere the value livesWhere you set itApplies to
GlobalThe live planning sceneconfig.yamlEvery Behavior without an override
Per BehaviorThe Behavior's collision_check_params portThe ObjectiveThat Behavior only

A Behavior with an override uses that value. A Behavior without one uses the padding of the planning scene it checks against. A scene fetched from the Runtime carries the global value. A scene passed in through a port keeps the padding of the scene it was made from. An override does not change the planning scene, so a later Behavior without an override still uses the scene's padding.

These nodes override the global value with 0.01 m by default:

  • The core motion Subtrees, such as Move to Cartesian Pose and Move to Named Waypoint.
  • PoseJog and JointJog. Request Teleoperation gives PoseJog the 0.01 m override and JointJog a 0 m override.
  • ComputeInverseKinematics, GenerateCalibrationViews and ExecutePolicy.

The global value reaches these nodes only once you remove their override.

These Behaviors use the scene's padding. PlanToJointGoal, SetupMTCPlanToPose, SetupMTCPlanToRobotState and SetupMTCConnectWithProRRT leave the port empty by default. SetupMTCBatchPoseIK and the Cartesian planning Behaviors (SetupMTCPathIK, SetupMTCCartesianSequence, SetupMTCMoveAlongFrameAxis, SetupMTCCartesianMoveToRobotState and SetupMTCMultiEEFMoveAlongAxis) have no link padding port.

When you add a node, the Desktop App writes the port's default into the Objective XML. A node that defaults to 0.01 m therefore carries that override.

World padding is the margin around world objects, and config.yaml has no entry for it. Set it per Behavior in the World padding (m) field of the collision_check_params port, or in XML with override_scene_world_padding: true and world_padding.

Set the Global Value​

Set moveit_params.link_padding in the config.yaml of your robot configuration package, in meters. 0.01 is an example value:

moveit_params:
  link_padding: 0.01

The Runtime applies it to the live planning scene at startup. Without the entry, the global value is 0.

Override the Padding on One Behavior​

In the Objective editor, click the edit icon next to the node's collision_check_params port, type a value in Link padding (m), and click Apply. Any value of 0 or more overrides the global value for that node. 0 means no link padding.

In the Objective XML, set the value together with override_scene_link_padding. 0.005 is an example value:

collision_check_params="[{override_scene_link_padding: true, link_padding: 0.005}]"

link_padding applies only while override_scene_link_padding is true. A nonzero link_padding without the flag fails the Behavior.

To make a node use the global value again, clear the padding fields in the port editor and click Apply. In XML, keep the collision_check_params attribute but leave out override_scene_link_padding and link_padding. Clearing the fields in the port editor writes [{workspace_step: 0, sanity_collision_check: false}]. Removing the attribute instead restores the port's default. On a node that defaults to 0.01 m, Reset to Defaults restores the 0.01 m override, not the global value. While the deprecated link_padding port is set, it takes precedence over collision_check_params, so unset it as well.

See Which Padding Applied​

  • The port editor. The Link padding (m) field shows a node's override. An empty field means the node uses the global value. Two cases break this: the port reads a blackboard entry, as inside the core Subtrees, or the deprecated link_padding port is set.

  • config.yaml. moveit_params.link_padding is the global value at startup.

  • The debug alert. Debug alerts are off by default. To see them, turn on Debug for the Alert Sidebar in Alert Settings. PlanToJointGoal, the jog Behaviors, ComputeInverseKinematics, GenerateCalibrationViews and ExecutePolicy publish the link padding their collision checks use and where that value is set. A line reads, for example, "Collision checks use a link padding of 0 m, set in the planning scene." The source is the planning scene, the collision_check_params port, or the deprecated link_padding port. A Behavior publishes the line again only when the value or its source changes. ExecutePolicy never pads self-collisions, so its line starts with "Collision checks against the world". The jog Behaviors publish only while skip_collision_checks is false. SetupMTCPlanToPose, SetupMTCPlanToRobotState and SetupMTCConnectWithProRRT publish only when their port sets an override.

  • The failure message. When ProRRT rejects the start or goal joint positions because of a collision, the message names the two bodies. When they are padded, it also gives the larger of their two paddings:

    The initial joint positions are not valid: found a self-collision involving the bodies 'forearm_link <-> wrist_3_pinch_link'. Colliding bodies define a padding value of 0.03 m.

Keep the Global Value Below the Self-Collision Limit​

Every link grows by the padding. Two links in a start state collide once their paddings together exceed the gap between them. Every plan from that state then fails with the message above. The limit depends on the robot and its start state. In lab_sim, for example, plans from the start state succeed with 0.025 m of link padding and fail with 0.03 m.

See Also​