fegeometry

R2026b

Geometry object for finite element analysis

Since R2023a

Description

An fegeometry object contains a geometry for use in a finite element analysis with an femodel object.

Creation

Syntax

gm = fegeometry(geometry)

gm = fegeometry(geometry,Name=Value)

gm = fegeometry(mesh)

gm = fegeometry(nodes,elements)

gm = fegeometry(___,ElementIDToRegionID)

Description

gm = fegeometry(geometry) creates an fegeometry object that you can use in a finite element analysis with an femodel object. Alternatively, you can assign a geometry directly to the Geometry property of femodel, for example, femodel.Geometry = geometry.

gm = fegeometry(geometry,Name=Value) creates an fegeometry object using one or more name-value arguments. For this syntax, geometry must specify a path to an STL or STEP file.

gm = fegeometry(mesh) creates an fegeometry object from a mesh represented by an FEMesh object. If the mesh data identifies multiple faces for a 2-D geometry or multiple cells for a 3-D geometry, the resulting geometry contains corresponding multiple faces or cells.

gm = fegeometry(nodes,elements) creates an fegeometry object from a mesh represented by nodes and elements.

gm = fegeometry(___,ElementIDToRegionID) creates a multidomain geometry from a mesh represented by an FEMesh object or by nodes and elements. ElementIDToRegionID specifies the domain IDs for each element of the mesh.

Input Arguments

geometry — Geometry description

string scalar | character vector | decomposed geometry matrix | handle to a geometry function | triangulation object | triangulation points and triangulation connectivity list | delaunayTriangulation object | DiscreteGeometry object | AnalyticGeometry object | polyshape object

Geometry description, specified as one of these values:

• String scalar or character vector that contains a path to an STL or STEP file. The path must end with the file extension ".stl", ".STL", ".stp", ".STP", ".step", ".STEP", or any combination of uppercase and lowercase letters in this extension.

  fegeometry does not let you import a multidomain geometry from an STL file if subdomains have any common points. You can import a 3-D multidomain geometry from a STEP file.

• Decomposed geometry matrix or a handle to a geometry function. For details about a decomposed geometry matrix, see decsg. A geometry function must return the same result for the same input arguments in every function call. Thus, it must not contain functions and expressions designed to return a variety of results, such as random number generators.

• triangulation object. The fegeometry function accepts both surface triangulation and triangulation with tetrahedra for 3-D geometries. For a 3-D geometry created from surface triangulation, the Mesh property remains empty. For a 2-D geometry or a 3-D geometry created from triangulation with tetrahedra, fegeometry uses triangulation points and connectivity list to specify a linear mesh. If the Mesh property is empty or your task requires a more accurate quadratic mesh or a finer linear mesh, use the generateMesh function.

• Matrices of triangulation points P and triangulation connectivity list T. These matrices are the same as matrices representing the properties of a triangulation object. Triangulation connectivity list is a m-by-n matrix, where m is the number of triangles or tetrahedra, and n is the number of vertices per triangle or tetrahedron. Each row of T contains the vertex IDs that define a triangle or tetrahedron. The vertex IDs are the row numbers of the input points. The ID of a triangle or tetrahedron in the triangulation is the corresponding row number in T. P is a matrix whose columns are the x-coordinates, y-coordinates, and (possibly) z-coordinates of the triangulation points. The row numbers of P are the vertex IDs in the triangulation.

• delaunayTriangulation object. The fegeometry function uses triangulation points to specify a mesh. If your task requires a more accurate quadratic mesh, use the generateMesh function.

• DiscreteGeometry object or a vector of DiscreteGeometry objects.

• AnalyticGeometry object or a vector of AnalyticGeometry objects.

• polyshape object or a vector of polyshape objects.

mesh — Mesh description

FEMesh object

Since R2024b

Mesh description, specified as an FEMesh object.

nodes — Mesh nodes

Nnodes-by-2 numeric matrix | Nnodes-by-3 numeric matrix

