Collision Capsule

R2026b

Create capsule collision geometry

Since R2025a

expand all in page
  • Collision Capsule block

Libraries:
Robotics System Toolbox / Collision Detection

Description

The Collision Capsule block outputs a capsule primitive collision geometry defined by a radius and length, with the central line segment of the capsule aligning with its z-axis. The origin of the body-fixed frame is located at the midpoint of the central line segment.

Examples

expand all

Open Live Script

Open the Simulink® model. This model contains all five of the collision geometry blocks in the Collision Detection library and checks for collision between any two of the collision geometries. Note that the Collision Mesh block uses vertices from the exampleMeshVertices MAT file. The model loads the exampleMeshVertices MAT file when you open the model by using the PreLoadFcn callback. 

model = "CollisionCheckingBetweenGeometries.slx";
open_system(model)

Simulate the model.

out = sim("CollisionCheckingBetweenGeometries.slx")
out = 
  Simulink.SimulationOutput:

             collStatus: [1x1 timeseries] 
               geom1Idx: [1x1 timeseries] 
               geom2Idx: [1x1 timeseries] 
                logsout: [1x1 Simulink.SimulationData.Dataset] 
                sepDist: [1x1 timeseries] 
                   tout: [101x1 double] 
             witnessPts: [1x1 timeseries] 

     SimulationMetadata: [1x1 Simulink.SimulationMetadata] 
           ErrorMessage: [0x0 char]

Get data from the simulation output.

collCheckingPairs = [out.geom1Idx.Data out.geom2Idx.Data];
collStatuses = out.collStatus.Data;
sepDistances = out.sepDist.Data;
witnessPoints = out.witnessPts.Data;

Ports

Input

expand all

Radius of the spherical ends of the capsule, specified as a positive scalar. Units are in meters.

Length of the central line segment of the capsule, specified as a nonnegative scalar. Units are in meters.

Note

This is not the length from end-to-end of the capsule. The total length of the capsule is Length + 2*Radius.

Pose of the collision geometry relative to the world frame, specified as a 4-by-4 homogeneous matrix.

Output

expand all

Collision geometry, returned as a bus slCollision with these elements:

  • m_Type — Type of collision geometry:

    • 0 — Collision Box

    • 1 — Collision Cylinder

    • 2 — Collision Sphere

    • 3 — Collision Capsule

    • 4 — Collision Mesh

  • m_X — x-dimension size of the collision geometry in meters.

  • m_Y — y-dimension size of the collision geometry in meters.

  • m_Z — z-dimension size of the collision geometry in meters.

  • m_Radius — Radius of the collision geometry in meters.

  • m_Height — Height of the collision geometry in meters.

  • m_Vertices — Vertices of the collision geometry in local frame.

  • m_Position — xyz-position of the collision geometry in meters.

  • m_Quaternion — Orientation of the collision geometry described as a quaternion.

To perform collision checking, connect this output to a Check Collision block as input.

Validity of collision capsule dimensions, returned as an integer scalar where each digit represents the validity of a dimension:

  • First Digit — Validity of the radius at Radius port.

  • Second Digit — Validity of the length at Length port.

Each of these digits can be one of these values:

  • 4 — Specified dimension value is not numeric.

  • 3 — Specified dimension value is not a real number.

  • 2 — Specified dimension value is nonfinite.

  • 1 — Specified radius is not positive, or the specified length is negative.

  • 0 — Specified dimension value is valid.

For example, if the exit flag is 10, then the radius of the capsule is invalid because it is not positive.

To validate dimensions at runtime instead, select the Enable Runtime Input Dimensions Error parameter.

Data Types: uint16

Parameters

expand all

To edit block parameters interactively, use the Property Inspector. From the Simulink® Toolstrip, on the Simulation tab, in the Prepare gallery, select Property Inspector.

Select this parameter to enable runtime validation of the collision capsule dimensions and return an error if either Radius or Length is invalid.

If you clear this parameter, the block does not error during simulation, and instead uses the ExitFlag port to identify invalid capsule dimensions.

  • Code generation — Simulate model using generated C code. The first time you run a simulation, Simulink generates C code for the block. The block reuses the C code for subsequent simulations, as long as the model does not change.

  • Interpreted execution — Simulate model using the MATLAB® interpreter. For more information, see Interpreted Execution vs. Code Generation (Simulink).

Programmatic Use: Add Block

To add the block programmatically, use the add_block function with one of these library block paths as the source.

"robotslcollision/Collision Capsule"

Example: add_block("robotslcollision/Collision Capsule","myModel/myBlock",MakeNameUnique="on")

More About

expand all

Extended Capabilities

expand all

Version History

Introduced in R2025a

See Also

Objects

Blocks