surfaceMesh

Create surface mesh

Since R2022b

Description

A surfaceMesh object creates and stores a surface mesh. A surface mesh represents a geometric surface and consists of vertices, faces, and edges. Using the surfaceMesh object and the object functions, you can:

• Add and remove mesh vertices and faces

• Perform geometric operations, such as rotate, translate, transform, and scale

• Compute mesh normals

• Crop, simplify, and subdivide a mesh

• Check mesh properties such as whether it is self-intersecting, watertight, or orientable

• Remove degenerate and unreferenced vertices and faces

Creation

Syntax

mesh = surfaceMesh(vertices,faces)

mesh = surfaceMesh(___,Name=Value)

Description

mesh = surfaceMesh(vertices,faces) creates a surfaceMesh object with the specified vertices and faces.

mesh = surfaceMesh(___,Name=Value) specifies options using one or more name-value arguments in addition to the arguments from the previous syntax. For example, VertexNormals=[8 -4 4; 4 4 8; -6 6 3; -3 -6 6; 3 -6 -6; 6 6 -3] specifies the normal vectors for the mesh vertices.

Properties

Vertices — Mesh vertices

M-by-3 matrix

Mesh vertices, specified as an M-by-3 matrix. Each row of the matrix is of the form [x y z], specifying the coordinates of a vertex. Each vertex has a vertex ID equal to its row number in the matrix. M is the total number of vertices in the mesh.

The vertices argument sets this property at object creation.

Data Types: single | double

Faces — Mesh triangular faces

N-by-3 matrix

Mesh triangular faces, specified as an N-by-3 matrix. Each row of the matrix is in the form [V1 V2 V3], specifying the row indices of the corresponding vertices in Vertices that define the triangular face. N is the number of faces in the mesh.

The faces argument sets this property at object creation.

Data Types: single | double

VertexNormals — Normal vectors for mesh vertices

M-by-3 matrix

Normal vectors for the mesh vertices, specified as an M-by-3 matrix. Each row of the matrix is in the form [x y z], specifying the normal vector for a vertex. M is the total number of vertices in the mesh.

Vertex normal is a weighted average of all the face normals that are connected to a vertex.

To set this property, specify it at object creation.

Example: mesh(vertices,faces,VertexNormals=[8 -4 4; 4 4 8; -6 6 3; -3 -6 6; 3 -6 -6; 6 6 -3])

Data Types: single | double

VertexColors — Color values for mesh vertices

M-by-3 matrix

Color values for the mesh vertices, specified as an M-by-3 matrix. Each row of the matrix is of the form [R G B], specifying the color value for a vertex. Each value must be in the range [0, 1]. M is the total number of vertices in the mesh.

To set this property, specify it at object creation.

Example: mesh(vertices,faces,VertexColors=[1 0 0; 0 0 1; 0 0 0; 1 1 1 1; 1 1 0; 0 1 1])

Data Types: single | double

FaceNormals — Normals for mesh faces

N-by-3 matrix

Normal vectors for the mesh faces, specified as an N-by-3 matrix. Each row of the matrix is of the form [x y z], specifying the normal for a face. N is the total number of faces in the mesh.

To set this property, specify it at object creation.

Example: mesh(vertices,faces,FaceNormals=[8 -4 4; 4 4 8; -6 6 3; -3 -6 6; 3 -6 -6; 6 6 -3])

Data Types: single | double

FaceColors — Color for mesh faces

N-by-3 matrix

Color values for the mesh faces, specified as an N-by-3 matrix. Each row of the matrix is of the form [R G B], specifying the color value for a face. Each value must be in the range [0, 1]. N is the total number of faces in the mesh.

To set this property, specify it at object creation.

Example: mesh(vertices,faces,FaceColors=[1 0 0; 0 0 1; 0 0 0; 1 1 1; 1 1 0; 0 1 1])

Data Types: single | double

NumVertices — Number of mesh vertices

positive integer

Number of mesh vertices, stored as a positive integer.

This property is read-only.

Data Types: unit32

NumFaces — Number of mesh faces

positive integer

Number of mesh faces, stored as a positive integer.

This property is read-only.

Data Types: unit32

Object Functions

addVertices	Add vertices to surface mesh
addFaces	Add faces to surface mesh
removeVertices	Remove vertices from surface mesh
removeFaces	Remove faces from surface mesh
translate	Translate surface mesh
rotate	Rotate surface mesh
transform	Apply rigid transformation to surface mesh
vertexCenter	Find vertex center of surface mesh
scale	Scale vertices of surface mesh
computeNormals	Compute unit normals for mesh vertices and faces
crop	Crop surface mesh
simplify	Simplify surface mesh
subdivide	Subdivide surface mesh
isEdgeManifold	Check if surface mesh is edge-manifold
isOrientable	Check if surface mesh is orientable
isSelfIntersecting	Check if surface mesh is self-intersecting
isVertexManifold	Check if surface mesh is vertex-manifold
isWatertight	Check if surface mesh is watertight
removeDefects	Remove surface mesh defects

Examples

Create Cuboid Surface Mesh

Define mesh vertices for a cuboid.

vertices = [1 -1  1; 1 1 1; -1 1 1; -1 -1 1; ...
            1 -1 -1; 1 1 -1; -1 1 -1; -1 -1 -1];

Define the mesh faces using the vertices.

faces = [6 2 1; 1 5 6; 8 4 3; 3 7 8; 6 7 3; 3 2 6; ...
         5 1 4; 4 8 5; 4 1 2; 2 3 4; 7 6 5; 5 8 7];

Create the surface mesh.

mesh = surfaceMesh(vertices,faces);

Display the cuboid surface mesh.

surfaceMeshShow(mesh)

Version History

Introduced in R2022b