Mesh nodes, specified as an Nnodes-by-2 or Nnodes-by-3 matrix for a 2-D or 3-D geometry, respectively. Nnodes is the number of nodes in the mesh. Each row of the matrix contains x-, y-, and, if applicable, z- coordinates of one node.

Data Types: double

elements — Mesh elements

Nelements-by-3 integer matrix | Nelements-by-4 integer matrix | Nelements-by-6 integer matrix | Nelements-by-10 integer matrix

Mesh elements, specified as an integer matrix with Nelements rows and 3, 4, 6, or 10 columns, where Nelements is the number of elements in the mesh.

• Linear planar mesh or linear mesh on the geometry surface has size Nelements-by-3. Each row of elements contains the indices of the triangle corner nodes for a surface element. In this case, the resulting geometry does not contain a full mesh. Create the mesh using the generateMesh function.

• Linear elements have size Nelements-by-4. Each row of elements contains the indices of the tetrahedral corner nodes for an element.

• Quadratic planar mesh or quadratic mesh on the geometry surface has size Nelements-by-6. Each row of elements contains the indices of the triangle corner nodes and edge centers for a surface element. In this case, the resulting geometry does not contain a full mesh. Create the mesh using the generateMesh function.

• Quadratic elements have size Nelements-by-10. Each row of elements contains the indices of the tetrahedral corner nodes and the tetrahedral edge midpoint nodes for an element.

For details on node numbering for linear and quadratic elements, see Mesh Data.

Data Types: double

ElementIDToRegionID — Domain information for each mesh element

vector of positive integers

Domain information for each mesh element, specified as a vector of positive integers. Each vector element is an ID of a geometric region for an element of the mesh. The length of this vector equals the number of elements in the mesh.

Data Types: double

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: gm = fegeometry("AngleBlock.step",MaxRelativeDeviation=5) imports a geometry from the AngleBlock.step file using the relative sag of 5.

AllowSelfIntersections — Indicator to allow import of self-intersecting geometry

true or 1 (default) | false or 0

Since R2024a

Indicator to allow the import or creation of a self-intersecting geometry, specified as true or false. You also can use 1 or 0 instead of true or false. This argument enables you to import a self-intersecting geometry from an STL or STEP file, create it from a triangulation object, or create it from matrices of triangulation points and triangulation connectivity list.

By default, fegeometry does not check for self-intersections and lets you import these types of geometries. If you set this argument to false or 0, fegeometry issues an error for a geometry with self-intersections.

Example: AllowSelfIntersections=true

FeatureAngle — Threshold for dihedral angle between adjacent triangles

44 (default) | number between 10 and 90

Since R2024a

Threshold for the dihedral angle between adjacent triangles to indicate the edge and create two separate faces, specified as a number between 10 and 90. The specified FeatureAngle value represents degrees. This argument works for importing a geometry from STL and STEP files, creating a geometry from a triangulation object, or creating a geometry from matrices of triangulation points and triangulation connectivity list. You also can change FeatureAngle for an existing fegeometry object.

If the angle between the triangles exceeds the threshold, the edge becomes a topological (feature) edge separating two faces. If the angle does not exceed the threshold, fegeometry does not create a topological edge with two separate faces, unless the function can create the edge based on other criteria. Instead, fegeometry creates one face.

Example: FeatureAngle=30

MaxRelativeDeviation — Relative sag

1 (default) | number in the range [0.1, 10]

Relative sag for importing a STEP geometry, specified as a number in the range [0.1,10]. This value controls the accuracy of the geometry import from a STEP file. A relative sag is the ratio between the local absolute sag and the local mesh edge length. The absolute sag is the maximal gap between the mesh and the geometry.

Example: MaxRelativeDeviation=5

Data Types: double

VectorOutput — Indicator to return vector of single-domain geometries

false (default) | true

Since R2026b

