PyMeshFix

0.18.0 · active · verified Fri Apr 17

PyMeshFix is a Python library that provides bindings to the MeshFix C++ library, enabling robust repair of triangular meshes. It can fix common mesh issues such as holes, self-intersections, and non-manifold edges. The current version is 0.18.0, and it generally sees several releases per year, often aligning with updates to the broader PyVista ecosystem.

Common errors

```
ModuleNotFoundError: No module named 'pymeshfix'
```
cause The pymeshfix library has not been installed in your current Python environment.

fix Run `pip install pymeshfix` in your terminal to install the library.
```
TypeError: an integer is required (got type numpy.float64) / ArgumentError: Python argument types to meshfix.MeshFix.set_meshfix_faces did not match C++ signature:
```
cause The array provided for mesh faces (indices) has an incorrect data type, typically a float type instead of an integer type.

fix Ensure your face array is explicitly cast to `numpy.int32` or `numpy.int64`. Example: `faces = np.array([[0, 1, 2]], dtype=np.int32)`.
```
ERROR: Could not find a version that satisfies the requirement pymeshfix (from versions: none) / ERROR: No matching distribution found for pymeshfix
```
cause Your Python interpreter version is not compatible with any available pymeshfix wheels on PyPI, or you are on an unsupported platform.

fix Verify your Python version. PyMeshFix currently supports `Python >=3.10, <3.15`. Install a compatible Python version or use a virtual environment with a supported Python version.

Warnings

breaking Version 0.18.0 replaced the internal Cython bindings with Nanobind. While the public Python API is intended to remain stable, this change in the underlying C++ binding technology might affect environments with custom build pipelines or those implicitly relying on Cython internals. Users might experience different build requirements or subtle runtime behavior changes.
Fix: Ensure your build environment is compatible with Nanobind requirements if compiling from source. If using pre-built wheels, simply update `pymeshfix` and its dependencies.
gotcha Mesh face arrays (indices) must be of an integer dtype, specifically `numpy.int32` or `numpy.int64`. Providing float dtypes will lead to `TypeError` or `ArgumentError` from the underlying C++ extension.
Fix: When creating or loading face arrays, explicitly cast them to an integer type: `faces = np.array(..., dtype=np.int32)`.
gotcha PyMeshFix has strict Python version requirements, currently supporting `Python >=3.10` and `<3.15`. Using an incompatible Python version will prevent installation or lead to 'No matching distribution' errors.
Fix: Ensure you are using a Python interpreter version within the supported range (e.g., 3.10, 3.11, 3.12, 3.13, 3.14). Consider using a virtual environment manager like `conda` or `venv` to manage Python versions.
gotcha PyMeshFix is licensed under the GNU General Public License (GPL). This is an important consideration for commercial or proprietary projects, as it imposes requirements on derivative works.
Fix: Review the GPL license terms carefully to understand its implications for your project before incorporating PyMeshFix.

Install

pip install pymeshfix Install stable version

Imports

MeshFix
```
from pymeshfix import MeshFix
```

Quickstart

This quickstart demonstrates how to import `MeshFix`, initialize it with NumPy arrays for vertices and faces, and perform a basic repair operation. Note that `pymeshfix` is typically used to fix complex meshes loaded from files, and this example uses a simple mesh to illustrate the API. The `repair` method can take various parameters to control the fixing process.

import numpy as np
from pymeshfix import MeshFix

# Create a simple mesh with a known issue (e.g., open boundary)
# A triangle pointing up, but with a missing top vertex to create a hole
v = np.array([
    [0.0, 0.0, 0.0], # Base left
    [1.0, 0.0, 0.0], # Base right
    [0.5, 1.0, 0.0]  # Top (would create a closed triangle)
], dtype=np.float64)
f = np.array([
    [0, 1, 2] # A single triangle
], dtype=np.int32)

# To demonstrate repair, let's create a small hole by removing a vertex
# For a true 'hole fix', typically you'd have an open boundary that isn't manifold
# In this minimal example, we'll just demonstrate the API with a valid mesh
# Real-world usage involves meshes with actual defects.

# Initialize MeshFix with vertices and faces
mfx = MeshFix(v, f)

# Repair the mesh (e.g., fill holes, remove self-intersections)
# Common options include verbose=False, joincomp=True, remove_self_intersections=True
mfx.repair(verbose=False, joincomp=True, remove_self_intersections=True)

# Get the repaired mesh
v_repaired = mfx.v
f_repaired = mfx.f

print(f"Original vertices shape: {v.shape}")
print(f"Original faces shape: {f.shape}")
print(f"Repaired vertices shape: {v_repaired.shape}")
print(f"Repaired faces shape: {f_repaired.shape}")
# Often, repair might add or remove vertices/faces depending on the issues found

# Example of creating a mesh with a hole more explicitly (requires more complex setup)
# v_hole = np.array([[0,0,0], [1,0,0], [0,1,0], [1,1,0], [0.5,0.5,1]])
# f_hole = np.array([[0,1,2], [1,3,2], [0,2,4], [1,3,4]]) # missing [0,1,4] & [2,3,4] faces to make it a pyramid with a hole
# mfx_hole = MeshFix(v_hole, f_hole)
# mfx_hole.repair()
# print("Hole repaired:", mfx_hole.v.shape, mfx_hole.f.shape)

view raw JSON →