importGeometry

R2026b

Import geometry from STL or STEP file

Syntax

gm = importGeometry(geometryfile)

gm = importGeometry(model,geometryfile)

importGeometry(model,___)

___ = importGeometry(___,Name=Value)

Description

gm = importGeometry(geometryfile) creates a geometry object from the specified STL or STEP geometry file. A geometry imported from an STL file can be 3-D or planar. A geometry imported from a STEP file must be 3-D.

gm = importGeometry(model,geometryfile) also includes the geometry in the model container.

importGeometry(model,___) creates a geometry object from the specified STL or STEP geometry file and includes the geometry in the model container.

___ = importGeometry(___,Name=Value) creates a geometry object using one or more name-value arguments. Use this syntax with any of the argument combinations from the previous syntaxes.

Examples

Import 3-D Geometry from STL File Without Creating Model

Create a geometry object from an STL geometry file.

gm = importGeometry("ForearmLink.stl");

Plot the geometry.

pdegplot(gm)

Import Planar Geometry from STL File into Model

Import a planar STL geometry and include it in a PDE model. When importing a planar geometry, importGeometry converts it to a 2-D geometry by mapping it to the xy-plane.

Create a PDEModel container.

model = createpde;

Import a geometry into the container.

importGeometry(model,"PlateHolePlanar.stl")

ans = 
  DiscreteGeometry with properties:

       NumCells: 0
       NumFaces: 1
       NumEdges: 5
    NumVertices: 5
       Vertices: [5×3 double]

Plot the geometry with the edge labels.

pdegplot(model,EdgeLabels="on")

Import 3-D Geometry from STEP File

Create a geometry object from a STEP geometry file.

gm = importGeometry("BlockWithHole.step");

Plot the geometry.

pdegplot(gm,FaceAlpha=0.3)

Now import the same geometry while specifying the relative sag. You can use this parameter to control the accuracy of the geometry import.

gm = importGeometry("BlockWithHole.step",MaxRelativeDeviation=0.1);

Plot the geometry.

pdegplot(gm,FaceAlpha=0.3)

Import 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, importGeometry imports the file as a single multidomain geometry.

gm = importGeometry("Hemispheres.step")

gm = 
  DiscreteGeometry with properties:

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

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 = importGeometry("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(fegeometry(gm),KeepBoundaries=true);

Plot the result with cell labels.

figure
pdegplot(g,CellLabels="on")

Input Arguments

model — Model container

PDEModel object

Model container, specified as a PDEModel object.

Example: model = createpde(3)

geometryfile — Path to STL or STEP file

string scalar | character vector

Path to STL or STEP file, specified as a string scalar or a character vector ending with the file extension ".stl", ".stp", or ".step". You can also use the uppercase extensions ".STL", ".STP" or ".STEP", or any combinations of uppercase and lowercase letters in these extensions.

Tip

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

Example: "../geometries/Carburetor.stl"

Data Types: string | char

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 = importGeometry("AngleBlock.step",MaxRelativeDeviation=5)

AllowSelfIntersections — Indicator to allow import of self-intersecting geometry

true or 1 (default) | false or 0

Indicator to allow import of self-intersecting geometry from an STL or STEP file, specified as true or false. You also can use 1 or 0 instead of true or false. By default, importGeometry does not check for self-intersections and lets you import such geometries. If you set AllowSelfIntersections to false or 0, importGeometry throws an error for a geometry with self-intersections.

Example: gm = importGeometry("GeometryWithSelfIntersectons.stl",AllowSelfIntersections=true)

FeatureAngle — Threshold for dihedral angle between adjacent triangles to indicate edge between separate faces

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. Specify the FeatureAngle value in degrees.

If the angle between the triangles exceeds the threshold, the edge becomes a topological (feature) edge separating two faces. If it does not exceed the threshold, importGeometry does not create a topological edge with two separate faces, unless the edge can be created based on other criteria. Instead, importGeometry treats it as one face.

Example: gm = importGeometry("Geometry.stl",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: gm = importGeometry("AngleBlock.step",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, importGeometry recognizes if a STEP file represents a multidomain geometry and imports it as one geometry with multiple cells. If the resulting geometry is invalid, importGeometry 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 = importGeometry("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

Output Arguments

gm — Geometry

DiscreteGeometry object

Geometry, returned as a DiscreteGeometry object.

Tips

• The STL format approximates the boundary of a CAD geometry by using a collection of triangles, and the importGeometry function reconstructs the faces and edges from this data. Reconstruction from STL data is not precise and can result in a loss of edges and, therefore, the merging of adjacent faces. Typically, lost edges are the edges between two adjacent faces meeting at a small angle, or smooth edges bounding blend surfaces. Usually, the loss of such edges does not affect the analysis workflow.

• Because STL geometries are only approximations of the original CAD geometries, the areas and volumes of the STL and CAD geometries can differ.

Version History

Introduced in R2015a

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 importing a geometry from a STEP file. This value sets the threshold for the dihedral angle between adjacent triangles to indicate the edge.

R2025a: To be removed: structural, thermal, and electromagnetic analysis models

importGeometry will no longer accept StructuralModel, ThermalModel, and ElectromagneticModel. These objects will be removed. To import a geometry for structural, thermal, or electromagnetic analysis, use femodel or fegeometry.

importGeometry will continue accepting PDEModel.

The unified finite element model workflow defines the type of a problem and all of its parameters as the properties of an femodel object. This object enables you to specify physical parameters for structural, thermal, and electromagnetic types of analyses. The solver in the unified workflow uses only the parameters (properties) appropriate for the current analysis type while ignoring all other properties. If you switch the analysis type by setting the AnalysisType property of the model, the solver uses the appropriate set of properties corresponding to the new analysis type.

For more help migrating your existing code that uses StructuralModel, ThermalModel, or ElectromagneticModel to the unified finite element workflow, see Migration from Domain-Specific to Unified Workflow.

R2024a: Import geometries using AllowSelfIntersection and FeatureAngle

When importing a geometry from a file, you can check for self intersections and specify a threshold for dihedral angle between adjacent triangles to indicate edge between separate faces.

Also, the 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.

R2022b: Import from STEP files

You can now import a geometry from a STEP file. When importing from a STEP file, you can control the accuracy of the geometry import by specifying the relative sag value.

R2021a: Import without creating a model

You can now create a geometry object from an STL geometry file without attaching the imported geometry to any model. The new syntax is g = importGeometry('geometryfile.stl').

R2017b: Import and mesh planar STL geometries

You can now import a planar STL geometry and convert it to a 2-D geometry by mapping it to the xy-plane.

R2016b: Improved quality of STL import

When importing an STL geometry for a 3-D problem, the function can now recognize and reconstruct more geometric vertices, edges, and faces of the original CAD geometry in some instances. In these cases, the resulting geometry is a closer match to the original CAD geometry.

Detailed geometries can now contain more faces and edges than in previous releases. As a result, in rare instances, the new faces and edges can cause renumbering of the existing ones. If your code imports an STL geometry, visually check the geometry to ensure that you are assigning boundary and initial conditions to the intended regions.