STL file reader

For loading triangulated surface geometry stored in the STL format, a widespread exchange format for 3D surface models written by CAD programs, 3D printing software, 3D modeling tools such as Blender, and mesh processing libraries. The reader produces a triangle mesh data object, which OVITO can display alongside particle-based simulation data, for example to show a container geometry, a tool, a substrate, or some other static object in the scene. Meshes loaded from STL files can also serve as user-defined particle shapes. Polygonal meshes stored in the Wavefront OBJ format are handled by a separate file reader.

Imported data

The file reader creates the following data in the pipeline’s file source:

Triangle mesh

A single triangle mesh object with the identifier mesh, consisting of the list of vertices and the list of triangular faces read from the file. The mesh is rendered by a Triangle mesh visual element, which controls its color, transparency, and the optional highlighting of polygon edges. In Python, the imported TriangleMesh can be found in the DataCollection.objects list.

Since the format describes a single static geometry, the reader does not load trajectories from a single file. A numbered sequence of files (e.g. mesh.0.stl, mesh.1.stl, …) can however be imported as an animation sequence using a wildcard file pattern, as described in Simulation trajectories.

The format stores no simulation cell, per-vertex or per-face properties, or global attributes; no such data is created by the reader. The loaded mesh can be moved, rotated, and scaled with the Affine transformation modifier.

STL files come in two variants, an ASCII text form and a binary form, both of which are supported. The reader determines the variant automatically: a file whose first line begins with the keyword solid and whose next non-blank line is a facet normal record is read as an ASCII STL file; otherwise it is treated as a binary STL file, provided that the file size is consistent with the number of triangles stated in the binary header (80-byte header followed by a 32-bit triangle count and 50 bytes per triangle). Binary files whose header text happens to begin with the word solid are recognized correctly. Automatic format detection additionally requires the file name to end with the suffix .stl (case-insensitive). Files with a different suffix can be loaded by selecting the format explicitly, e.g. input_format='stl' in import_file().

STL files do not share vertices between triangles; the three corners of every facet are listed separately. After reading the file, OVITO merges coincident vertices (those closer than \(10^{-8}\) times the diagonal of the mesh’s bounding box) so that adjacent triangles share their corner vertices and the mesh becomes a connected surface. Subsequently, OVITO marks those polygon edges as visible along which the normals of the two adjacent faces differ by more than 20 degrees. These edges are drawn when the Highlight edges option of the visual element is turned on, which outlines the sharp features of the model without cluttering flat or smoothly curved regions with triangle edges.

Limitations

  • The facet normals stored in the file (facet normal records or the normal vectors of the binary format) are ignored. The orientation of each triangle is determined from the order of its vertices, and shading normals are computed from the geometry.

  • The name given on the solid line of an ASCII file and the 80-byte header of a binary file are ignored.

  • Only the first solid of an ASCII file containing several solid … endsolid blocks is imported.

  • The per-triangle attribute field of the binary format, which some programs use to store face colors, is ignored.

  • Binary STL files containing 10 million or more triangles are rejected.

  • Compressed STL files (“.gz” suffix) are not supported.

Options

This file reader has no user-adjustable options.

Python parameters

The file reader accepts no format-specific keyword parameters in a call to the import_file() or load() Python functions.