Indicator to return a vector of single-domain geometries, specified as false or true. You can use this argument when importing a multidomain geometry from a STEP-file. Setting VectorOutput to true lets you return a vector of single-domain geometries instead of returning one multidomain geometry. You can manipulate or modify each of the returned single-domain geometries separately. For example, you can translate, rotate, and scale the geometries, and then combine them by using the Boolean union, intersect, and subtract functions.

By default, fegeometry recognizes a STEP file that represents a multidomain geometry and imports it as one geometry with multiple cells. If the resulting geometry is invalid, fegeometry errors. Setting VectorOutput to true lets you return a vector of single-domain geometries instead. Typically, you can combine these geometries by using the union function, for example:

gv = fegeometry("geometry.step",VectorOutput=true);
gm = union(gv,KeepBoundaries=true)

If the resulting geometry is invalid, you can try these approaches:

• Remove extraneous geometries from the vector before combining the geometries.

• Slightly translate some or all of the geometries before combining them.

• If internal boundaries are not essential for your task, call union with KeepBoundaries set to false.

Data Types: logical

Properties

NumCells — Number of geometry cells

Read-only: nonnegative integer

This property is read-only.

Number of geometry cells, returned as a nonnegative integer.

Data Types: double

NumFaces — Number of geometry faces

Read-only: positive integer

This property is read-only.

Number of geometry faces, returned as a positive integer.

Data Types: double

NumEdges — Number of geometry edges

Read-only: nonnegative integer

This property is read-only.

Number of geometry edges, returned as a nonnegative integer.

Data Types: double

NumVertices — Number of geometry vertices

Read-only: nonnegative integer

This property is read-only.

Number of geometry vertices, returned as a nonnegative integer.

Data Types: double

Vertices — Coordinates of geometry vertices

Read-only: N-by-2 numeric matrix | N-by-3 numeric matrix

This property is read-only.

Coordinates of geometry vertices, returned as an N-by-2 or N-by-3 numeric matrix for a 2-D or 3-D geometry, respectively. Here, N is the number of vertices.

Data Types: double

FeatureAngle — Threshold for dihedral angle between adjacent triangles

44 (default) | number between 10 and 90

Threshold for the dihedral angle between adjacent triangles to indicate the edge and create two separate faces, specified as a number between 10 and 90 (in degrees). See Feature Angle of 3-D Geometry.

Mesh — Mesh for solution

FEMesh object

Mesh for solution, specified as an FEMesh object.

Object Functions

addCell	Combine two geometries by adding one inside a cell of another
addFace	Fill void regions in 2-D and split cells in 3-D geometry
addVertex	Add vertex on geometry boundary
addVoid	Create void regions inside 3-D geometry
cellEdges	Find edges belonging to boundaries of specified cells
cellFaces	Find faces belonging to specified cells
deleteCell	Delete geometry cells
discreteGeometry	Discrete 2-D or 3-D geometry description
extrude	Extrude 2-D geometry or specified faces of 3-D geometry
faceEdges	Find edges belonging to specified faces
facesAttachedToEdges	Find faces attached to specified edges
generateMesh	Create triangular or tetrahedral mesh
mergeCells	Merge geometry cells
nearestEdge	Find edges nearest to specified point
nearestFace	Find faces nearest to specified point
pdegplot	Plot PDE geometry
pdemesh	Plot PDE mesh
rotate	Rotate geometry
scale	Scale geometry
translate	Translate geometry
triangulation	Create triangulation object from fegeometry

Examples

fegeometry Object from DiscreteGeometry Object

Create an fegeometry object from a DiscreteGeometry object by assigning it to an femodel object for a finite element analysis.

Create and plot a 3-D geometry consisting of three nested cuboids of the same height.

gm = multicuboid([2 3 5],[4 6 10],3);
pdegplot(gm,CellLabels="on",FaceAlpha=0.3)

Create an femodel object for solving a static structural problem and assign the geometry to the model.

model = femodel(AnalysisType="structuralStatic", ...
                Geometry=gm);
