Documentation Center

  • Trial Software
  • Product Updates

plot::SurfaceSTL

Import of STL graphics files

Use only in the MuPAD Notebook Interface.

This functionality does not run in MATLAB.

Syntax

plot::SurfaceSTL(filename, <UseNormals = b>, <a = amin .. amax>, options)

Description

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.

The STL data do not include any color information. Hence, the imported graphics reacts to the usual settings of FillColor, FillColorType etc. for MuPAD surfaces.

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.

The transformation objects plot::Rotate3d, plot::Scale3d, plot::Translate3d and plot::Transform3d can be applied to the imported STL object. Cf. Example 7.

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.

See Example 2 and Example 5.

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.

Attributes

AttributePurposeDefault Value
AffectViewingBoxinfluence of objects on the ViewingBox of a sceneTRUE
Colorthe main colorRGB::Red
Filledfilled or transparent areas and surfacesTRUE
FillColorcolor of areas and surfacesRGB::Red
FillColor2second color of areas and surfaces for color blendsRGB::CornflowerBlue
FillColorTypesurface filling typesDichromatic
FillColorFunctionfunctional area/surface coloring 
FillColorDirectionthe direction of color transitions on surfaces[0, 0, 1]
FillColorDirectionXx-component of the direction of color transitions on surfaces0
FillColorDirectionYy-component of the direction of color transitions on surfaces0
FillColorDirectionZz-component of the direction of color transitions on surfaces1
Framesthe number of frames in an animation50
InputFileinput file for import functions 
Legendmakes a legend entry 
LegendTextshort explanatory text for legend 
LegendEntryadd this object to the legend?FALSE
LineColorcolor of linesRGB::Black.[0.25]
LineWidthwidth of lines0.35
LineColor2color of linesRGB::DeepPink
LineStylesolid, dashed or dotted lines?Solid
LineColorTypeline coloring typesFlat
LineColorFunctionfunctional line coloring 
LineColorDirectionthe direction of color transitions on lines[0, 0, 1]
LineColorDirectionXx-component of the direction of color transitions on lines0
LineColorDirectionYy-component of the direction of color transitions on lines0
LineColorDirectionZz-component of the direction of color transitions on lines1
MeshVisiblevisibility of irregular mesh lines in 3DFALSE
Namethe name of a plot object (for browser and legend) 
ParameterEndend value of the animation parameter 
ParameterNamename of the animation parameter 
ParameterBegininitial value of the animation parameter 
ParameterRangerange of the animation parameter 
PointSizethe size of points1.5
PointStylethe presentation style of pointsFilledCircles
PointsVisiblevisibility of mesh pointsFALSE
Shadingsmooth color blend of surfacesSmooth
TimeEndend time of the animation10.0
TimeBeginstart time of the animation0.0
TimeRangethe real time span of an animation0.0 .. 10.0
Titleobject title 
TitleFontfont of object titles[" sans-serif ", 11]
TitlePositionposition of object titles 
TitleAlignmenthorizontal alignment of titles w.r.t. their coordinatesCenter
TitlePositionXposition of object titles, x component 
TitlePositionYposition of object titles, y component 
TitlePositionZposition of object titles, z component 
UseNormalsuse pre-defined normals?TRUE
VisiblevisibilityTRUE
VisibleAfterobject visible after this time value 
VisibleBeforeobject visible until this time value 
VisibleFromToobject visible during this time range 
VisibleAfterEndobject visible after its animation time ended?TRUE
VisibleBeforeBeginobject visible before its animation time starts?TRUE

Examples

Example 1

The following imported STL graphics consists of about 110.000 triangles:

plot(plot::SurfaceSTL("hand.stl"),
     CameraDirection = [15, 13, 22])

Example 2

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:

S1::center()

S1::boundingBox()

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:

Example 3

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

delete nut:

Example 4

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

Example 5

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])):

delete S:

Example 6

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

delete mycolorlist:

Example 7

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

Example 8

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:

Parameters

filename

The file name: a character string of type DOM_STRING.

filename is equivalent to the attribute InputFile.

a

Animation parameter, specified as a = amin..amax, where amin is the initial parameter value, and amax is the final parameter value.

Options

UseNormals

Option, specified as UseNormals = b

b may be TRUE or FALSE. This attribute specifies whether the normals defined in the STL file are used for the MuPAD plot.

Algorithms

The STL sample files presented on this help page were taken from the ftp site of the Clemson University, South Carolina, USA:

ftp.vr.clemson.edu/pub/rp/STL_objects.

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:

  • www.ennex.com/fabbers/StL.asp,

  • www.math.iastate.edu/burkardt/data/stl/stl.html and

  • rpdrc.ic.polyu.edu.hk/content/stl/stl_introduction.htm.

Collections of STL sample files can be found in the web, e.g., at:

  • www.wohlersassociates.com/Software-for-Rapid-Prototyping.html and

  • www.cs.duke.edu/~edels/Tubes.

Information about rapid prototyping technologies is available in the web, e.g., at:

www.cs.hut.fi/~ado/rp/rp.html.

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.

See Also

MuPAD Functions

MuPAD Graphical Primitives

Was this topic helpful?