Import of STL graphics files
This functionality does not run in MATLAB.
plot::SurfaceSTL(filename, <UseNormals = b>, <a = amin .. amax>, options)
plot::SurfaceSTL(filename) creates a 3D surface object from the data of a given STL graphics file named "filename".
Stereolithography (STL) files were introduced in software by 3D Systems of Valencia, CA, as a simple method of storing information about 3D objects.
STL files contain triangulation data of 3D surfaces. Each triangle is stored as a unit normal and three vertices. The normal and the vertices are specified by three coordinates each, so there is a total of 12 numbers stored for each triangle. Read the ‘Background' section of this help page for further details.
Depending on your hardware we recommend to plot STL objects with no more than 50.000 to 150.000 facets (triangles). You should activate the option ‘Accelerate OpenGL®' in the VCam options menu.
plot::SurfaceSTL reacts to the MuPAD® environment variable READPATH. For example, after
>> READPATH := READPATH, "C:\\STLFILES":
the file ‘C:\STLFILES\xyz.stl' is found by the command
>> S := plot::SurfaceSTL("xyz.stl"):
Alternatively, the file name can be specified as an absolute pathname:
>> S := plot::SurfaceSTL("C:\\STLFILES\\xyz.stl"):
If a MuPAD notebook was saved to a file, its location is available inside the notebook as the environment variable NOTEBOOKPATH. If your STL file is in the same folder as the notebook, you may call
>> S := plot::SurfaceSTL(NOTEBOOKPATH."xyz.stl"):
When setting the attribute UseNormals to FALSE, the normals defined in the STL graphics file are ignored when plotting the object in MuPAD. This reduces the data volume of the graphics object in the MuPAD session and improves the computing time as well. However, it leads to a slightly less brilliant image. Cf. Example 2.
Also user-defined color functions LineColorFunction and FillColorFunction can be used to color the imported surface. These functions are called with the index of the current triangle as its first parameter, followed by the x, y, and z coordinate of the current point.
If an object of type plot::SurfaceSTL is to be plotted together with other objects, one needs to know the coordinates of the surface objects. To this end, an object S := plot::SurfaceSTL(...) provides the methods S::center and S::boundingBox.
The call S::center() returns a list of 3 floating-point values representing the 3D center of the STL object.
The call S::boundingBox() returns a list of 3 ranges of floating-point values representing the ranges for the x, y, and z coordinates of the STL surface.
plot::SurfaceSTL::center(S) and plot::SurfaceSTL::boundingBox(S), respectively, are alternative calls.
Note that the STL graphics file must be read completely for computing these data. Also note that after a first call to S::center() or S::boundingBox(), the data are not recomputed by these functions even if the STL object S has changed. Use plot::SurfaceSTL::center(S), plot::SurfaceSTL::boundingBox(S) in such a case.
|AffectViewingBox||influence of objects on the ViewingBox of a scene||TRUE|
|Color||the main color||RGB::Red|
|Filled||filled or transparent areas and surfaces||TRUE|
|FillColor||color of areas and surfaces||RGB::Red|
|FillColor2||second color of areas and surfaces for color blends||RGB::CornflowerBlue|
|FillColorType||surface filling types||Dichromatic|
|FillColorFunction||functional area/surface coloring|
|FillColorDirection||the direction of color transitions on surfaces||[0, 0, 1]|
|FillColorDirectionX||x-component of the direction of color transitions on surfaces||0|
|FillColorDirectionY||y-component of the direction of color transitions on surfaces||0|
|FillColorDirectionZ||z-component of the direction of color transitions on surfaces||1|
|Frames||the number of frames in an animation||50|
|InputFile||input file for import functions|
|Legend||makes a legend entry|
|LegendText||short explanatory text for legend|
|LegendEntry||add this object to the legend?||FALSE|
|LineColor||color of lines||RGB::Black.[0.25]|
|LineWidth||width of lines||0.35|
|LineColor2||color of lines||RGB::DeepPink|
|LineStyle||solid, dashed or dotted lines?||Solid|
|LineColorType||line coloring types||Flat|
|LineColorFunction||functional line coloring|
|LineColorDirection||the direction of color transitions on lines||[0, 0, 1]|
|LineColorDirectionX||x-component of the direction of color transitions on lines||0|
|LineColorDirectionY||y-component of the direction of color transitions on lines||0|
|LineColorDirectionZ||z-component of the direction of color transitions on lines||1|
|MeshVisible||visibility of irregular mesh lines in 3D||FALSE|
|Name||the name of a plot object (for browser and legend)|
|ParameterEnd||end value of the animation parameter|
|ParameterName||name of the animation parameter|
|ParameterBegin||initial value of the animation parameter|
|ParameterRange||range of the animation parameter|
|PointSize||the size of points||1.5|
|PointStyle||the presentation style of points||FilledCircles|
|PointsVisible||visibility of mesh points||FALSE|
|Shading||smooth color blend of surfaces||Smooth|
|TimeEnd||end time of the animation||10.0|
|TimeBegin||start time of the animation||0.0|
|TimeRange||the real time span of an animation||0.0 .. 10.0|
|TitleFont||font of object titles||[" sans-serif ", 11]|
|TitlePosition||position of object titles|
|TitleAlignment||horizontal alignment of titles w.r.t. their coordinates||Center|
|TitlePositionX||position of object titles, x component|
|TitlePositionY||position of object titles, y component|
|TitlePositionZ||position of object titles, z component|
|UseNormals||use pre-defined normals?||TRUE|
|VisibleAfter||object visible after this time value|
|VisibleBefore||object visible until this time value|
|VisibleFromTo||object visible during this time range|
|VisibleAfterEnd||object visible after its animation time ended?||TRUE|
|VisibleBeforeBegin||object visible before its animation time starts?||TRUE|
The following imported STL graphics consists of about 110.000 triangles:
plot(plot::SurfaceSTL("hand.stl"), CameraDirection = [15, 13, 22])
By default, the normals defined in an STL graphics file are used when plotting the object in MuPAD. Suppressing the use of these normals may reduce the data volume of the graphical object and speed up plotting. However, in general, this leads to slightly less brilliant images. For comparison, the following STL graphics is plotted with and without using its normals:
S1 := plot::SurfaceSTL("skin.stl"): S2 := plot::SurfaceSTL("skin.stl", UseNormals = FALSE): plot(plot::Scene3d(S1), plot::Scene3d(S2), Layout = Vertical, Width = 120*unit::mm, Height = 140*unit::mm, Axes = None, BackgroundStyle = Pyramid):
We compute the center and the bounding box of the surface:
We rotate the object around its center:
plot(plot::Rotate3d(a, S1::center(), [0, 0, 1], S1, a = 0..2*PI), Axes = None)
delete S1, S2:
The following STL graphics is displayed as a surface model and as a wireframe model:
nut := plot::SurfaceSTL("nut.stl"): plot(plot::Scene3d(nut, CameraDirection = [10, 15, 30]), plot::Scene3d(nut, CameraDirection = [10, 15, 30], MeshVisible = TRUE, Filled = FALSE, LineColor = RGB::Black), Axes = None, Layout = Horizontal, BackgroundStyle = Pyramid):
For demonstrating further features of STL file import, we first create our own STL graphics file which defines a tetrahedron:
stlFile := "demo.stl":
fprint(Unquoted, Text, stlFile, "SOLID TRI FACET NORMAL 0.0 0.0 -1.0 OUTER LOOP VERTEX -1.5 -1.5 1.4 VERTEX 0.0 1.7 1.4 VERTEX 1.5 -1.5 1.4 ENDLOOP ENDFACET FACET NORMAL 0.0 0.88148 0.472221 OUTER LOOP VERTEX -1.5 -1.5 1.4 VERTEX 1.5 -1.5 1.4 VERTEX 0.0 0.0 -1.4 ENDLOOP ENDFACET FACET NORMAL -0.876814 -0.411007 0.24954 OUTER LOOP VERTEX 1.5 -1.5 1.4 VERTEX 0.0 1.7 1.4 VERTEX 0.0 0.0 -1.4 ENDLOOP ENDFACET FACET NORMAL 0.876814 -0.411007 0.24954 OUTER LOOP VERTEX 0.0 1.7 1.4 VERTEX -1.5 -1.5 1.4 VERTEX 0.0 0.0 -1.4 ENDLOOP ENDFACET ENDSOLID TRI" )
This STL graphics file is imported as a MuPAD plot object and rendered:
plot(plot::SurfaceSTL(stlFile, MeshVisible = TRUE)):
We create another STL file using export::stl. It contains a sphere of radius 1 parametrized by spherical coordinates:
export::stl("sphere.stl", [cos(u)*sin(v), sin(u)*sin(v), cos(v)], u = 0 .. 2*PI, v = 0 .. 2*PI, Mesh = [50, 50], Scaling = Constrained, OutputBox = [-1 .. 1, -1 .. 1, -1 .. 1]):
plot(plot::SurfaceSTL("sphere.stl", Scaling = Constrained)):
We plot the object defined in the STL graphics file of Example 4 with its bounding box:
S := plot::SurfaceSTL(stlFile): plot(S, plot::Box(op(S::boundingBox()), Color = RGB::Blue.[0.1])):
A color function FillColorFunction can be specified. This will be called with the index of the current facet as its first parameter followed by the x-, y- and z-coordinate of the current point.
We use the object defined in the STL graphics file of Example 4:
mycolorlist:= [RGB::Red, RGB::Blue, RGB::Green, RGB::Yellow]: plot(plot::Scene3d(plot::SurfaceSTL(stlFile, FillColorFunction = proc(n, x, y, z) begin mycolorlist[n] end_proc)), plot::Scene3d(plot::SurfaceSTL(stlFile, FillColorFunction = proc(n, x, y, z) begin [abs(x)/2, abs(y)/2, abs(z)/2] end_proc)), Axes = None, Layout = Horizontal):
We define a LineColorFunction:
plot(plot::Scene3d(plot::SurfaceSTL(stlFile, LineColorFunction = proc(n, x, y, z) begin mycolorlist[n] end_proc)), plot::Scene3d(plot::SurfaceSTL(stlFile, LineColorFunction = proc(n, x, y, z) begin [abs(x)/2, abs(y)/2, abs(z)/2] end_proc)), Axes = None, Filled = FALSE, MeshVisible = TRUE, LineWidth = 2*unit::mm, Layout = Horizontal):
Again, we plot the object of the STL graphics file defined in Example 4. Here, we add rotated, scaled and translated copies:
plot( plot::Scene3d( plot::SurfaceSTL(stlFile), plot::Scale3d([2, 2, 2], plot::SurfaceSTL(stlFile, Color = RGB::Blue.[0.1]) ) ), plot::Scene3d( plot::SurfaceSTL(stlFile), plot::Rotate3d(PI, Axis = [1, 0, 0], plot::SurfaceSTL(stlFile, Color = RGB::Blue.[0.1]) ) ), plot::Scene3d( plot::SurfaceSTL(stlFile), plot::Translate3d([1, 1, 1], plot::SurfaceSTL(stlFile, Color = RGB::Blue.[0.1]) ) ), plot::Scene3d( plot::SurfaceSTL(stlFile), plot::Transform3d([0, 0, 0], [1, 0, 0, 0, 1, 0, 0, 0, -1], plot::SurfaceSTL(stlFile, Color = RGB::Blue.[0.1]) ) ), Width = 120*unit::mm, Height = 120*unit::mm):
STL objects can be animated. The tetrahedron defined in Example 4 moves around a box:
SO := plot::SurfaceSTL(stlFile): BO := plot::Box(op(SO::boundingBox(SO)), Color = RGB::Blue.[0.1]): GO := [6*sin(a), -6*cos(a), 4*cos(2*a)], a = 0..2*PI: CU := plot::Curve3d(GO): plot(BO, CU, plot::Translate3d(GO, SO), ViewingBox = [-8..8, -8..8, -6..6]):
Below, the color function FillColorFunction of an STL object is animated:
plot(plot::SurfaceSTL(stlFile, MeshVisible = TRUE, LineColor = RGB::Black, FillColorFunction = proc(n, x, y, z) begin [sin(x + a)^2 ,sin(y + a)^2, sin(z + a)^2] end_proc, a = 0..2*PI, TimeRange = 1..4), Axes = None, Layout = Horizontal)
delete SO, BO, GO, CU, stlFile:
The file name: a character string of type DOM_STRING.
filename is equivalent to the attribute InputFile.
Animation parameter, specified as a = amin..amax, where amin is the initial parameter value, and amax is the final parameter value.
Option, specified as UseNormals = b
The STL sample files presented on this help page were taken from the ftp site of the Clemson University, South Carolina, USA:
There are two storage formats available for STL files, which are ASCII and BINARY. ASCII files are human-readable while BINARY files are smaller and faster to process. Both formats can be read by plot::SurfaceSTL. A typical ASCII STL file looks like this:
solid sample facet normal -4.470293E-02 7.003503E-01 -7.123981E-01 outer loop vertex -2.812284E+00 2.298693E+01 0.000000E+00 vertex -2.812284E+00 2.296699E+01 -1.960784E-02 vertex -3.124760E+00 2.296699E+01 0.000000E+00 endloop endfacet ... endsolid sample
STL BINARY files have the following format:
Bytes Type Description 80 ASCII header, no data significance 4 uint number of facets in file 4 float normal x - start of facet 4 float normal y 4 float normal z 4 float vertex1 x 4 float vertex1 y 4 float vertex1 z 4 float vertex2 x 4 float vertex2 y 4 float vertex2 z 4 float vertex3 x 4 float vertex3 y 4 float vertex3 z 2 byte not used - end of facet ...
Facet orientation: The facets define the surface of a 3D object. As such, each facet is part of the boundary between the interior and the exterior of the object. The orientation of the facets (which way is "out" and which way is "in") is specified redundantly in two ways which should be consistent. First, the direction of the normal is outward. Second, which is most commonly used nowadays, the facet vertices are listed in counterclockwise order when looking at the object from the outside (right-hand rule).
Vertex-to-vertex rule: Each triangle must share two vertices with each of its adjacent triangles. In other words, a vertex of one triangle cannot lie on the side of another.
Axes: The format specifies that all vertex coordinates must be strictly positive numbers. However, it seems that — with a few exceptions — most software used today (MuPAD included) allow negative coordinates as well.
Units: The STL file does not contain any scale information; the coordinates may be interpreted in arbitrary units.
Further details about the STL file format are available in the web, e.g., at:
Collections of STL sample files can be found in the web, e.g., at:
Information about rapid prototyping technologies is available in the web, e.g., at:
Note that MuPAD only accepts the following notations for the keywords "facet" and "vertex" in STL ASCII files: facet, FACET, Facet and vertex, VERTEX, Vertex, respectively.
The normal of a facet defined in an STL file is used for all its vertices when plotting this object. Due to the fact that some facets (triangles) share points with other ones, these points are plotted with different normals.