model.Geometry

ans = 
  fegeometry with properties:

        NumCells: 3
        NumFaces: 18
        NumEdges: 36
     NumVertices: 24
        Vertices: [24×3 double]
    FeatureAngle: 44
            Mesh: []

fegeometry Object from STL File

Create an fegeometry object from an STL file representing a forearm link, and use it for a finite element analysis with an femodel object.

Create an femodel object for solving a static structural problem, and assign the geometry to the model.

model = femodel(AnalysisType="structuralStatic", ...
                Geometry="ForearmLink.stl");
model.Geometry

ans = 
  fegeometry with properties:

        NumCells: 1
        NumFaces: 147
        NumEdges: 329
     NumVertices: 213
        Vertices: [213×3 double]
    FeatureAngle: 44
            Mesh: []

Plot the geometry.

pdegplot(model,FaceAlpha=0.3)

fegeometry Object from Function Handle

Create an fegeometry object from a function handle.

gm = fegeometry(@cardg)

gm = 
  fegeometry with properties:

        NumCells: 0
        NumFaces: 1
        NumEdges: 4
     NumVertices: 4
        Vertices: [4×2 double]
    FeatureAngle: []
            Mesh: []

Plot the geometry with the edge labels.

pdegplot(gm,EdgeLabels="on");

fegeometry Object from Geometry Description Matrix

Create an fegeometry object from a geometry description matrix.

g = [3 4 0 1 1 0 0 0 1.0 1.0];
sf = 'S1'; 
ns = 'S1';
gm = fegeometry(decsg(g',sf,ns'))

gm = 
  fegeometry with properties:

        NumCells: 0
        NumFaces: 1
        NumEdges: 4
     NumVertices: 4
        Vertices: [4×2 double]
    FeatureAngle: []
            Mesh: []

Plot the geometry with the edge labels.

pdegplot(gm,EdgeLabels="on");
xlim([-0.1 1.1])
ylim([-0.1 1.1])

fegeometry Object from triangulation Object

Since R2023b

Create an fegeometry object from a 2-D triangulation object.

Define the points in a 2-D triangulation.

P = [2.5 8.0;
     6.5 8.0;
     2.5 5.0;
     6.5 5.0;
     1.0 6.5;
     8.0 6.5];

Define the triangulation connectivity list.

T = [5 3 1;
     3 2 1;
     3 4 2;
     4 6 2];

Create the triangulation representation.

TR = triangulation(T,P)

TR = 
  triangulation with properties:

              Points: [6×2 double]
    ConnectivityList: [4×3 double]

Create an fegeometry object from the triangulation object TR.

gm = fegeometry(TR)

gm = 
  fegeometry with properties:

        NumCells: 0
        NumFaces: 1
        NumEdges: 6
     NumVertices: 6
        Vertices: [6×3 double]
    FeatureAngle: []
            Mesh: [1×1 FEMesh]

The created geometry includes a linear mesh.

gm.Mesh

ans = 
  FEMesh with properties:

             Nodes: [2×6 double]
          Elements: [3×4 double]
    MaxElementSize: 5
    MinElementSize: 2.1213
     MeshGradation: []
    GeometricOrder: 'linear'

To create a more accurate quadratic mesh, use generateMesh.

gm = generateMesh(gm);
gm.Mesh

ans = 
  FEMesh with properties:

             Nodes: [2×871 double]
          Elements: [6×408 double]
    MaxElementSize: 0.3046
    MinElementSize: 0.1523
     MeshGradation: 1.5000
    GeometricOrder: 'quadratic'

fegeometry Object from Mesh

Since R2024b

Create a spherical geometry from a mesh represented by an FEMesh object and from a mesh represented by nodes and elements.

First, create and plot a mesh.

model = createpde;
model.Geometry = multisphere(10);
msh = generateMesh(model);
pdemesh(msh)

Create an fegeometry object representing a sphere by using the FEMesh object msh.

g1 = fegeometry(msh)

