{"id":7458,"library":"numpy-stl","title":"numpy-stl","description":"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.","status":"active","version":"3.2.0","language":"en","source_language":"en","source_url":"https://github.com/WoLpH/numpy-stl/","tags":["stl","3d","numpy","mesh","cad","3d-printing","geometry","file-io"],"install":[{"cmd":"pip install numpy-stl","lang":"bash","label":"PyPI"}],"dependencies":[{"reason":"Core dependency for array operations and performance; version 3.2.0 adds support for NumPy 2.","package":"numpy","optional":false},{"reason":"Required for utility functions, version 1.6 or greater.","package":"python-utils","optional":false}],"imports":[{"symbol":"mesh","correct":"from stl import mesh"},{"symbol":"numpy","correct":"import numpy as np"}],"quickstart":{"code":"import numpy as np\nfrom stl import mesh\nimport os\n\n# --- Create a new mesh from scratch ---\n\n# Define the 8 vertices of the cube\nvertices = np.array([\n    [-1, -1, -1], [+1, -1, -1], [+1, +1, -1], [-1, +1, -1], # Bottom square\n    [-1, -1, +1], [+1, -1, +1], [+1, +1, +1], [-1, +1, +1]  # Top square\n])\n\n# Define the 12 triangles (faces) composing the cube\nfaces = np.array([\n    [0,3,1], [1,3,2], # Bottom\n    [0,4,7], [0,7,3], # Front-left\n    [4,5,6], [4,6,7], # Top\n    [5,1,2], [5,2,6], # Back-right\n    [2,3,6], [3,7,6], # Top-right\n    [0,1,5], [0,5,4]  # Bottom-left\n])\n\n# Create the mesh object\ncube = mesh.Mesh(np.zeros(faces.shape[0], dtype=mesh.Mesh.dtype))\nfor i, f in enumerate(faces):\n    for j in range(3):\n        cube.vectors[i][j] = vertices[f[j],:]\n\n# Save the mesh to a file\noutput_filename = 'new_cube.stl'\ncube.save(output_filename)\nprint(f\"Saved new mesh to {output_filename}\")\n\n# --- Load an existing STL file ---\n# Create a dummy file for demonstration if it doesn't exist\nif not os.path.exists('example.stl'):\n    # In a real scenario, 'example.stl' would be an existing file.\n    # For this quickstart, we'll save the cube we just created as 'example.stl'\n    # just to demonstrate loading.\n    cube.save('example.stl')\n\ntry:\n    your_mesh = mesh.Mesh.from_file('example.stl')\n    print(f\"Successfully loaded mesh from example.stl with {len(your_mesh.vectors)} triangles.\")\n    # Access mesh properties\n    print(f\"Volume: {your_mesh.get_mass_properties()[0]:.2f}\")\nexcept Exception as e:\n    print(f\"Could not load example.stl: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"Numpy-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.","severity":"breaking","affected_versions":"<3.2.0"},{"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.","message":"Prior 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.","severity":"gotcha","affected_versions":"<3.0.0 and <2.17.1"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","cause":"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.","error":"ImportError: cannot import name 'mesh' from 'stl'"},{"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)`.","cause":"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.","error":"TypeError: 'numpy.ndarray' object cannot be interpreted as an integer"},{"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.","cause":"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.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'some_file.stl'"}]}