Main Content

createMesh

Create new mesh with specified values

Since R2022b

    Description

    example

    createMesh(actor,vertices,normals,faces) creates a mesh defined by vertices, normals and faces.

    createMesh(___,tcoords,vcolor) creates a mesh additionally defined by the texture coordinates tcoords and the vertex colors vcolor.

    Examples

    collapse all

    This example shows how to build an actor from mesh data and apply texture using either Simulink® or MATLAB®. You can build an appearance for the actor using the createMesh function and apply texture using the Texture property of the sim3d.Actor object. A mesh is a 3D build of a model consisting of polygons and is defined by vertices, normals, and faces. This example uses the mesh data of a cube to build a cube actor. First, you create a world scene and an actor object. Next, input the mesh data to build the appearance of the actor and apply a texture. Then, you add the actor to the world and set a view in the scene. Finally, you view the actor in the Simulation 3D Viewer window.

    Build Actor and Apply Texture Using Simulink

    This workflow shows how to use Simulation 3D Actor block and Simulation 3D Scene Configuration block to create a virtual world with an actor. You can build the appearance of the actor from mesh data, apply a texture, and set a view in the scene to view the actor in the Simulation 3D Viewer window.

    Open Model

    Open the Simulink model.

    open_system("CreateMeshActorAndApplyTexture");

    Simulink model with Simulation 3D Actor block named cube and Simulation 3D Scene Configuration block.

    Explore Model Components

    The model includes a Simulation 3D Actor block and a Simulation 3D Scene Configuration 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. For more details, see Operating Modes.

    The block parameter dialog box of the Simulation 3D Actor block named cube shows parameters and the initialization script

    The Initialization script builds an actor using the createMesh function with mesh data, vertices (V), normals (N), and faces (F). This example uses the mesh data for a cube of size [1 1 1]. The mesh data contains 24 vertices, 24 normals for each of the vertices, and 12 triangular faces. Each face of the cube is made with two triangular faces, and each triangular face is made with three vertices. The input argument Texture coordinates, T, maps the texture file on to each vertices of the actor. T defines which point on the texture file maps to each of the vertices. The input argument Vertex Colors, C, specifies color for each vertex in [R G B] components. To display the vertex colors, you must set the VertexBlend property of sim3d.Actor object to a value greater than 0 and less than 1. C is optional to build an actor from mesh data. For this example, C is an empty matrix. On the Transform tab, you can also set the Initial position, Initial rotation and Actor scale of the actor.

    Simulate Model

    Simulate the model and view the cube actor with texture in the Simulation 3D Viewer.

    sim("CreateMeshActorAndApplyTexture");

    Cube actor with texture in the virtual world scene.

    Close Model

    Close the Simulink model.

    close_system("CreateMeshActorAndApplyTexture");

    Build Actor and Apply Texture Using MATLAB

    You can use the sim3d.World and sim3d.Actor objects and functions to create a virtual world with an actor.

    Create a world scene.

    world = sim3d.World();

    Instantiate an actor object named cube. You can use any name for the actor.

    ActObj = sim3d.Actor('ActorName', 'cube');

    To build an actor with createMesh function, specify the input arguments vertices (V), normals (N), and faces (F) of the mesh. This example uses the mesh data for a cube of size [1 1 1]. The mesh data contains 24 vertices, 24 normals for each of the vertices, and 12 triangular faces. Each face of the cube is made with two triangular faces, and each triangular face is made with three vertices. If you can have the vertices, normals, and faces of an actor, you can build the actor with createMesh function.

    V = [-0.5 -0.5 -0.5; 0.5 -0.5 -0.5; 0.5 0.5 -0.5; -0.5 0.5 -0.5; ...
         -0.5 -0.5 0.5; 0.5 -0.5 0.5; 0.5 0.5 0.5; -0.5 0.5 0.5; ...
         -0.5 -0.5 -0.5; 0.5 -0.5 -0.5; 0.5 0.5 -0.5; -0.5 0.5 -0.5; ...
         -0.5 -0.5 0.5; 0.5 -0.5 0.5; 0.5 0.5 0.5; -0.5 0.5 0.5; ...
         -0.5 -0.5 -0.5; 0.5 -0.5 -0.5; 0.5 0.5 -0.5; -0.5 0.5 -0.5; ...
         -0.5 -0.5 0.5; 0.5 -0.5 0.5; 0.5 0.5 0.5; -0.5 0.5 0.5];
    
    N = [0 0 -1; 0 0 -1; 0 0 -1; 0 0 -1; 0 0 1; 0 0 1; ...
         0 0 1; 0 0 1; -1 0 0; 1 0 0; 1 0 0; -1 0 0; ...
         -1 0 0; 1 0 0; 1 0 0; -1 0 0; 0 -1 0; 0 -1 0; ...
         0 1 0; 0 1 0; 0 -1 0; 0 -1 0; 0 1 0; 0 1 0];
    
    F = [0 2 3; 0 1 2; 16 20 21; 21 17 16; 9 13 10; 10 13 14; ...
         18 22 19; 19 22 23; 11 15 8; 8 15 12; 4 7 5; 5 7 6];

    The input argument Texture coordinates, T, maps the texture file on to each vertices of the actor. T defines which point on the texture file maps to each of the vertices.

    T = [0 0; 1 0; 1 1; 0 1; 0 1; 1 1; 1 0; 0 0; 1 1; 0 1; 1 1; 0 1; ...
         1 0; 0 0; 1 0; 0 0; 0 1; 1 1; 0 1; 1 1; 0 0; 1 0; 0 0; 1 0];

    The input argument Vertex Colors, C, specifies color for each vertex in [R G B] components. To display the vertex colors, you must set the VertexBlend property of sim3d.Actor object to a value greater than 0 and less than 1. C is optional to build an actor from mesh data and for this example, C is an empty matrix.

    C = [];

    Create a mesh using the actor object and mesh data. Use the image file to set the texture. Add the actor object to the world.

    createMesh(ActObj, V, N, F, T, C);
    ActObj.Texture = fullfile(pwd,"image.png");
    add(world,ActObj);

    Set Actor Transformation

    Use the actor object translation, rotation, and scale properties to orient the actor relative to the world origin.

    ActObj.Translation = [0 0 0];
    ActObj.Rotation = [0, 0, 0];
    ActObj.Scale = [1, 1, 1];

    Set Viewer Window Point of View

    If you do not create a viewport, then the point of view is set to 0, 0, 0, and you can use the keyboard shortcuts and mouse controls to navigate in the Simulation 3D Viewer window.

    For this example, use the createViewport function to create a viewport with a single field, Main, that contains a sim3d.sensors.MainCamera object.

    viewport = createViewport(world);
    viewport.Translation = [-6, 0, 1.5];

    Run Animation

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

    run(world,0.02,10);

    Cube actor with texture in the virtual world scene.

    Delete World

    Delete the world object.

    delete(world)

    Input Arguments

    collapse all

    Actor class where mesh is created, specified as a sim3d.Actor object.

    Vertex positions, 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: 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: 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 matrix.

    Example: 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

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

    Note

    To display vcolor 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 vcolor.

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

    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 of the vertices. This matrix must be the same length as vertices.

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

    Data Types: double

    Version History

    Introduced in R2022b