# getCapsules

Get collision capsules of rigid body

Since R2022b

## Syntax

``[capsules,fitInfo] = getCapsules(capapprox,bodyname)``
``[capsules,fitInfo] = getCapsules(___,maxcollisoncapsules)``

## Description

example

````[capsules,fitInfo] = getCapsules(capapprox,bodyname)` gets the collision capsules of the specified body `bodyname` 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

collapse all

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

collapse all

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

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`

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

collapse all

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

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:

• ocg is the origin of the fitted collision object.

• lcc is the point of the central line of the collision capsule closest to ocg.

• rcc is the radius of the collision capsule.

## Version History

Introduced in R2022b