Registry / data / numpy-stl

numpy-stl

JSON →
library3.2.0pypypi✓ verified 84d ago

Numpy-stl is a Python library designed to simplify reading, writing, and modifying both binary and ASCII STL (stereolithography) files. Leveraging NumPy, it offers fast and efficient operations for 3D object manipulation. The library is currently at version 3.2.0, with regular updates that include bug fixes, new features, and compatibility enhancements for its core dependencies.

pip install numpy-stl
INSTALL
IMPORT
SIG · NUMPY-STL
N
numpy-stl
datapythonv3.2.0
Install
3.8s avg
Import
534ms
Disk
90MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.543s · 90.1MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 3.8s · import 0.525s · 86MB
90MB installed
● package 90MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

mesh
from stl import mesh
numpy
import numpy as np

This quickstart demonstrates how to create a simple cube mesh from vertices and faces and save it to an STL file. It also shows how to load an existing STL file and access some of its properties like the number of triangles and volume. The example includes creating a dummy file if one doesn't exist to ensure the loading part is runnable.

import numpy as np from stl import mesh import os # --- Create a new mesh from scratch --- # Define the 8 vertices of the cube vertices = np.array([ [-1, -1, -1], [+1, -1, -1], [+1, +1, -1], [-1, +1, -1], # Bottom square [-1, -1, +1], [+1, -1, +1], [+1, +1, +1], [-1, +1, +1] # Top square ]) # Define the 12 triangles (faces) composing the cube faces = np.array([ [0,3,1], [1,3,2], # Bottom [0,4,7], [0,7,3], # Front-left [4,5,6], [4,6,7], # Top [5,1,2], [5,2,6], # Back-right [2,3,6], [3,7,6], # Top-right [0,1,5], [0,5,4] # Bottom-left ]) # Create the mesh object cube = mesh.Mesh(np.zeros(faces.shape[0], dtype=mesh.Mesh.dtype)) for i, f in enumerate(faces): for j in range(3): cube.vectors[i][j] = vertices[f[j],:] # Save the mesh to a file output_filename = 'new_cube.stl' cube.save(output_filename) print(f"Saved new mesh to {output_filename}") # --- Load an existing STL file --- # Create a dummy file for demonstration if it doesn't exist if not os.path.exists('example.stl'): # In a real scenario, 'example.stl' would be an existing file. # For this quickstart, we'll save the cube we just created as 'example.stl' # just to demonstrate loading. cube.save('example.stl') try: your_mesh = mesh.Mesh.from_file('example.stl') print(f"Successfully loaded mesh from example.stl with {len(your_mesh.vectors)} triangles.") # Access mesh properties print(f"Volume: {your_mesh.get_mass_properties()[0]:.2f}") except Exception as e: print(f"Could not load example.stl: {e}")
Debug
Known issues
breakingNumpy-stl v3.2.0 adds support for NumPy 2.x, which includes significant API and ABI changes in NumPy itself. If you are using older versions of `numpy-stl` with NumPy 2.x, or if you compile extensions against an older NumPy and then try to run with NumPy 2.x, you may encounter compatibility issues.
fix
Upgrade to `numpy-stl` version 3.2.0 or newer to ensure full compatibility with NumPy 2.x. If using compiled extensions, recompile them against NumPy 2.x.
affects: <3.2.0
gotchaPrior to versions 3.0.0 and 2.17.1, `numpy-stl` had issues with floating-point number truncation. This could lead to a loss of precision in the saved or processed STL files, potentially affecting the geometry of the 3D models.
fix
Ensure you are using `numpy-stl` version 3.0.0 (or higher) or 2.17.1 (or higher) to benefit from the fixes that prevent floating-point truncation.
affects: <3.0.0 and <2.17.1
gotchaThe primary import for `numpy-stl` is `from stl import mesh`. If you have another Python package named `stl` installed on your system, it can lead to import conflicts and unexpected `ImportError` messages, as Python might import the wrong `stl` module.
fix
If you encounter `ImportError` related to 'stl' or 'mesh', check for other installed packages named 'stl' (e.g., `pip list | grep stl`). Uninstall any conflicting packages (e.g., `pip uninstall stl`) and then reinstall `numpy-stl` if necessary.
affects: All versions
Errors
Common errors & fixes
ImportError: cannot import name 'mesh' from 'stl'
This error typically occurs when Python either cannot find the `stl` module from `numpy-stl` or imports a different package also named `stl` that does not expose a `mesh` object. This is often due to a conflicting package or a broken installation.
fix
Verify that `numpy-stl` is correctly installed (`pip show numpy-stl`). Check for other installed packages named `stl` (e.g., using `pip list | grep stl`) and uninstall them if they are not `numpy-stl`'s module. Reinstall `numpy-stl` if the issue persists: `pip uninstall numpy-stl && pip install numpy-stl`.
TypeError: 'numpy.ndarray' object cannot be interpreted as an integer
This can happen when trying to create a `Mesh` object with an incorrect `dtype` or when improperly initializing the data array for the mesh, especially if `numpy.zeros` is not used with `mesh.Mesh.dtype` for the structure.
fix
Ensure that when creating a new mesh, the data array is initialized with the correct structured dtype from `mesh.Mesh.dtype`. For example: `data = np.zeros(num_faces, dtype=mesh.Mesh.dtype)`.
FileNotFoundError: [Errno 2] No such file or directory: 'some_file.stl'
This error occurs when `mesh.Mesh.from_file()` cannot find the specified STL file at the given path. This can be due to a typo in the filename, an incorrect relative path, or the file simply not existing.
fix
Double-check the filename and its full or relative path. Ensure the file exists in the expected location. Use `os.path.exists()` to verify the file's presence before attempting to load it.
Upgrade
Version history
3.2.0latest on PyPI · released Nov 25, 2024
Audit
Dependencies
numpyrequiredCore dependency for array operations and performance; version 3.2.0 adds support for NumPy 2.
python-utilsrequiredRequired for utility functions, version 1.6 or greater.
Agent activity
10 hits · last 30 days
node
8
OpenAI (training)
1
Resources
numpy-stl — pip install numpy-stl · libregistry