show

Display ego bodies and obstacles in environment

Since R2020b

Syntax

ax = show(capsuleListObj)

ax = show(capsuleListObj,Name,Value)

Description

ax = show(capsuleListObj) displays the initial state of all ego bodies and obstacles in the specified capsule list, and returns the axes handle of the plot.

ax = show(capsuleListObj,Name,Value) specifies options using name-value pair arguments. For example, 'FastUpdate',true enables fast updates to an existing plot.

Examples

Build Ego Body Paths and Check for Collisions with Obstacles

Build an ego body path and maintain obstacle states using the dynamicCapsuleList object. Visualize the states of all objects in the environment at different timestamps. Validate the path of the ego body by checking for collisions with obstacles in the environment.

Create the dynamicCapsuleList object. Extract the maximum number of steps to use as the number of time stamps for your object paths.

obsList = dynamicCapsuleList;
numSteps = obsList.MaxNumSteps;

Add Ego Body

Define an ego body by specifying the ID, geometry, and state together in a structure. The capsule geometry has a length of 3 m and radius of 1 m. Specify the state as a linear path from x = 0m to x = 100m.

egoID1 = 1;
geom = struct("Length",3,"Radius",1,"FixedTransform",eye(3));
states = linspace(0,1,obsList.MaxNumSteps)'.*[100 0 0];

egoCapsule1 = struct('ID',egoID1,'States',states,'Geometry',geom);
addEgo(obsList,egoCapsule1);

show(obsList,"TimeStep",[1:numSteps]);
ylim([-20 20])

Add Obstacles

Specify states for two obstacles that are separated from the ego body by 5 m in opposite directions on the y-axis. Assume the obstacles have the same geometry geom as the ego body.

obsState1 = states + [0 5 0];
obsState2 = states + [0 -5 0];

obsCapsule1 = struct('ID',1,'States',obsState1,'Geometry',geom);
obsCapsule2 = struct('ID',2,'States',obsState2,'Geometry',geom);

addObstacle(obsList,obsCapsule1);
addObstacle(obsList,obsCapsule2);

show(obsList,"TimeStep",[1:numSteps]);
ylim([-20 20])

Update Obstacles

Alter your obstacle locations and geometry dimensions over time. Use the previously generated structure, modify the fields, and update the obstacles using the updateObstacleGeometry and updateObstaclePose object functions. Reduces the radius of the first obstacle to 0.5 m, and change the path to move it towards the ego body.

obsCapsule1.Geometry.Radius = 0.5;

obsCapsule1.States = ...
    [linspace(0,100,numSteps)' ... % x
     linspace(5,-4,numSteps)' ... % y 
     zeros(numSteps,1)]; % theta

updateObstacleGeometry(obsList,1,obsCapsule1);
updateObstaclePose(obsList,1,obsCapsule1);

Check for Collisions

Visualize the new paths. Show where collisions between the ego body and an obstacle, which the display highlights in red. Notice that collisions between the obstacles are not checked.

show(obsList,"TimeStep",[1:numSteps],"ShowCollisions",1);
ylim([-20 20])
xlabel("X (m)")
ylabel("Y (m)")

Programmatically check for collisions by using the checkCollision object function. The function returns a vector of logical values that indicates the status of each time step. The vector is transposed for display purposes.

collisions = checkCollision(obsList)'

collisions = 1×31 logical array

   0   0   0   0   0   0   0   0   0   0   0   0   1   1   1   1   1   1   1   1   1   1   0   0   0   0   0   0   0   0   0

To validate paths with a large number of steps, use the any function on the vector of collision values.

if any(collisions)
    disp("Collision detected.")
end

Collision detected.

Update Ego Path

Specify a new path for the ego body. Visualize the paths again, displaying collisions.

egoCapsule1.States = ...
    [linspace(0,100,numSteps)' ... % x
    3*sin(linspace(0,2*pi,numSteps))' ... % y
    zeros(numSteps,1)]; % theta

updateEgoPose(obsList,1,egoCapsule1);

show(obsList,"TimeStep",[1:numSteps],"ShowCollisions",1);
ylim([-20 20])

Input Arguments

capsuleListObj — Dynamic capsule list

dynamicCapsuleList object | dynamicCapsuleList3D object

Dynamic capsule list, specified as a dynamicCapsuleList or dynamicCapsuleList3D object.

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: 'FastUpdate',true enables the option for fast updates in an existing plot.

Parent — Parent axes to plot on

gca (default) | Axes handle

Parent axes to plot on, specified as the comma-separated pair consisting of 'Parent' and an Axes Properties handle.

FastUpdate — Perform fast update to existing plot

false or 0 (default) | true or 1

Perform a fast update to an existing plot, specified as the comma-separated pair consisting of 'FastUpdate' and a logical 0 (false) or 1 (true). You must use the show object function to initially display your capsule list before you can specify it with this argument.

Data Types: logical

TimeStep — Time steps to display

1 (default) | numeric vector

Time steps to display, specified as the comma-separated pair consisting of 'TimeStep' and numeric vector of values in the range [1, N], where N is the value of the MaxNumSteps property of the object specified in the capsuleListObj argument. Each time step corresponds to a row of the state matrix for each ego body and obstacle.

ShowCollisions — Check for and highlight collisions in display

false or 0 (default) | true or 1

Check for and highlight collisions in the display, specified as the comma-separated pair consisting of 'ShowCollisions' and a logical 0 (false) or 1 (true).

Data Types: logical

EgoIDs — Ego IDs to display

vector of positive integers

Ego IDs to display, specified as the comma-separated pair consisting of 'EgoIDs' and a vector of positive integers. By default, the object function displays all ego bodies.

ObstacleIDs — Obstacle IDs to display

vector of positive integers

Obstacle IDs to display, specified as the comma-separated pair consisting of 'ObstacleIDs' and a vector of positive integers. By default, the function displays all obstacles.

Output Arguments

ax — Parent axes of dynamic capsule list plot

Axes handle

Parent axes of the dynamic capsule list plot, returned as an Axes Properties handle.

Extended Capabilities

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

Version History

Introduced in R2020b