stl-reader 0.2.3

Read in STL files

stl-reader is a Python library for rapidly reading binary and ASCII STL files. It wraps a nanobind interface to the fast STL library provided by libstl. Thanks @aki5!

The main advantage of stl-reader over other STL reading libraries is its performance. It is particularly well-suited for large files, mainly due to its efficient use of hashing when merging points. This results in a 5-35x speedup over VTK for files containing between 4,000 and 9,000,000 points.

See the benchmarks below for more details.

Installation

The recommended way to install stl-reader is via PyPI:

pip install stl-reader

You can also clone the repository and install it from source:

git clone https://github.com/pyvista/stl-reader.git
cd stl-reader
pip install .

Usage

Load in the vertices and indices of a STL file directly as a NumPy array:

>>> import stl_reader
>>> vertices, indices = stl_reader.read("example.stl")
>>> vertices
array([[-0.01671113,  0.5450843 , -0.8382146 ],
       [ 0.01671113,  0.5450843 , -0.8382146 ],
       [ 0.        ,  0.52573115, -0.8506509 ],
       ...,
       [ 0.5952229 , -0.57455426,  0.56178033],
       [ 0.56178033, -0.5952229 ,  0.57455426],
       [ 0.57455426, -0.56178033,  0.5952229 ]], dtype=float32)
>>> indices
array([[      0,       1,       2],
       [      1,       3,       4],
       [      4,       5,       2],
       ...,
       [9005998, 9005988, 9005999],
       [9005999, 9005996, 9005995],
       [9005998, 9005999, 9005995]], dtype=uint32)

In this example, vertices is a 2D NumPy array where each row represents a vertex and the three columns represent the X, Y, and Z coordinates, respectively. indices is a 1D NumPy array representing the triangles from the STL file.

Alternatively, you can load in the STL file as a PyVista PolyData:

>>> import stl_reader
>>> mesh = stl_reader.read_as_mesh('example.stl')
>>> mesh
PolyData (0x7f43063ec700)
  N Cells:    1280000
  N Points:   641601
  N Strips:   0
  X Bounds:   -5.000e-01, 5.000e-01
  Y Bounds:   -5.000e-01, 5.000e-01
  Z Bounds:   -5.551e-17, 5.551e-17
  N Arrays:   0

Benchmark

The main reason behind writing yet another STL file reader for Python is to leverage the performant libstl library.

Here are some timings from reading in a 1,000,000 point binary STL file:

Library	Time (seconds)
stl-reader	0.174
numpy-stl	0.201 (see note)
PyVista (VTK)	1.663
meshio	4.451

Note numpy-stl does not merge duplicate vertices.

Comparison with VTK

Here’s an additional benchmark comparing VTK with stl-reader:

import numpy as np
import time
import pyvista as pv
import matplotlib.pyplot as plt
import stl_reader

times = []
filename = 'tmp.stl'
for res in range(50, 800, 50):
    mesh = pv.Plane(i_resolution=res, j_resolution=res).triangulate().subdivide(2)
    mesh.save(filename)

    tstart = time.time()
    out_pv = pv.read(filename)
    vtk_time = time.time() - tstart

    tstart = time.time()
    out_stl = stl_reader.read(filename)
    stl_reader_time =  time.time() - tstart

    times.append([mesh.n_points, vtk_time, stl_reader_time])
    print(times[-1])


times = np.array(times)
plt.figure(1)
plt.title('STL load time')
plt.plot(times[:, 0], times[:, 1], label='VTK')
plt.plot(times[:, 0], times[:, 2], label='stl_reader')
plt.xlabel('Number of Points')
plt.ylabel('Time to Load (seconds)')
plt.legend()

plt.figure(2)
plt.title('STL load time (Log-Log)')
plt.loglog(times[:, 0], times[:, 1], label='VTK')
plt.loglog(times[:, 0], times[:, 2], label='stl_reader')
plt.xlabel('Number of Points')
plt.ylabel('Time to Load (seconds)')
plt.legend()
plt.show()

Read in ASCII Meshes

The stl-reader also supports ASCII files and is around 2.4 times faster than VTK at reading ASCII files.

import time
import stl_reader
import pyvista as pv
import numpy as np

# create and save a ASCII file
n = 1000
mesh = pv.Plane(i_resolution=n, j_resolution=n).triangulate()
mesh.save("/tmp/tmp-ascii.stl", binary=False)

# stl reader
tstart = time.time()
mesh = stl_reader.read_as_mesh("/tmp/tmp-ascii.stl")
print("stl-reader    ", time.time() - tstart)

tstart = time.time()
pv_mesh = pv.read("/tmp/tmp-ascii.stl")
print("pyvista reader", time.time() - tstart)

# verify meshes are identical
assert np.allclose(mesh.points, pv_mesh.points)

# approximate time to read in the 1M point file:
# stl-reader     0.80303955078125
# pyvista reader 1.916085958480835

License and Acknowledgments

This project relies on libstl for reading in and merging the vertices of a STL file. Wherever code is reused, the original MIT License is mentioned.

The work in this repository is also licensed under the MIT License.

Support

If you are having issues, please feel free to raise an Issue.