Main Content

sim3d.Actor

Object used to define actors in the Unreal Engine viewer

expand all in page

    Description

    Use the sim3d.Actor object for user-defined Unreal Engine® C++ or blueprint actors.

    Creation

    Syntax

    actor = sim3d.Actor
    actor = sim3d.Actor(___,Name,Value)

    Description

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

    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])

    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, returned as an m-by-n array. m is the vertical resolution of the image, and n is the horizontal resolution of the image.

    The table shows the object IDs used in the default scenes that available in the Simulation 3D Scene Configuration block. If you are using a custom scene, you can assign new object types to unused IDs. If a scene contains an object that does not have an assigned ID, that object is assigned an ID of 0. The detection of lane markings is not supported.

    IDType
    0

    None/default

    1

    Building

    2

    Not used

    3

    Other

    4

    Pedestrians

    5

    Pole

    6

    Lane Markings

    7

    Road

    8

    Sidewalk

    9

    Vegetation

    10

    Vehicle

    11

    Not used

    12

    Generic traffic sign

    13

    Stop sign

    14

    Yield sign

    15

    Speed limit sign

    16

    Weight limit sign

    17-18

    Not used

    19

    Left and right arrow warning sign

    20

    Left chevron warning sign

    21

    Right chevron warning sign

    22

    Not used

    23

    Right one-way sign

    24

    Not used

    25

    School bus only sign

    26-38

    Not used

    39

    Crosswalk sign

    40

    Not used

    41

    Traffic signal

    42

    Curve right warning sign

    43

    Curve left warning sign

    44

    Up right arrow warning sign

    45-47

    Not used

    48

    Railroad crossing sign

    49

    Street sign

    50

    Roundabout warning sign

    51

    Fire hydrant

    52

    Exit sign

    53

    Bike lane sign

    54-56

    Not used

    57

    Sky

    58

    Curb

    59

    Flyover ramp

    60

    Road guard rail

    61Bicyclist
    62-66

    Not used

    67

    Deer

    68-70

    Not used

    71

    Barricade

    72

    Motorcycle

    73-255

    Not used

    Dependencies

    To enable this port, on the Simulation 3D Scene Configuration block, select Output semantic segmentation on the Ground Truth tab.

    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 reality 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.

    Children of actor, specified as a handle to the sim3d.Actor object.

    This property is read only.

    This property is read only.

    Parent world method handle, specified as a handle to the parent sim3d.Actor object.

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

    Rotation of actor in the Unreal Editor scene, 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 Unreal Editor scene, 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: string

    Mesh Attributes

    Vertices of the mesh geometry, specified as a real n-by-3 vector, where n is the number of vertices.

    Example: actor.Vertices = [1, 2, 3; 43, 54, 65]

    Data Types: double

    Vertices of each triangle, specified as a real n-by-3 vector, where n is the number of vertices. You can use this property to define how each triangle of the mesh is drawn.

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

    Data Types: double

    Normals of each vertex, specified as a real n-by-3 vector, where n is the number of vertices. Normals must be of the same length as Vertices.

    Example: actor.Normals = [1, 2, 3; 43, 54, 65]

    Data Types: double

    Texture coordinates for each vertex, specified as a real n-by-2 vector, where n is the number of vertices. This argument is optional, and if specified, must be the same length as Vertices.

    Example: actor.TextureCoordinates = [1 2;3 4]

    Vertex colors, specified as a real n-by-3 vector, where n is the number of vertices. This argument is optional, and if specified, must be the same length as Vertices.

    Example: actor.VertexColors = [1, 2,3; 4, 5, 6]

    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 a nontransparent 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 surface and 1 indicates a faceted surface.

    Example: actor.Flat = 0.7

    Data Types: double

    Tessellation factor of actor, specified as a real positive integer in the range (0,8). Use this property to specify the coefficient of automatic geometry refinement. This property can be useful when texture displacement mapping is used.

    Example: actor.Tessellation = 5

    Color blending coefficient of vertices, specified as a real positive number in the range (0,1). This value can be larger to achieve the effect of glowing colors..

    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]
    Angle

    Use this property to set the relative texture angle. The texture rotates always around its center point [0.5, 0.5] in the UV coordinates. The center is fixed to the texture and moves with it depending on the Position and Velocity parameters.. Negative values can be used to flip the texture in corresponding coordinate.

    • Value – Real positive scalar

    • Default Value – 0

    • Data Type – double

    		actor.TextureTransform.Angle = pi/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 actor shape, specified as a character array. The supported file types are JPEG, PNG, BMP, and TGA. The filepath should be absolute.

    Example: actor.Texture = "file.jpg"

    Physical Attributes

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

    Linear velocity of actor in local coordinates, specified as a real positive 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 in local coordinates, specified as a real positive 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 ortrue.

    • 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

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

    Example: actor.Collisions = true

    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

    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

    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
    takeSnapshotTake snapshot of selected properties
    restoreSnapshotRestore actor to state of properties saved in specified snapshot
    createMeshCreate new mesh with specified values
    addMeshAdd mesh on top of current mesh
    loadLoad or import 3D file
    saveSave actor and children to a MAT file
    createShapeCreate geometry for basic primitives

    Version History

    Introduced in R2022b

    See Also

    | |