addCollision

Add collision geometry to rigid body

Syntax

addCollision(body,type,parameters)

addCollision(body,collisionObj)

addCollision(___,Name=Value)

addCollision(___,tform)

Description

addCollision(body,type,parameters) adds a collision geometry of the specified geometric type and parameters to the specified rigid body.

addCollision(body,collisionObj) adds a collision geometry object to the rigid body, specified as one of these collision objects:

• collisionBox

• collisionCapsule

• collisionCylinder

• collisionSphere

• collisionMesh

This syntax attaches the collision geometry at a relative pose of tform*collisionObj.Pose with respect to the rigid body frame.

addCollision(___,Name=Value) specifies additional options using one or more name-value pair arguments. Specify name-value pair arguments after all other input arguments.

addCollision(___,tform) specifies a transformation for the collision geometry relative to the body frame in addition to any combination of input arguments from previous syntaxes.

Examples

Add Collision Meshes and Check Collisions for Manipulator Robot Arm

Load a robot model and modify the collision meshes. Clear existing collision meshes, add simple collision object primitives, and check whether certain configurations are in collision.

Load Robot Model

Load a preconfigured robot model into the workspace using the loadrobot function. This model already has collision meshes specified for each body. Iterate through all the rigid body elements and clear the existing collision meshes. Confirm that the existing meshes are gone.

robot = loadrobot("kukaIiwa7",DataFormat="column");

for i = 1:robot.NumBodies
    clearCollision(robot.Bodies{i})
end

show(robot,Collisions="on",Visuals="off");

Add Collision Cylinders

Iteratively add a blue collision cylinder to each body and set the transparency to opaque. Skip some bodies for this specific model, as they overlap and always collide with the end effector (body 10).

collisionObj = collisionCylinder(0.05,0.25);

for i = 1:robot.NumBodies
    if i > 6 && i < 10
        % Skip these bodies.
    else
        addCollision(robot.Bodies{i}, collisionObj, FaceColor=[0 0 1], FaceAlpha=1)
    end
end

show(robot,Collisions="on",Visuals="off");

Check for Collisions

Generate a series of random configurations. Check whether the robot is in collision at each configuration. Visualize each configuration that has a collision.

figure
rng(0) % Set random seed for repeatability.
for i = 1:20
    config = randomConfiguration(robot);
    isColliding = checkCollision(robot,config,SkippedSelfCollisions="parent");
    if isColliding
        show(robot,config,Collisions="on",Visuals="off");
        title("Collision Detected")
    else
        % Skip non-collisions.
    end
end

Input Arguments

body — Rigid body

rigidBody object

Rigid body, specified as a rigidBody object.

type — Geometry type for collision geometry

"box" | "cylinder" | "capsule" | "sphere" | "mesh"

Geometry type for collision geometry, specified as a string scalar. The specified type determines the format of the parameters input.

• "box" — [x y z]

• "cylinder" — [radius length]

• "capsule" — [radius length]

• "sphere" — radius

• "mesh" — n-by-3 matrix of vertices or an STL or DAE file name as a string

Data Types: char | string

parameters — Collision geometry parameters

numeric vector | numeric matrix | string scalar

Collision geometry parameters, specified as a numeric vector, numeric matrix, or string scalar. The type input determines the format of this value.

• "box" — [x y z]

• "cylinder" — [radius length]

• "capsule" — [radius length]

• "sphere" — radius

• "mesh" — n-by-3 matrix of vertices or an STL or DAE file name as a string

Data Types: single | double | char | string

collisionObj — Collision geometry object

collisionBox object | collisionCylinder object | collisionCapsule object | collisionSphere object | collisionMesh object

Collision geometry object, specified as a collisionBox, collisionCapsule, collisionCylinder, collisionSphere, or collisionMesh object.

tform — Transformation of collision geometry relative to body frame

eye(4) (default) | 4-by-4 homogeneous transformation matrix | string scalar | character vector

Transformation of collision geometry relative to the body frame, specified as a frame name or 4-by-4 homogeneous transformation matrix. If specifying a collision object using the collisionObj input, this function attaches the collision geometry at a relative pose of tform*collisionObj.Pose with respect to the rigid body frame.

Data Types: single | double

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: addCollision(body1, "sphere", 0.1, pose, 'FaceColor', [0 0 1], 'FaceAlpha', 1)

FaceColor — Collision object color setting

[0.466666666666667 0.674509803921569 0.188235294117647] (default) | 1-by-3 matrix

Color setting of the collision object attached to the rigid body, specified as a 1-by-3 matrix of RGB values.

Data Types: row vector

FaceAlpha — Collision object transparency setting

1 (default) | nonnegative scalar

Transparency setting of the collision object attached to the rigid body, specified as a nonnegative scalar.

Data Types: scalar

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2020b

R2025a: Add collision geometries on frame in rigid body name

You can use the addCollision function to add collision geometries on a frame in the rigid body.

R2025a: Set color and transparency of collision object

Use FaceColor and FaceAlpha to set the color and transparency of the collision object attached to the rigid body.

R2022b: addCollision supports adding capsule collision geometry

The collisionObj argument now accepts the collisionCapsule object.

The type and parameters arguments accept values of "capsule" and parameters in the form [radius length], respectively.