getCapsules

Get collision capsules of rigid body

Since R2022b

Syntax

[capsules,fitInfo] = getCapsules(capapprox,bodyname)

[capsules,fitInfo] = getCapsules(___,maxcollisoncapsules)

Description

[capsules,fitInfo] = getCapsules(capapprox,bodyname) gets the collision capsules of the specified body of the rigid body tree in the capsule approximation. The function also returns the fit information of the collision capsules.

[capsules,fitInfo] = getCapsules(___,maxcollisoncapsules) specifies the maximum number of capsules to return during code generation maxcollisoncapsules, in addition to the input arguments from the previous syntax. If you specify maxcollisoncapsules during MATLAB^® execution, the function ignores it.

Examples

Create and Modify Capsule Approximation

Load a robot into the workspace and visualize it.

robotIRB = loadrobot("abbIrb120");
show(robotIRB);

Create a capsule approximation of the robot, and visualize the capsule-approximated robot model.

capsIRB = capsuleApproximation(robotIRB);
figure
show(capsIRB,homeConfiguration(capsIRB.RigidBodyTree));

Use the getCapsules function to see if the end effector, "tool0", has any collision capsules. Because tool0 is just a frame, it has no collision mesh to approximate as a collision capsule.

capsulesTool = getCapsules(capsIRB,"tool0")

capsulesTool =

  1x0 empty cell array

Add a capsule to tool0, at a position 0.15 meters along the x-axis, with a radius of 0.15 and a length of 0.

addCapsule(capsIRB,"tool0",[0.15 0],trvec2tform([0.15 0 0]))
show(capsIRB,homeConfiguration(capsIRB.RigidBodyTree));

Again check tool0 for a collision capsule, and verify the properties of the detected capsule.

capsulesTool = getCapsules(capsIRB,"tool0")

capsulesTool = 1x1 cell array
    {1x1 collisionCapsule}

capsulesTool{1}

ans = 
  collisionCapsule with properties:

    Radius: 0.1500
    Length: 0
      Pose: [4x4 double]

Remove the capsule from the base link. Then, reduce the collision capsule size of tool0, and move it -0.05 meters from the previous position along the x-axis.

removeCapsule(capsIRB,"base_link",1)
updatePose(capsIRB,"tool0",trvec2tform([-0.05 0 0]),1)
updateGeometry(capsIRB,"tool0",[.1 0.01],1)
show(capsIRB,homeConfiguration(capsIRB.RigidBodyTree));

Input Arguments

capapprox — Capsule approximation of rigid body tree

capsuleApproximation object

Capsule approximation of a rigid body tree, specified as a capsuleApproximation object.

bodyname — Name of rigid body to get capsules from

string scalar | character vector

Name of the rigid body to get capsules from, specified as a string scalar or character vector. The rigid body must exist in the rigidBodyTree object of the RigidBodyTree property of capsapprox.

Example: "EndEffectorTool"

Data Types: char | string

maxcollisoncapsules — Maximum number of collision capsules to return during code generation

10 (default) | positive integer

Maximum number of collision capsules to return from the specified rigid body during code generation, specified as a positive integer.

If you specify maxcollisoncapsules during MATLAB execution, the function ignores it.

Output Arguments

capsules — Collision capsules of rigid body

cell array

Collision capsules of the rigid body, returned as a cell array of collisionCapsule objects.

fitInfo — Fit information of collision capsules

array of structures

Fit information of the collision capsules, returned as an M-element array of structures, where M is the total number of capsules of the rigid body. Each element of fitInfo contains the fit information for the collision capsule at the corresponding index. Each structure contains the Residual field, returned as an N-element vector, where N is the total number of points of the collision geometry. Each element of the vector specifies the residual of a point of the collision geometry as:

$$\left|(o_{cg}-l_{cc})\right|+r_{cc}$$

where:

• o_cg is the origin of the fitted collision object.

• l_cc is the point of the central line of the collision capsule closest to o_cg.

• r_cc is the radius of the collision capsule.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

If the maxcollisoncapsules input argument is unspecified during code generation, the maximum number of capsules of the rigid body returned is 10, resulting in only the capsules at indices in the range [1, 10] being returned. If maxcollisoncapsules is specified in MATLAB execution, it is ignored.

Version History

Introduced in R2022b