updateMesh

Update robot platform body mesh

Since R2022a

Syntax

updateMesh(platform,type,Name=Value)

Description

updateMesh(platform,type,Name=Value) updates the body mesh of the robot platform with the specified mesh type and specifies additional options using one or more 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

Perform Pick and Place in Robot Scenario

Create a robotScenario object.

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

Create a rigidBodyTree object of the Franka Emika Panda manipulator using loadrobot.

robotRBT = loadrobot("frankaEmikaPanda");

Create a rigidBodyTree-based robotPlatform object using the manipulator model.

robot = robotPlatform("Manipulator",scenario, ...
                      RigidBodyTree=robotRBT);

Create a non-rigidBodyTree-based robotPlatform object of a box to manipulate. Specify the mesh type and size.

box = robotPlatform("Box",scenario,Collision="mesh", ...
                    InitialBasePosition=[0.5 0.15 0.278]);
updateMesh(box,"Cuboid",Collision="mesh",Size=[0.06 0.06 0.1])

Visualize the scenario.

ax = show3D(scenario,Collisions="on");
view(79,36)
light

Specify the initial and the pick-up joint configuration of the manipulator, to move the manipulator from its initial pose to close to the box.

initialConfig = homeConfiguration(robot.RigidBodyTree);
pickUpConfig = [0.2371 -0.0200 0.0542 -2.2272 0.0013 ...
                2.2072 -0.9670 0.0400 0.0400];

Create an RRT path planner using the manipulatorRRT object, and specify the manipulator model.

planner = manipulatorRRT(robot.RigidBodyTree,scenario.CollisionMeshes);
planner.IgnoreSelfCollision = true;

Plan the path between the initial and the pick-up joint configurations. Then, to visualize the entire path, interpolate the path into small steps.

rng("default")
path = plan(planner,initialConfig,pickUpConfig);
path = interpolate(planner,path,25);

Set up the simulation.

setup(scenario)

Check the collision before manipulator picks up the box.

checkCollision(robot,"Box", ...
               IgnoreSelfCollision="on")

ans = logical
   0

Move the joints of the manipulator along the path and visualize the scenario.

helperRobotMove(path,robot,scenario,ax)

Check the collision after manipulator picks up the box.

checkCollision(robot,"Box", ...
               IgnoreSelfCollision="on")

ans = logical
   1

Use the attach function to attach the box to the gripper of the manipulator.

attach(robot,"Box","panda_hand", ...
       ChildToParentTransform=trvec2tform([0 0 0.1]))

Specify the drop-off joint configuration of the manipulator to move the manipulator from its pick-up pose to the box drop-off pose.

dropOffConfig = [-0.6564 0.2885 -0.3187 -1.5941 0.1103 ...
                 1.8678 -0.2344 0.04 0.04];

Plan the path between the pick-up and drop-off joint configurations.

path = plan(planner,pickUpConfig,dropOffConfig);
path = interpolate(planner,path,25);

Move the joints of the manipulator along the path and visualize the scenario.

helperRobotMove(path,robot,scenario,ax)

Use the detach function to detach the box from the manipulator gripper.

detach(robot)

Plan the path between the drop-off and initial joint configurations to move the manipulator from its box drop-off pose to its initial pose.

path = plan(planner,dropOffConfig,initialConfig);
path = interpolate(planner,path,25);

Move the joints of the manipulator along the path and visualize the scenario.

helperRobotMove(path,robot,scenario,ax)

Helper function to move the joints of the manipulator.

function helperRobotMove(path,robot,scenario,ax)
    for idx = 1:size(path,1)
        jointConfig = path(idx,:);
        move(robot,"joint",jointConfig)
        show3D(scenario,fastUpdate=true,Parent=ax,Collisions="on");
        drawnow
        advance(scenario);
    end
end

Input Arguments

platform — Robot platform in scenario

robotPlatform object

Robot platform in the scenario, specified as a robotPlatform object.

type — Type of mesh

