sim3d.graphics.Text

Create text actor

Since R2024a

Description

Use the sim3d.graphics.Text object to create an actor object with N number of text elements in the 3D environment for annotation and displaying relevant information data during simulation. After you create a sim3d.graphics.Text object, you can modify the aspects of the text actor by setting property values.

Creation

Syntax

text = sim3d.graphics.Text()

text = sim3d.graphics.Text(Name=Value)

Description

text = sim3d.graphics.Text() creates a default text actor object in the 3D environment.

text = sim3d.graphics.Text(Name=Value) specifies options using one or more name-value arguments. For example, to create a text actor at the position (0,1,1), set Translation to [0 1 1].

Input Arguments

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: text = sim3d.graphics.Text(ActorName='Text',Translation=[0 1 1],Color=[1 1 0],String="Hello") creates an actor object with one text element, the specified actor name, position, color, and string.

Example: texts = sim3d.graphics.Text(ActorName='Texts',Translation=[0 -1 1; 0 0 1; 0 1 1],Color=[1 1 0; 1 0 0; 0 1 0],String=["Hello"; "3D"; "World"]) creates an actor object with three text elements by specifying the actor name and setting the positions, colors, and texts to display.

ActorName — Name of actor

autogenerated name (default) | character array | string

Name of actor, specified as a character array or string. If you do not specify an actor name, then the software assigns the actor an autogenerated name. Use this argument to set the name of the sim3d.graphics.Text object.

Note

If you specify the same name as an actor that already exists, then the software appends actor name you specify with a unique identifier.

Translation — Relative translation

[0 0 0] (default) | real N-by-3 array

Relative translation (x,y,z) of the actor object to its parent actor, specified as a real N-by-3 array, in m. N specifies the number of elements created using the sim3d.graphics.Text object. When you add an actor to the 3D environment, the default parent actor is the Scene Origin at (0,0,0).

Example: Translation=[3 4 3]

Example: Translation=[3 2 3; 3 5 3; 3 3 3]

Data Types: double

Rotation — Relative rotation

[0 0 0] (default) | real N-by-3 array

Relative rotation (roll, pitch, yaw) of the actor object to its parent actor, specified as a real N-by-3 array, in rad.

Example: Rotation=[0 pi/2 -pi/4]

Example: Rotation=[0 pi/2 -pi/4; 0 pi/2 -pi/4; 0 pi/2 -pi/4]

Data Types: double

Color — Base color of actor

[1 0 0] (default) | real N-by-3 array

Base color of actor, specified as real N-by-3 array of RGB triplet values. An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0, 1].

Example: Color=[0 1 0]

Example: Color=[1 0 0; 0 0 1; 1 1 0]

Data Types: double

String — Text to display

" " (default) | string N-by-1 vector

Text to display in 3D environment, specified as string N-by-1 vector. The default value is an empty string "".

Example: String="Hello"

Example: String=["Hello"; "3D"; "World"]

Data Types: string

FontSize — Horizontal and vertical scale of text

1 (default) | real positive N-by-1 vector

Horizontal and vertical scale of text, specified as real positive N-by-1 vector. The default value 1 represents the original size of the text. A value greater than or less than 1 increases or decreases the size of the text, respectively.

Example: FontSize=2

Example: FontSize=[1.5; 1.5; 1.5]

Data Types: double

Hidden — Option to hide actor

0 or false (default) | 1 or true | logical N-by-1 vector

Option to hide the actor from the 3D environment scene, specified as 0 (false) if the actor is visible in the scene or 1 (true) if the actor is hidden in the scene. For N number of elements, specify as a logical N-by-1 vector.

Example: Hidden=1

Example: Hidden=[1; 0; 1]

Properties

Parent — Parent of actor

handle to parent actor object

Parent of actor, specified as a handle to the parent actor object. After you add an actor to the sim3d.World object, the default parent actor is the Scene Origin at (0,0,0). Use this property to set any actor in the 3D environment as the parent actor of a sim3d.graphics.Text object.

Children — Children of actor

structure

This property is read-only.

Children of actor, specified as a structure. Each field of the structure contains a handle to the child of a sim3d.graphics.Text object.

ParentWorld — Parent world

handle to parent world object

Parent world, specified as a handle to the parent sim3d.World object. You can use this property only if the sim3d.graphics.Text object is added to the parent sim3d.World object.

CoordinateSystem — Actor orientation

'Default' (default) | 'MATLAB' | 'ISO8855' | 'AERO' | 'VRML' | 'SAE'

Actor orientation representation in the 3D environment, specified as one of the listed values. The values are not case-sensitive.

• 'Default' – World coordinate system

• 'MATLAB' – MATLAB^® coordinate system

