addVisual

Add visual geometry data to rigid body

Syntax

addVisual(body,type,parameters)

addVisual(___,Name=Value)

addVisual(___,tform)

Description

addVisual(body,type,parameters) adds the visuals of a geometry of the specified type type and geometric parameters parameters to the specified rigid body body.

addVisual(___,Name=Value) specifies additional options using one or more name-value pair arguments. Specify name-value pair arguments after all other input arguments.

addVisual(___,tform) specifies a homogeneous transformation for the geometry visual relative to the body frame in addition to any combination of input arguments from previous syntaxes.

Examples

Create and Modify Visual Meshes for Rigid Body Tree Robot Model

Create a rigid body tree robot model.

rbt = rigidBodyTree();

Add a body to the base of the robot.

body1 = rigidBody('Link1');

Add a red visual box mesh to Link1 body with FaceAlpha set to 0.5 for 50% transparency. Add another visual box mesh and set the color to green and transparency to 20%.

Use trvec2tform function to define the position of each box.

boxdims = [0.1,0.1,0.1];

pose = trvec2tform([0,0,-0.2]);
addVisual(body1, 'Box', boxdims, pose, FaceColor=[1 0 0], FaceAlpha=0.5);

pose = trvec2tform([0,0,0.2]);
addVisual(body1, 'Box', boxdims, pose, FaceColor=[0 1 0], FaceAlpha=0.2);

Add the body 'Link1' to the robot model as a child to the robot's base.

addBody(rbt, body1, rbt.BaseName);

Visualize the robot with visual meshes.

show(rbt);

Input Arguments

body — Rigid body

rigidBody object

Rigid body, specified as a rigidBody object.

type — Geometry type for geometry

"Box" | "Cylinder" | "Capsule" | "Sphere" | "Mesh" | "RegularExtrusion" | "GeneralExtrusion" | "Ellipsoid" | "RevolvedSolid"

Geometry type for geometry, specified as one of these valid geometry type names:

Geometry Type	Shape
"Box"
"Cylinder"
"Capsule"
"Sphere"
"Mesh"
"RegularExtrusion"
"GeneralExtrusion"
"Ellipsoid"
"RevolvedSolid"

Data Types: char | string

parameters — Geometry parameters

numeric vector | numeric matrix | string scalar

Geometry parameters, specified as a numeric vector, numeric matrix, or string scalar. The type input determines the format of this value.

• "Box" — [x y z]

• "Cylinder" — [radius length]

• "Capsule" — [radius length]

• "Sphere" — radius

• "Mesh" — "meshfilename" or {'meshfilename' scale}.'meshfilename' must either be an STL or DAE file name, specified as a string or character vector. scale is the xyz-scale of the mesh's bounding box, specified as a three-element vector of positive numeric values. The scaling is along the axes of the origin frame of the rigid body.

• "RegularExtrusion" — [numberofsides outerradius length]. It represents extruded geometry with a regular polygonal cross section.

• "GeneralExtrusion" — [crosssection length]. It represents extruded geometry with an arbitrary polygonal cross-section.

  The crossection parameter is specified as a vector of N number of 2-D points where:

  • N is greater than or equal to 3.

  • No two consecutive vertices coincide, including the first and last.

  • The ordering of vertices follows a right-handed boundary traversal.

  • The cross section must avoid self-intersection.

• "Ellipsoid" — [x-radius y-radius z-radius]

• "RevolvedSolid" — crossection for fully revolved solid or [crossection revolutionangle] for partially revolved solid. The revolved solid represents a rotational sweep of a polygonal cross-section specified in the xz-plane.

  The crossection parameter is specified as a vector of N number of 2-D points where:

  • N is greater than or equal to 3.

  • No two consecutive vertices coincide, including the first and last.

  • The ordering of vertices follows a right-handed boundary traversal.

  • The cross section must avoid self-intersection.

  • The cross section must entirely lie in the closed right plane (nonnegative x coordinates).

Example: addVisual(body,"mesh",{"meshName.stl",[0.5 1 1]})

Data Types: single | double | char | string

tform — Polygon mesh transformation

string scalar | character vector | 4-by-4 homogeneous transformation

Mesh transformation relative to the body coordinate frame, specified as a frame name or 4-by-4 homogeneous transformation.

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: addVisual(body1, 'Box', boxdims, pose, FaceColor=[0 1 0], FaceAlpha=0.2)

FaceColor — Visual object color setting

[0.5 0.5 0.5] (default) | 1-by-3 matrix

Color setting of the visual object attached to the rigid body, specified as a 1-by-3 matrix of RGB values.

Data Types: row vector

FaceAlpha — Visual object transparency setting

1 (default) | nonnegative scalar

Transparency setting of the visual object attached to the rigid body, specified as a nonnegative scalar.

Data Types: scalar

Version History

Introduced in R2017b

R2025a: Integrate frame name in addVisual method

The addVisual function now accepts either a frame name or 4-by-4 homogeneous transformation in the tform input argument.

R2025a: Add new geometries as visuals in rigid body tree

Use addVisual function to add new geometries as visuals in rigid body tree robot model, such as "RegularExtrusion", "GeneralExtrusion", "Ellipsoid", and "RevolvedSolid". These primitives align with the equivalent Simscape™ solids.

R2025a: Set color and transparency of visual object

Use FaceColor and FaceAlpha to set the color and transparency of the visual object attached to the rigid body.

R2024b: Scale meshes

Specify an xyz-scale for the "mesh" geometry type using the parameters argument.

R2023a: Add visual of primitive geometries

Use the type and parameters arguments to specify primitive geometries such as a box, sphere, cylinder, and capsule.