g1 = 
  fegeometry with properties:

        NumCells: 1
        NumFaces: 1
        NumEdges: 0
     NumVertices: 0
        Vertices: []
    FeatureAngle: 44
            Mesh: [1×1 FEMesh]

Plot the resulting geometry.

pdegplot(g1)

Create an fegeometry object representing the same sphere by using the mesh nodes and elements as input arguments. Transpose the arrays representing the nodes and elements.

g2 = fegeometry(msh.Nodes',msh.Elements')

g2 = 
  fegeometry with properties:

        NumCells: 1
        NumFaces: 1
        NumEdges: 0
     NumVertices: 0
        Vertices: []
    FeatureAngle: 44
            Mesh: [1×1 FEMesh]

Plot the resulting geometry.

pdegplot(g2)

2-D Multidomain Geometry

Create a 2-D multidomain geometry from a planar mesh.

The MultidomainMesh2D file, which is included in Partial Differential Equation Toolbox™, contains a 2-D mesh. Load information about nodes, elements, and element-to-domain correspondence into your workspace.

load MultidomainMesh2D

Create a geometry from the mesh nodes and elements.

gm = fegeometry(nodes',elements',ElementIdToRegionId);

Plot the geometry with the face labels.

pdegplot(gm,FaceLabels="on")

3-D Multidomain fegeometry Object from Mesh

Since R2024b

Create two geometries from a mesh, one with two cells and another with one cell.

The TwoCellMesh file contains a 3-D mesh specified by an FEMesh object and a vector specifying element-to-domain correspondence. Each vector element is a cell ID for an element of the mesh. Load this data into your workspace.

load TwoCellMesh;

Create a geometry from the mesh.

gm2cells = fegeometry(msh);

Plot the geometry with the cell labels.

pdegplot(gm2cells,CellLabels="on",FaceAlpha=0.3)

Now, modify vector ElementIDToRegionID, which specifies the element-to-domain correspondence, so that all elements of the mesh belong to cell 1.

ElementIDToRegionID(:) = 1;

Create a geometry from the mesh. The resulting geometry has one cell.

gm1cell = fegeometry(msh,ElementIDToRegionID);

Plot the geometry with the cell label.

pdegplot(gm1cell,CellLabels="on",FaceAlpha=0.3)

Self-Intersecting Geometry

Since R2024a

Check for self-intersections while importing the geometry of a cover.

Create an fegeometry object from an STL file and plot the geometry.

gm = fegeometry("Cover.stl");
pdegplot(gm)

Create an femodel object for solving a static structural problem, and assign the geometry to the model.

model = femodel(AnalysisType="structuralStatic", ...
                Geometry=gm);

Generate a mesh and assign the result to the model to update the mesh stored in the Geometry property of the model. The mesh generator issues a warning about poor quality of some of the mesh elements.

model = generateMesh(model);

Warning: Found elements with poor shape quality.
(Type "warning off pde:pdeMeshGenerator:ElementQualityWarn" to suppress this warning.) 
> In pde.EquationModel/generateMesh (line 104)
In fegeometry/generateMesh (line 220)
In femodel/generateMesh (line 344)

Rotate the geometry plot to check for any problematic areas. By looking at the top of the geometry, you can see that three of the cylinders might be in contact with each other or intersecting each other.

figure
pdegplot(gm)
view([30 90])

Use the AllowSelfIntersections argument to check for self-intersections while importing a geometry. If you set this argument to false, fegeometry does not allow the import if a geometry has self-intersections.

gm = fegeometry("Cover.stl",AllowSelfIntersections=false)

Unable to import a self-intersecting geometry.

Multidomain Geometry from STEP File

Import a multidomain geometry from a STEP file as a single geometry with multiple cells and as a vector of single-domain geometries.

Import a geometry from a STEP file containing two hemispheres. By default, fegeometry imports the file as a single multidomain geometry.

gm = fegeometry("Hemispheres.step")