• 'ISO8855' – ISO 8855 standard coordinate system

• 'AERO' – SAE coordinate system

• 'VRML' – X3D ISO standard coordinate system

• 'SAE' – SAE coordinate system

To display the actor transformation in the specified coordinate system, set this property first, and then set the transform properties Translation, Rotation, and Scale. For more details on the different coordinate systems, see Coordinate Systems in Simulink 3D Animation.

Data Types: string

Translation — Relative translation

[0 0 0] (default) | real N-by-3 array

Relative translation (x,y,z) of the actor object to its parent actor, specified as a real N-by-3 array, in m. N specifies the number of elements created using the sim3d.graphics.Text object. When you add an actor to the 3D environment, the default parent actor is the Scene Origin at (0,0,0).

Example: text.Translation = [1 2 1]

Example: texts.Translation = [1 4 2; 1 3 2; 1 2 2]

Rotation — Relative rotation

[0 0 0] (default) | real N-by-3 array

Relative rotation (roll, pitch, yaw) of the actor object to its parent actor, specified as a real N-by-3 array, in rad.

Example: text.Rotation = [0 pi/2 pi/8]

Example: texts.Rotation = [pi/2 pi/4 pi/2; 0 pi/4 pi/2; pi pi/2 0]

Color — Base color of actor

[1 0 0] (default) | real N-by-3 array

Base color of actor, specified as real N-by-3 array of RGB triplet values. An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0, 1].

Example: text.Color = [0 1 0]

Example: texts.Color = [1 0 0; 0 0 1; 1 1 0]

Data Types: double

String — Text to display

" " (default) | string N-by-1 vector

Text to display in 3D environment, specified as string N-by-1 vector. The default value is an empty string "".

Example: text.String = "Hello"

Example: texts.String = ["Hello"; "3D"; "World"]

Data Types: string

FontSize — Horizontal and vertical scale of text

1 (default) | real positive N-by-1 vector

Horizontal and vertical scale of text, specified as real positive N-by-1 vector. The default value 1 represents the original size of the text. A value greater than or less than 1 increases or decreases the size of the text, respectively.

Example: text.FontSize = 2

Example: texts.FontSize = [3; 3; 3]

Data Types: double

Hidden — Option to hide actor

0 or false (default) | 1 or true | logical N-by-1 vector

Option to hide the actor from the 3D environment scene, specified as 0 (false) if the actor is visible in the scene or 1 (true) if the actor is hidden in the scene. For N number of elements, specify as a logical N-by-1 vector.

Example: text.Hidden = 1

Example: texts.Hidden = [1; 0; 1]

Examples

Create Annotations Using MATLAB

Create arrows and text labels in the 3D environment. First, create a box actor. Then, create arrows and text label objects and attach them to the actor. Finally, view the annotated actor in the Simulation 3D Viewer window.

Create 3D Environment

Create a world object using sim3d.World.

world = sim3d.World();

Create Actor

Create a box actor in the 3D environment using the sim3d.Actor object and add the box actor to the world.

box = sim3d.Actor(ActorName='Box');
createShape(box,'box',[0.5 0.5 0.5]);
box.Color = [1 1 0];
add(world,box);

Create Arrows

Create three arrows using the sim3d.graphics.Arrow object and set the ActorName of the object. To position the arrows in the 3D environment, set the Translation argument with a 3-by-3 array value. Set the Rotation and Color properties for each arrow and add the object to the world.

arrows = sim3d.graphics.Arrow( ...
    ActorName='Arrows', ...
    Translation=[0.25 0 0; 0 0.25 0; 0 0 0.25]);
arrows.Rotation = [0 0 0; 0 0 pi/2; 0 pi/2 0];
arrows.Color = [1 0 0; 0 1 0; 0 0 1];
add(world,arrows,box);

Create Text

Create three text labels using the sim3d.graphics.Text object and set the ActorName of the object. To position the text labels in the 3D environment, set the Translation argument with a 3-by-3 array value. Set the Color property of each text label and the String property with the display text. Add the object to the world.

texts = sim3d.graphics.Text( ...
    ActorName='Texts', ...
    Translation=[1.25 0 0; 0 1.25 0; 0 0 1.25]);
texts.Color = [1 0 0; 0 1 0; 0 0 1];
texts.String = ["X";"Y";"Z"];
add(world,texts,box);

Run Simulation

Set the Simulation 3D Viewer window point of view and run the simulation.

viewport = createViewport(world,Translation=[-3 4 1]);
viewport.Rotation = [0 0 -pi/4];
sampletime = 0.01;
stoptime = 5;
run(world,sampletime,stoptime);

delete(world);

Version History

Introduced in R2024a