"Cuboid" | "GroundVehicle" | "RigidBodyTree" | "Custom"

Type of mesh, specified as "Cuboid", "GroundVehicle", "RigidBodyTree", or "Custom".

Data Types: char | string

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: Scale=2 specifies the scale of the ground vehicle robot platform mesh as 2.

Position — Relative mesh position in body frame

[0 0 0] (default) | vector of form [x y z]

Relative mesh position in the body frame, specified as a vector of the form [x y z] in meters.

Data Types: single | double

Orientation — Relative mesh orientation in body frame

[1 0 0 0] (default) | vector of form [w x y z] | quaternion object

Relative mesh orientation in the body frame, specified as a quaternion vector of the form [w x y z] or a quaternion object.

Data Types: single | double

Offset — Transformation of mesh relative to body frame

4-by-4 homogeneous transformation matrix

Transformation of mesh relative to the body frame, specified as a 4-by-4 homogeneous transformation matrix. The matrix maps points in the platform mesh frame to points in the body frame.

Data Types: single | double

Color — Robot platform body mesh color

[1 0 0] (default) | RGB triplet

Robot platform body mesh color, specified as a RGB triplet, except for the rigid body mesh.

Data Types: single | double

Faces — Faces of custom robot platform mesh

N-by-3 matrix of positive integers

Faces of the custom robot platform mesh, specified as an N-by-3 matrix of positive integers. The three elements in each row are the indices of the three points in the vertices forming a triangle face. N is the number of faces.

Data Types: single | double

Vertices — Vertices of custom robot platform mesh

N-by-3 matrix of real scalars

Vertices of the custom robot platform mesh, specified as an N-by-3 matrix of real scalars. The first, second, and third element of each row represents the x-, y-, and z-position of each vertex, respectively. N is the number of vertices.

Data Types: single | double

Size — Size of cuboid robot platform mesh

[1 0.5 0.3] (default) | vector of form [xlength ylength zlength]

Size of the cuboid robot platform mesh, specified as a vector of the form [xlength ylength zlength] in meters.

Data Types: single | double

Scale — Scale of ground vehicle robot platform mesh

1 (default) | scalar

Scale of the ground vehicle robot platform mesh, specified as a scalar. Scale is unitless.

Data Types: single | double

Object — Rigid body tree robot platform

[] (default) | rigidBodyTree object

Rigid body tree robot platform, specified as a rigidBodyTree object.

IsBinaryOccupied — Occupied state of binary occupancy map

false (default) | true

Occupied state of binary occupancy map, specified as true or false. Set the value as true if robot platform is incorporated in the binary occupancy map.

Data Types: logical

Collision — Collision object to add to platform mesh

"default" (default) | false | "mesh" | "capsule" | collisionBox object | collisionCapsule object | collisionCylinder object | collisionMesh object | collisionSphere object

Collision object to add to the platform mesh, specified as one of these values:

• false — Keeps the platform mesh collision-object-free. Clears any existing collision object from the rigidBodyTree-based platform mesh.

• "default" — Keeps the existing collision mesh for the rigidBodyTree-based platform. For other platforms, keeps the platform mesh collision-object-free.

• "mesh" — Fits a collision object, such as collisionBox, collisionCylinder, collisionMesh, or collisionSphere, based on the platform mesh type.

• "capsule" — Fits a collision capsule object to the platform mesh.

• One of these externally created collision objects:

  • collisionBox

  • collisionCapsule

  • collisionCylinder

  • collisionMesh

  • collisionSphere

The rigidBodyTree-based platform accepts an externally created collision mesh for only the base body.

Data Types: logical | char | string

CollisionOffset — Transformation of collision mesh relative to platform mesh

eye(4) (default) | 4-by-4 homogeneous transformation matrix

Transformation of the collision mesh relative to the platform mesh, specified as a 4-by-4 homogeneous transformation matrix. Use the CollisionOffset input for rigidBodyTree-based platforms only when specifying the Collision input as an externally created collision object.

Data Types: single | double

Version History

Introduced in R2022a