generateRobotWorkspace

Generate reachable workspace of robot in environment

Since R2024b

Syntax

[workspace,configs] = generateRobotWorkspace(robot,environment)

[workspace,configs] = generateRobotWorkspace(robot,environment,eeName)

[___] = generateRobotWorkspace(___,Name=Value)

Description

[workspace,configs] = generateRobotWorkspace(robot,environment) generates the reachable workspace, as end-effector coordinates and their corresponding joint configurations, for a specified robot in the specified environment. This syntax uses the last rigid body in the robot model as the end effector.

[workspace,configs] = generateRobotWorkspace(robot,environment,eeName) specifies the rigid body to use as the end effector.

[___] = generateRobotWorkspace(___,Name=Value) specifies options using one or more name-value arguments in addition to any combination of arguments from previous syntaxes. For example, MaxNumSamples=1500 sets the maximum number of configurations to sample to 1500.

Examples

Plot Workspace of Robot Manipulator

Load the robot model for the Universal Robots UR5e manipulator, and create a collision environment consisting of a workbench, a barrier, floor, and mount for the robot.

robot = loadrobot("universalUR5e",DataFormat="row");
env = exampleHelperCreateWorkbench(0.4,1.5,0.05,[0.5 0.0 0.1]);

Show the collision environment and then plot the robot manipulator in a configuration over the workbench.

showCollisionArray(env);
hold on
show(robot,[0 -pi/3 pi/3 2*pi pi/2 0]);

Generate the workspace for the robot in the collision environment.

rng default
[ws,configs] = generateRobotWorkspace(robot,env);

Plot the workspace as an alpha shape.

wsAlpha = alphaShape(ws(:,1),ws(:,2),ws(:,3));
a = plot(wsAlpha,FaceAlpha=0.45,EdgeColor="none");
title("Robot Workspace in Specified Environment")
hold off

Identify Workspace Regions with High Manipulability

Load the robot model for the Universal Robots UR5e manipulator, and specify the last body in the robot model "tool0" as the end effector.

robot = loadrobot("universalUR5e",DataFormat="row");
show(robot);
ee = "tool0";

Generate the workspace for the robot in an obstacle-free environment, using "tool0" as the end effector of the robot model, and ignoring self-collisions in the robot model during collision checking.

rng default
[workspace,configs] = generateRobotWorkspace(robot,{},ee,IgnoreSelfCollision="on");

Calculate the manipulability, using Yoshikawa index, for each configuration in the workspace.

mIdx = manipulabilityIndex(robot,configs,ee);

Show the robot, and then plot the workspace analysis. Voxelize the workspace to make it easier to see the high-manipulability areas.

hold on
showWorkspaceAnalysis(workspace,mIdx,Voxelize=true)
axis auto
title("Voxelized Manipulability-Encoded Workspace")
hold off

Get the configurations with a manipulability index greater than 0.1.

highMIdxConfigs = configs(mIdx>0.1,:)

highMIdxConfigs = 105×6

    3.9154    0.4125   -0.9379    5.5167    4.7242    0.6303
    1.0622    4.1458   -1.3166   -1.2245    4.5497    1.4419
   -5.7293    2.3464    1.4688   -0.7895   -1.5100    6.0276
    3.2651   -2.6273   -1.3984   -6.2064   -1.5744   -0.7925
   -2.4593   -2.6281   -1.6178    5.4875    4.5263   -1.2915
   -2.7437   -0.2400    1.1615   -3.6661    1.3592   -2.1843
    1.2724   -2.2470   -1.3553   -0.8128    5.0738    5.3420
   -1.1097    3.6946   -0.9852   -0.4699   -1.6610    2.2566
   -2.1939    0.6961   -1.2854   -1.6824   -1.8969    1.6364
    2.7559    0.2960   -1.5027   -0.0870    4.4716    2.8200
    3.5406    3.8625   -1.4762    4.9750    1.3570   -6.1022
   -2.0595    5.6969    1.5740   -2.0870    1.6692   -1.0613
   -0.0951    3.1191   -1.1879   -6.1864    1.4529   -1.7898
   -3.9272   -2.4752   -1.1262   -0.7288   -1.7356    1.5783
   -4.2214    2.3661    0.9005    4.0382   -1.5262   -4.8770
      ⋮

Input Arguments

robot — Robot model

rigidBodyTree object

Robot model, specified as a rigidBodyTree object.

environment — Collision environment

P-element cell array of collision objects

Collision environment, specified as a P-element cell array of collision objects. A collision object is any of these objects:

• collisionBox

• collisionCapsule

• collisionCylinder

• collisionMesh

• collisionSphere

P is the total number of obstacles in the environment.

eeName — Name of end effector

string scalar | character vector

Name of the end effector, specified as a string scalar or character vector. The robot model specified by robot must contain a body with this name.

By default, the last body of robot is the end effector.

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: generateRobotWorkspace(robot,env,MaxNumSamples=1500,SkippedSelfCollisions="adjacent") sets the maximum number of configurations to sample to 1500, and does not check body pairs with adjacent indices for self-collisions.

MaxNumSamples — Maximum number of joint configurations to sample

10000 (default) | positive integer

Maximum number of joint configurations to sample in the state space of the robot, specified as a positive integer.

Note

The MaxNumSamples argument does not directly correspond to the actual count of generated configurations and workspace points in the configs and workspace output arguments. The actual count is less than MaxNumSamples, as it excludes configurations that generateRobotWorkspace determines would put the robot in collision with itself or the environment.

Example: generateRobotWorkspace(robot,env,MaxNumSamples=1500)

SkippedSelfCollisions — Body pairs skipped for checking self-collisions

"parent" (default) | "adjacent" | p-by-2 cell array of character vectors

Body pairs skipped for checking self-collisions, specified as "parent", "adjacent", or a p-by-2 cell array of character vectors:

• "parent" — Skip collision checking between child and parent bodies. See Skip Self-Collision Checking Between Parent and Adjacent Bodies for more information.

• "adjacent" — Skip collision checking between bodies on adjacent indices. See Skip Self-Collision Checking Between Parent and Adjacent Bodies for more information.

• p-by-2 cell array of character vectors — Skip collision checking between specific body pairs. Each row specifies a pair of body names between which to skip self-collision checking. p is the number of body pairs to skip for self-collision checking. For more information, see Skip Self-Collision Checking Between Specific Body Pairs.

Data Types: char | string

IgnoreSelfCollision — Skip checking for robot self-collisions

"off" (default) | "on"

Skip checking for robot self-collisions, specified as either "on" or "off". When this argument is enabled, the function ignores collisions between the collision objects of the rigid body tree robot model bodies and other collision objects of the same model or its base.

Data Types: char | string

Output Arguments

workspace — Workspace as end-effector coordinates

M-by-3 matrix

Workspace as end-effector coordinates, returned as an M-by-3 matrix. M is the total number of end-effector coordinates, and calculated as the value of MaxNumSamples minus the number of sampled configurations that result in collisions.

configs — Joint configurations of corresponding end-effector coordinates

M-by-N matrix

Joint configurations of the corresponding end-effector coordinates, returned as an M-by-N matrix. M is the total number of joint configurations corresponding to the workspace end-effector coordinates, and calculated as the value of MaxNumSamples minus the number of sampled configurations that result in collisions. N is the total number of nonfixed joints in the robot model.

Extended Capabilities

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

Version History

Introduced in R2024b