show3D

Visualize robot scenario in 3-D

Since R2022a

Syntax

[ax,plottedFrames] = show3D(scenario)

[ax,plottedFrames] = show3D(scenario,time)

[ax,plottedFrames] = show3D(___,Name=Value)

Description

[ax,plottedFrames] = show3D(scenario) visualizes latest states of the platforms and sensors in the robot scenario scene along with all static meshes. The function also returns the axes on which the scene is plotted and the frames on which each object is plotted.

[ax,plottedFrames] = show3D(scenario,time) visualizes the robot scenario at the specified time.

[ax,plottedFrames] = show3D(___,Name=Value) specifies additional options using name-value arguments.

Examples

Create and Simulate Robot Scenario

Create a robot scenario.

scenario = robotScenario(UpdateRate=100,StopTime=1);

Add the ground plane and a box as meshes.

addMesh(scenario,"Plane",Size=[3 3],Color=[0.7 0.7 0.7]);
addMesh(scenario,"Box",Size=[0.5 0.5 0.5],Position=[0 0 0.25], ...
        Color=[0 1 0])

Create a waypoint trajectory for the robot platform using an ENU reference frame.

waypoint = [0 -1 0; 1 0 0; -1 1 0; 0 -1 0];
toa = linspace(0,1,length(waypoint));
traj = waypointTrajectory("Waypoints",waypoint, ...
                          "TimeOfArrival",toa, ...
                          "ReferenceFrame","ENU");

Create a rigidBodyTree object of the TurtleBot 3 Waffle Pi robot with loadrobot.

robotRBT = loadrobot("robotisTurtleBot3WafflePi");

Create a robot platform with trajectory.

platform = robotPlatform("TurtleBot",scenario, ...
                         BaseTrajectory=traj);

Set up platform mesh with the rigidBodyTree object.

updateMesh(platform,"RigidBodyTree",Object=robotRBT)

Create an INS sensor object and attach the sensor to the platform.

ins = robotSensor("INS",platform,insSensor("RollAccuracy",0), ...
                  UpdateRate=scenario.UpdateRate);

Visualize the scenario.

[ax,plotFrames] = show3D(scenario);
axis equal
hold on

In a loop, step through the trajectory to output the position, orientation, velocity, acceleration, and angular velocity.

count = 1;
while ~isDone(traj)
    [Position(count,:),Orientation(count,:),Velocity(count,:), ...
     Acceleration(count,:),AngularVelocity(count,:)] = traj();
    count = count+1;
end

Create a line plot for the trajectory. First create the plot with plot3, then manually modify the data source properties of the plot. This improves the performance of the plotting.

trajPlot = plot3(nan,nan,nan,"Color",[1 1 1],"LineWidth",2);
trajPlot.XDataSource = "Position(:,1)";
trajPlot.YDataSource = "Position(:,2)";
trajPlot.ZDataSource = "Position(:,3)";

Set up the simulation. Then, iterate through the positions and show the scene each time the INS sensor updates. Advance the scene, move the robot platform, and update the sensors.

setup(scenario)
for idx = 1:count-1
    % Read sensor readings.
    [isUpdated,insTimestamp(idx,1),sensorReadings(idx)] = read(ins);
    if isUpdated
        % Use fast update to move platform visualization frames.
        show3D(scenario,FastUpdate=true,Parent=ax);
        % Refresh all plot data and visualize.
        refreshdata
        drawnow limitrate
    end
    % Advance scenario simulation time.
    advance(scenario);
    % Update all sensors in the scene.
    updateSensors(scenario)
end
hold off

Input Arguments

scenario — Robot scenario

robotScenario object

Robot scenario, specified as a robotScenario object.

time — Time stamp

nonnegative scalar

Time stamp at which to show the scenario, specified as a nonnegative scalar. The time stamp must already be saved in the scenario. To change the number of saved time stamps, use the HistoryBufferSize property of the robotScenario object, scenario.

Data Types: single | double

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.

Example: show3D(scenario,Parent=ax)

Parent — Parent axes for plotting

axes object | uiaxes object

Parent axes for plotting, specified as an axes object or a uiaxes object.

FastUpdate — Enable updating from previous map

false (default) | true

Enable updating from previous map, specified as true or false. When specified as true, the function plots the map via a lightweight update to the previous map in the figure. When specified as false, the function plots the whole scene on the figure every time.

Note

Parent axes must be specified to perform fast update.

Example: FastUpdate=true

Data Types: logical

View — View point of plot

"3D" (default) | "Top" | "Side"

View point of plot, specified as "3D", "Top", or "Side".

Example: View="Side"

Data Types: string | char

Visuals — Display body visual meshes

"on" (default) | "off"

Display body visual meshes, specified as "on" or "off".

Example: Visuals="off"

Data Types: char | string

Collisions — Display body collision geometries

"off" (default) | "on"

Display body collision geometries, specified as "on" or "off".

Example: Collisions="on"

Data Types: char | string

CollisionMeshAlpha — Collision mesh transparency

0.3 (default) | numeric scalar in the range [0,1]

Collision mesh transparency, specified as a numeric scalar in the range [0,1]. A value of 0 means transparent. A value of 1 means opaque. Values between 0 and 1 are partially transparent.

Example: CollisionMeshAlpha=0.5

Data Types: single | double

Output Arguments

ax — Axes on which scenario is plotted

axes object | uiaxes object

Axes on which the scenario is plotted, returned as an axes object or a uiaxes object.

plottedFrames — Plotted frame information

structure

Plotted frame information, returned as a structure of hgtransform objects.

Version History

Introduced in R2022a