gm = 
  fegeometry with properties:

        NumCells: 2
        NumFaces: 7
        NumEdges: 4
     NumVertices: 4
        Vertices: [4×3 double]
    FeatureAngle: 44
            Mesh: []

Plot the geometry with cell labels to see the individual cells.

pdegplot(gm,CellLabels="on")

Return a vector of single-domain geometries by setting VectorOutput to true.

gm = fegeometry("Hemispheres.step",VectorOutput=true);

Plot the geometries.

pdegplot(gm(1))
hold on
pdegplot(gm(2),FaceColor="red")

Combine the single-domain geometries into one multidomain geometry by using the union function with KeepBoundaries set to true.

g = union(gm,KeepBoundaries=true);

Plot the result with cell labels.

figure
pdegplot(g,CellLabels="on")

Feature Angle of 3-D Geometry

Change the threshold value for dihedral angle between adjacent triangles for a fegeometry object.

Create an fegeometry object representing a unit circle. The circle consists of four edges with vertices connecting them.

g = fegeometry(@circleg);
pdegplot(g,VertexLabels="on",EdgeLabels="on")

Extrude the geometry into 3-D. The resulting geometry is a cylinder with its side consisting of four faces with the edges separating them. The edges come from the vertices of the original circle geometry.

g3D = extrude(g,2);
pdegplot(g3D,EdgeLabels="on", ...
             FaceLabels="on", ...
             FaceAlpha=0.3)

You can merge these faces by setting the FeatureAngle property of the geometry to a value greater than the default 44 degrees. For example, set the value to 45 degrees.

g3D.FeatureAngle = 45;
pdegplot(g3D,EdgeLabels="on", ...
    FaceLabels="on", ...
    FaceAlpha=0.3)

Tips

• For 3-D geometries symmetrical around an axis of rotation, you can speed up computations by simplifying a 3-D geometry to a 2-D geometry and setting the PlanarType property of femodel to "axisymmetric". The axis of rotation is the vertical axis, x = 0. The x–axis represents the radial component, and the y–axis represents the axial component.

Version History

Introduced in R2023a

R2026b: Import multidomain geometries from STEP files

You can now import a multidomain geometry from a STEP file. The resulting geometry contains multiple cells. You also can use VectorOutput to import a multidomain geometry as a vector of single-domain geometries.

R2026b: Specify FeatureAngle when importing a geometry from a STEP file

You can specify the FeatureAngle value when creating an fegeometry object by importing a geometry from a STEP file. This value sets the threshold for the dihedral angle between adjacent triangles to indicate the edge.

R2026b: Create a geometry from a polyshape object

You can use a polygonal shape, specified as a polyshape object, to create an fegeometry object.

R2025a: Use AllowSelfIntersections and FeatureAngle when creating geometries from triangulations

When creating a geometry from a triangulation object or from matrices of triangulation points and triangulation connectivity list, you can set the AllowSelfIntersections name-value argument to check for self intersecting geometries. You can also use the FeatureAngle name-value argument to specify a threshold for the dihedral angle between adjacent triangles to indicate the edge between separate faces.

R2024b: Create a geometry from an FEMesh object

You can use a mesh represented by an FEMesh object to create an fegeometry object. If the mesh data identifies multiple domains, the resulting geometry is multidomain.

R2024a: Import geometries using AllowSelfIntersections and FeatureAngle

When importing a geometry from a file, you can set the AllowSelfIntersections name-value argument to check for self intersecting geometries. You can also use the FeatureAngle name-value argument to specify a threshold for the dihedral angle between adjacent triangles to indicate the edge between separate faces.

Also, the fegeometry function now removes scratch edges when importing a geometry from an STL or STEP file. Scratch edges are the edges with both ends disconnected from the rest of the geometry edges.

R2023b: Create geometry from triangulation and delaunayTriangulation objects

You can use triangulation, specified as a triangulation or delaunayTriangulation object, to create an fegeometry object.