Main Content

sim3d.Actor

Object used to define actors in the virtual world

Since R2022b

    Description

    Use the sim3d.Actor object for user-defined actors in virtual world with sim3d.World object.

    Creation

    Description

    actor = sim3d.Actor creates a default actor object that represents all items in the virtual world.

    example

    actor = sim3d.Actor(___,Name,Value) specifies additional options using one or more name-value arguments.

    Input Arguments

    expand all

    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: actor1 = sim3d.Actor('ActorName','vehicle1','Translation', [3, 4, 3], 'Rotation', [], 'Scale',[1 2 1], 'OnHit', @hitcallback)

    Name of actor, specified as a character array or string. If an actor name is not specified, then the actor is assigned an autogenerated name.

    Note

    If you specify the same name as an actor that already exists, then the actor name you specify is appended with a unique identifier to differentiate it.

    Relative translation (x,y,z) of the actor object to its parent actor, specified as a real 1-by-3 vector, in meters. Use this argument to set the Translation property of the sim3d.Actor object.

    Data Types: double

    Relative rotation (roll, pitch, yaw) of the actor object to its parent actor, specified as a real 1-by-3 vector, in radians. Use this argument to set the Rotation property of the sim3d.Actor object.

    Data Types: double

    Relative scaling in x, y and z coordinates, specified as a real 1-by-3 vector. Use this name value argument to set the Scale property of the sim3d.Actor object.

    Data Types: double

    Semantic segmentation map of object class identifiers, specified as an array.

    Custom hit event callback function handle, specified as the handle to the user-defined function such as @hitcallback. Use the function to pass the actor handle as the input argument to access sim3d.Actor properties during hit event.

    Example: function hitcallback(Actor)

    Custom begin overlap event callback function handle, specified as the handle to the user-defined function such as @beginoverlapcallback. Use the function to pass the actor handle as the input argument to access sim3d.Actor properties during begin overlap event.

    Example: function beginoverlapcallback(Actor)

    Custom end overlap event callback function handle, specified as the handle to the user-defined function such as @endoverlapcallback. Use the function to pass the actor handle as the input argument to access sim3d.Actor properties during end overlap event.

    Example: function endoverlapcallback(Actor)

    Custom click event callback function handle, specified as the handle to the user-defined function such as @clickcallback. Use the function to pass the actor handle as the input argument to access sim3d.Actor properties during click event.

    Example: function clickcallback(Actor)

    In addition to these name-value arguments, you also can specify any of the properties on this page as name-value arguments.

    Output Arguments

    expand all

    Actor object, returned as a sim3d.Actor object. A unique identifier and unique name is assigned to the actor. You can change the actor name, but the unique identifier is associated with the actor until the actor is deleted. The virtual world is composed of a hierarchical structure of actors.

    Properties

    expand all

    Base Attributes

    Structure to hold actor data, specified as a structure. You can update and maintain this data and use it to update the fields of the structure during simulation or in the setup method.

    Parent of actor, specified as a handle to the parent sim3d.Actor object. You can set this property using the Parent argument.

    This property is read-only.

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

    Parent world handle, specified as a handle to the parent sim3d.World object. You can use this property only with actors added to the world.

    Actor orientation representation in the virtual world, specified as 'Default', 'MATLAB', 'ISO8855', 'AERO', 'VRML', or 'SAE'. The values are not case sensitive. To display the actor transformation in the specified coordinate system, set this property first and then the transform properties Translation, Rotation, and Scale.

    Coordinate System Description
    'Default'

    The default coordinate system, in m and rad.

    Axes

    • X-axis points away from the viewer.

    • Y-axis points toward right.

    • Z-axis points upward.

    Rotation

    • Roll — Clockwise rotation about X-axis

    • Pitch — Clockwise rotation about Y-axis

    • Yaw — Counterclockwise rotation about Z-axis

    Three dimensional default coordinate system with X,Y,Z, Roll, Pitch, and Yaw labelled

    'MATLAB'

    The MATLAB® coordinate system, in m and rad.

    Axes

    • X-axis points away from the viewer.

    • Y-axis points toward left.

    • Z-axis points upward.

    Rotation

    • Roll — Clockwise rotation about X-axis

    • Pitch — Clockwise rotation about Y-axis

    • Yaw — Clockwise rotation about Z-axis

    Three dimensional MATLAB coordinate system with X,Y,Z, Roll, Pitch, and Yaw labelled

    'ISO8855'

    The ISO 8855 standard coordinate system, in m and deg. For more information, see ISO Standards.

    Axes

    • X-axis points away from the viewer.

    • Y-axis points toward left.

    • Z-axis points upward.

    Rotation

    • Roll — Clockwise rotation about X-axis

    • Pitch — Clockwise rotation about Y-axis

    • Yaw — Clockwise rotation about Z-axis

    Three dimensional ISO8855 coordinate system with X,Y,Z, Roll, Pitch, and Yaw labelled

    'AERO'

    The coordinate system for Aerospace applications, in m and rad. For more information, see Body Coordinates (Aerospace Blockset).

    Axes

    • X-axis points away from the viewer.

    • Y-axis points toward right.

    • Z-axis points downward.

    Rotation

    • Roll — Clockwise rotation about X-axis

    • Pitch — Clockwise rotation about Y-axis

    • Yaw — Counterclockwise rotation about Z-axis

    Three dimensional aero coordinate system with X,Y,Z, Roll, Pitch, and Yaw labelled

    'VRML'

    The X3D ISO standard coordinate system, in m and rad.

    Axes

    • X-axis points away from the viewer.

    • Y-axis points upward.

    • Z-axis points toward right.

    Rotation

    • Roll — Clockwise rotation about X-axis

    • Pitch — Counterclockwise rotation about Y-axis

    • Yaw — Counterclockwise rotation about Z-axis

    Three dimensional VRML coordinate system with X,Y,Z, Roll, Pitch, and Yaw labelled

    'SAE'

    The SAE J670 standard coordinate system, in m and rad. For more information, see SAE International Standards.

    Axes

    • X-axis points away from the viewer.

    • Y-axis points toward right.

    • Z-axis points downward.

    Rotation

    • Roll — Clockwise rotation about Y-axis

    • Pitch — Clockwise rotation about X-axis

    • Yaw — Clockwise rotation about Z-axis

    Three dimensional SAE coordinate system with X,Y,Z, Roll, Pitch, and Yaw labelled

    Cartesian coordinates for actor position in the virtual world, specified as a real 1-by-3 vector. You can set this property using the Translation argument.

    Rotation of actor in the virtual world, specified as a three element vector. You can set this property using the Rotation name value argument.

    Scale of actor used for scaling in each of three directions in the virtual world, specified as a real 1-by-3 vector. You can set this property using the Scale argument.

    Type of actor mobility to respond to physics and/or move the actor during simulation, specified as 'sim3d.utils.MobilityTypes.Movable' or 'sim3d.utils.MobilityTypes.Static'.

    Data Types: sim3d.utils.MobilityTypes

    Mesh Attributes

    Vertices of mesh geometry, specified as an N-by-3 matrix. This matrix includes the coordinates of all vertex positions to be used for the mesh geometry. Each vertex has a vertex ID equal to its row number in the matrix. N specifies the number of vertices.

    Example: actor.Vertices = [-1 -1 0; 1 -1 0; 1 1 0; -1 1 0; -1 -1 0; 1 -1 0;1 1 0;-1 1 0]

    Data Types: double

    Vertices of each triangular face, specified as an M-by-3 matrix. This matrix defines how each triangle of the mesh is drawn. The matrix specifies the vertex IDs that define each triangular face of the mesh. M is the number of triangular faces in the mesh.

    Example: actor.Faces = [0 3 2; 0 2 1; 4 6 7; 4 5 6]

    Data Types: double

    Normal vectors of each vertex, specified as an N-by-3 matrix. Each row of the matrix specifies the normal vector for a vertex. This matrix must be the same size as Vertices.

    Example: actor.Normals = [0 0 1; 0 0 1; 0 0 1; 0 0 1; 0 0 -1; 0 0 -1; 0 0 -1; 0 0 -1]

    Data Types: double

    Texture coordinates for each vertex, specified as an N-by-2 matrix. This matrix defines which point on the texture file maps to each vertices. This argument is optional and, if specified, must be the same length as Vertices.

    Example: actor.TextureCoordinates = [0 0; 0 1; 1 1; 1 0; 0 0; 0 1; 1 1; 1 0]

    Vertex colors, specified as an N-by-3 matrix. This matrix specifies the color value of each vertex in [R G B] form. This matrix must be the same length as Vertices.

    Note

    To display VertexColors along with the actor base color, set the VertexBlend property to a value greater than 0. If VertexBlend is 1, then actor displays only the VertexColors.

    Example: actor.VertexColors = [1 0 0; 0 1 0; 0 0 1; 1 0 1; 1 1 0; 0 1 1; 1 1 0; 0 1 0]

    Material Attributes

    Base color of actor, specified as a real 1-by-3 vector. Color consists of a vector of color RGB components [red green blue]. Values greater than 1 cause glowing and can be used for various indicators. If the sim3d.Actor object has a texture, the TextureMapping.Blend coefficient can be used to control how it blends with the base color.

    Example: actor.Color = [0.3 0.27 0.9]

    Transparency of actor, specified as a real positive number in the range (0,1), where 0 indicates an opaque object and 1 indicates a completely transparent object.

    Example: actor.Transparency = 0.8

    Data Types: double

    Shininess of actor, specified as a real positive number in the range (0,1), where 0 indicates a nonshiny object and 1 indicates a completely shiny object.

    Example: actor.Shininess = 0.3

    Data Types: double

    Metallic look of actor, specified as a real positive number in the range (0,1), where 0 indicates a plastic surface and 1 indicates a metallic surface.

    Example: actor.Metallic = 0.1

    Data Types: double

    Flat shading factor of actor, specified as a real positive number in the range (0,1), where 0 indicates a smooth shading and 1 indicates a faceted shading.

    Example: actor.Flat = 0.7

    Data Types: double

    Actor shadows, specified as 0 (false) if the actor does not cast shadows or 1 (true) if it does.

    Color blending coefficient of vertices, specified as a real positive number in the range (0,1), where 0 indicates to display only the base color and 1 indicates to display only the vertex color. This value indicates how much of the base color blends with the specified vertex color.

    Example: actor.VertexBlend = 0.5

    Texture transformations applied to actor texture, specified as a real positive scalar. Use TextureTransform to define texture position, velocity, scale, and angle.

    Transformation Properties

    PropertyDetailValueValue Example
    Position

    Use this property to set the position of the texture. You can use Position to move the texture along U and V coordinates.

    • Value – Real positive (1,2) vector

    • Default Value – (0,0)

    • Data Type – double

    actor.TextureTransform.Position = [2, 3]
    Velocity

    Use this property to set the velocity of the texture movement. velocity is expressed as a change of U and V coordinates per second of simulation time. The animated surface has no effect on physical interactions.

    • Value – Real positive (1,2) vector

    • Default Value – (0,0)

    • Data Type – double

    actor.TextureTransform.Velocity = [2, 3]
    Scale

    Use this property to set the relative texture scale. If the texture is smaller than the surface to be covered, the scale repeats automatically in all directions. Negative values can be used to flip the texture in corresponding coordinate.

    • Value – Real positive (1,2) vector

    • Default Value – (0,0)

    • Data Type – double

    actor.TextureTransform.Scale = [2, 2]

    Texture mapping parameters applied to actor texture, specified as a real positive vector. Use TextureMapping to define texture blend, displacement, bump factor, and roughness.

    Mapping Properties

    PropertyDetailValueValue Example
    Blend

    Use this property to set the blend ratio of the texture.

    You can use Blend to set the ratio of texture mixing with the base color of the surface using linear interpolation.

    To create an effect of glowing texture, use a black base color ([0 0 0]) and blend values greater than 1.

    You can set the value independently for each color channel ([red green blue]).

    • Value – Real positive (1,3) vector

    • Default Value – (0,0,0)

    • Data Type – double

    actor.TextureMapping.Blend = [1 1 0.5]
    Displacement

    Use this property to set the displacement of the texture.

    You can use Displacement to move the vertex of a geometric mesh in the direction of the normal depending on the color of the texture at that location. This deformation is only visual and does not affect physical interactions.

    You can set the value independently for each color channel ([red green blue]) and its range is unlimited.

    • Value – Real positive (1,3) vector

    • Default Value – (0,0,0)

    • Data Type – double

    actor.TextureMapping.Displacement = [1 2 5]
    Bumps

    Use this property to set the bump factor of the texture.

    You can use Bump to create the effect of a bumpy surface (such as a stone wall) by making small manipulations with normals and lighting.

    You can set the value independently for each color channel ([red green blue]) and its range is unlimited.

    • Value – Real positive (1,3) vector

    • Default Value – (0,0,0)

    • Data Type – double

    actor.TextureMapping.Bumps = [10 10 0.5]
    Roughness

    Use this property to set the roughness factor of the texture.

    You can use Roughness to locally manipulate the global surface shininess specified by the Shininess property.

    You can set the value independently for each color channel ([red green blue]) and its range is unlimited.

    • Value – Real positive (1,3) vector

    • Default Value – (0,0,0)

    • Data Type – double

    actor.TextureMapping.Roughness = [1 1 0.5]

    Source file for texture, specified as a character array. The supported file types are JPEG, PNG, and BMP. The filepath should be absolute.

    Note

    For BMP files, only 8-bit files are supported.

    Example: actor.Texture = fullfile(pwd, "file.jpg")

    Two-sided visibility of actor surface, specified as 0 (false) if the actor is visible only from the outer side or 1 (true) if the actor is visible from both the inner and outer sides. When this property is false, actor performance improves, as the polygons facing away from the camera viewpoint are not rendered.

    Example: actor.TwoSided = 1

    Physical Attributes

    Linear velocity of actor, specified as a real 1-by-3 vector, in meters per second.

    Example: actor.LinearVelocity = [1 1 1]

    Dependencies

    Mobility should be set to 'sim3d.utils.MobilityTypes.Movable' for velocities to work. Otherwise the actor will not move, and you will see a warning.

    Angular velocity of actor, specified as a real 1-by-3 vector, in radians per second.

    Example: actor.AngularVelocity = [2 2 2]

    Dependencies

    Mobility should be set to 'sim3d.utils.MobilityTypes.Movable' for velocities to work. Otherwise the actor will not move, and you will see a warning.

    Mass of actor, specified as a real positive scalar, in kilograms.

    Example: actor.Mass = 12

    Center of mass of sim3d.Actor object, specified as a real positive vector. Use this property to shift the center of gravity from the origin of the local coordinate system.

    Example: actor.CenterOfMass = [1 0 1]

    Application of gravity to actor, specified as 0 (false) if no gravity is applied or 1 (true) if gravity is applied.

    Example: actor.Gravity = false

    Dependencies

    • This property works when:

      • Physics property is set to 1 or true.

      • PreciseContact property is set to 0 or false.

    • Mobility should be set to 'sim3d.utils.MobilityTypes.Movable' for the actor to experience the effects of gravity. Otherwise the actor will not move, and you will see a warning.

    Reaction of actor to physical forces such as gravity and collision, specified as 0 (false) or 1 (true).

    If Physics is enabled, the actor moves independently of its parent actor object but together with its children, unless the children also have Physics enabled.

    Example: actor.Physics = true

    Dependencies

    This property works when PreciseContact property is set to 0 or false.

    Object collision, specified as 0 (false) for no collision or 1 (true) if objects will collide.

    Example: actor.Collisions = false

    Precise contacts during collisions, specified as 0 (false) or 1 (true). Setting this value to true allows the Unreal Engine® to use a collision box that follows the actor mesh precisely. This setting allows the software to detect collisions accurately.

    Example: actor.PreciseContacts = true

    Dependencies

    • Setting PreciseContacts property to true for an actor disables the Physics and Gravity properties.

    • This property is not run-time configurable.

    Stationary translational motion, specified as either 0 (false) or 1 (true). If this property is enabled, the actor is fixed in place. If the actor has defined a nonzero linear velocity, it interacts with other objects as if it were moving itself. You can use this property to model belt conveyors.

    Example: actor.LocationLocked = true

    Dependencies

    Physics should be set to false.

    Stationary rotational motion, specified as either 0 (false) or 1 (true). If this property is enabled, the sim3d.Actor object is fixed in place. If the actor has defined a nonzero angular velocity, it interacts with other objects as if it were moving itself. You can use this property to model circular conveyors (carousels).

    Example: actor.RotationLocked = true

    Dependencies

    Physics should be set to false.

    Option to hide the actor from the virtual world scene, specified as 0 (false) if the actor is visible in the scene or 1 (true) if the actor is hidden in the scene.

    Example: actor.Hidden = 1

    Dynamic friction, dimensionless, specified as a real positive number in the range (0,1). This property indicates the ease with which two actors can slide over each other. The value can only change in discrete steps of 0.1. When two actors slide over each other, the friction is the average value of both actors.

    Example: actor.Friction = 0.4

    Coefficient of restitution, dimensionless, specified as a real positive number in the range (0,1). This property indicates how bouncy the collision is between two actors. The value can only change in discrete steps of 0.1. When two actors collide with each other, the coefficient of restitution is the average value of both actors.

    Example: actor.Restitution = 0.5

    Force applied to actor, specified as real a 1-by-3 vector, in N. The acceleration of the actor depends on the Mass property of the actor and the size of the simulation step specified by sampleTime in run.

    Example: actor.Force = [0 5 0]

    Dependencies

    Physics should be set to true.

    Torque applied to actor, specified as a real 1-by-3 vector, in Nm. The angular acceleration of the actor depends on the Mass property of the actor and the size of the simulation step specified by sampleTime in run.

    Example: actor.Torque = [0 pi/2 0]

    Dependencies

    Physics should be set to true.

    Event Attributes

    Option to report actor events, specified as 0 (false) or 1 (true). This table provides the required events and collision property settings to report events.

    Event Report Event DescriptionActor Events PropertyActor Collision Property
    Hit

    Actor 1 collides with Actor 2

    Actor 1 – true

    Actor 2 – true or false

    Actor 1 – true

    Actor 2 – true

    BeginOverlap

    Actor 1 starts to overlap with Actor 2

    Actor 1 – true

    Actor 2 – true or false

    Actor 1 – false or true and Actor 2 – false or

    Actor 1 – false and Actor 2 – false or true

    EndOverlap

    Actor 1 stops overlapping with Actor 2

    Actor 1 – true

    Actor 2 – true or false

    Actor 1 – false

    Actor 2 – false

    ClickEventYou click Actor 1

    Actor 1 – true

    NA

    Example: actor.Events = true

    This property is read-only.

    Hit event for sim3d.Actor object, specified as 0 (false) or 1 (true).

    This property is read-only.

    Hit sim3d.Actor object identifier, specified as a real positive integer.

    This property is read-only.

    Identifier of actor that collides with the sim3d.Actor object, specified as a real positive integer.

    This property is read-only.

    Hit event location in the virtual world, specified as a real 1-by-3 vector.

    Data Types: double

    This property is read-only.

    Name of actor that collides with the sim3d.Actor object, specified as a character array or string.

    This property is read-only.

    Overlap begin event for sim3d.Actor object, specified as 0 (false) or 1 (true).

    This property is read-only.

    Identifier of the overlapped sim3d.Actor object, specified as a real positive integer.

    This property is read-only.

    Identifier of the actor that overlaps with the sim3d.Actor object, specified as a real positive integer.

    This property is read-only.

    Name of actor that overlaps with the sim3d.Actor object, specified as a character array or string.

    This property is read-only.

    Overlap end event for sim3d.Actor object, specified as 0 (false) or 1 (true).

    This property is read-only.

    Identifier of the sim3d.Actor object that is ending overlap, specified as a real positive integer.

    This property is read-only.

    Identifier of the actor that ends overlap with the sim3d.Actor object, specified as a real positive integer.

    This property is read-only.

    Name of actor that ends overlap with the sim3d.Actor object, specified as a character array or string.

    This property is read-only.

    Click event for sim3d.Actor object, specified as 0 (false) or 1 (true).

    This property is read-only.

    Identifier of the sim3d.Actor object that is clicked, specified as a real positive integer.

    This property is read-only.

    Cartesian coordinates of the click event location in the virtual world, specified as a real 1-by-3 vector.

    Data Types: double

    This property is read-only.

    Name of clicked actor, specified as a character array or string.

    Object Functions

    copyCopy all properties from another actor
    findByFind all actors that match specified criteria
    propagatePropagate value of selected property to actor and its children
    gatherReturn values of selected property from all objects in selected branch
    createMeshCreate new mesh with specified values
    addMeshAppend mesh on top of current mesh
    loadLoad or import 3D file
    saveSave actor and children to a MAT file
    createShapeCreate geometry for basic primitives

    Examples

    collapse all

    This example shows how to create an actor in a virtual world to display in the Simulation 3D Viewer window using Simulink® or MATLAB®.

    This process does not build an appearance for the actor, so the Simulation 3D Viewer does not render a visualization of the actor. For an example that shows how to build an appearance for an actor, see Build Actor from 3D Graphic Primitives.

    Create Virtual World with Actor Using Simulink

    You can use the Simulation 3D Actor block and Simulation 3D Scene Configuration block to create an actor in a virtual world and view it in the Simulation 3D Viewer window.

    Open Model

    Open the Simulink model.

    open_system("CreateWorld");

    Simulink model with Simulation 3D Actor block and Simulation 3D Scene Configuration block

    Explore Model Components

    The model includes a Simulation 3D Scene Configuration block and a Simulation 3D Actor block. The Simulation 3D Scene Configuration block implements a 3D simulation environment. Double-click the Simulation 3D Scene Configuration block to open the Block Parameters dialog box. Set a view in the scene with the Scene view parameter. You can also set a custom viewpoint with this parameter. You must include the configuration block when building Simulink models with Simulation 3D Actor blocks.

    Block parameter dialog box of Simulation 3D Scene Configuration block

    The Simulation 3D Actor block adds an actor to the virtual world. Double-click the Simulation 3D Actor block to open the Block Parameters dialog box. To create an actor before simulation starts, on the Main tab, set the Operation parameter to Create at setup. The block first creates an empty actor with the name specified in the Actor name parameter. You can use any name for the actor. Then, the block loads the source file, if any is present, and runs the Initialization script to build an appearance for the actor. For more details, see Operating Modes. For this example, the block does not build an appearance for the actor in the virtual world.

    Parameters of Simulation 3D Actor block

    Simulate Model

    Simulate the model and view the virtual world in the Simulation 3D Viewer.

    sim("CreateWorld");

    Empty virtual world scene

    Close Model

    Close the Simulink model.

    close_system("CreateWorld");

    Create Virtual World with Actor Using MATLAB

    You can use the sim3d.World and sim3d.Actor objects to create an actor in a virtual world and view it in the Simulation 3D Viewer window.

    Create World

    Create a world scene.

    world = sim3d.World();

    Create Actor

    Add an actor to the world.

    add(world,sim3d.Actor());

    Run Simulation

    Run a simulation set for 10 seconds with a sample time of 0.02 seconds.

    run(world,0.02,10)

    Empty virtual world scene

    Delete World

    Delete the world object.

    delete(world);

    Version History

    Introduced in R2022b

    expand all