GitHub - pyvista/stl-reader: Fast STL file reader (original) (raw)

stl-reader

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:

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

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

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.