Main Content


Get collision capsules of rigid body

Since R2022b



    [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.


    collapse all

    Load a robot into the workspace and visualize it.

    robotIRB = loadrobot("abbIrb120");

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

    capsIRB = capsuleApproximation(robotIRB);

    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]))

    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}
    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.

    updatePose(capsIRB,"tool0",trvec2tform([-0.05 0 0]),1)
    updateGeometry(capsIRB,"tool0",[.1 0.01],1)

    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:



    • 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.

    Extended Capabilities

    Version History

    Introduced in R2022b