{"id":7214,"library":"fast-simplification","title":"Fast Quadratic Mesh Simplification","description":"fast-simplification is a Python wrapper around the high-performance Fast-Quadric-Mesh-Simplification C++ library. It provides efficient algorithms for reducing the polygon count of 3D meshes while striving to preserve their overall shape. The library is currently at version 0.1.13, actively maintained by the PyVista project, with a history of regular minor releases addressing compatibility and adding features.","status":"active","version":"0.1.13","language":"en","source_language":"en","source_url":"https://github.com/pyvista/fast-simplification","tags":["mesh","3d","simplification","geometry","quadric","pyvista"],"install":[{"cmd":"pip install fast-simplification","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for array input/output and internal data structures.","package":"numpy","optional":false},{"reason":"Recommended for advanced usage and direct integration with 3D visualization, though not strictly required for core simplification functionality.","package":"pyvista","optional":true}],"imports":[{"note":"The main simplification function is directly accessible after a top-level import.","symbol":"simplify","correct":"import fast_simplification\npoints, faces = fast_simplification.simplify(points, faces, reduction_factor)"},{"note":"Used to apply a previously recorded decimation process or to generate vertex mapping.","symbol":"replay_simplification","correct":"import fast_simplification\npoints_out, faces_out, indice_mapping = fast_simplification.replay_simplification(points, faces, collapses)"}],"quickstart":{"code":"import numpy as np\nimport fast_simplification\n\n# Example mesh data (a simple tetrahedron)\npoints = np.array([\n    [0.0, 0.0, 0.0],\n    [1.0, 0.0, 0.0],\n    [0.0, 1.0, 0.0],\n    [0.0, 0.0, 1.0]\n], dtype=np.float64)\n\n# Faces: connectivity of points, typically flattened for PyVista/VTK style\n# Each face is defined by its number of vertices (e.g., 3 for a triangle) followed by vertex indices.\nfaces = np.array([\n    3, 0, 1, 2,\n    3, 0, 1, 3,\n    3, 0, 2, 3,\n    3, 1, 2, 3\n], dtype=np.int64)\n\n# Perform simplification, e.g., reduce to 50% of original faces\nreduction_factor = 0.5\npoints_simplified, faces_simplified = fast_simplification.simplify(\n    points,\n    faces,\n    reduction_factor\n)\n\nprint(f\"Original points: {len(points)}, Original faces: {len(faces) // 4}\") # //4 because each face is 3 indices + 1 count\nprint(f\"Simplified points: {len(points_simplified)}, Simplified faces: {len(faces_simplified) // 4}\")","lang":"python","description":"This quickstart demonstrates how to simplify a mesh using NumPy arrays for points and faces. The `simplify` function returns the new points and faces of the decimated mesh."},"warnings":[{"fix":"Ensure `numpy` is updated to a compatible version (e.g., `numpy>=2.0.0` with `fast-simplification>=0.1.8`) or pinned (e.g., `numpy<2.0.0`) if other dependencies require it, and try reinstalling `fast-simplification` to ensure wheel compatibility.","message":"Potential NumPy version conflicts due to compiled extensions. While version 0.1.8 added support for NumPy v2, and 0.1.11 allowed NumPy <2.0, users might still encounter issues if other installed packages have strict NumPy version pins or if an older `fast-simplification` wheel was compiled against a different NumPy major version.","severity":"gotcha","affected_versions":"<0.1.8, potentially 0.1.8-0.1.10"},{"fix":"Ensure your face array correctly represents the mesh topology. For triangular meshes, this means an array where every fourth element is '3' followed by three vertex indices. Refer to PyVista documentation for common mesh array formats if converting from other libraries.","message":"The `simplify` function expects face arrays in a specific 'VTK-like' format where each face definition is prefixed by the number of vertices it contains (e.g., `[3, v1, v2, v3, 3, v4, v5, v6, ...]` for triangles). Incorrectly formatted face arrays will lead to errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For replay functionality, ensure you set `return_collapses=True` in `simplify` to get the necessary `collapses` data, then pass this directly to `replay_simplification`. Check the latest documentation for usage.","message":"The behavior of `fast_simplification.simplify` regarding `return_collapses` and subsequent `replay_simplification` changed with v0.1.3 and was further documented. While not strictly a breaking change, older assumptions about how to capture and replay decimation might need review.","severity":"deprecated","affected_versions":"<0.1.3"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure input arrays are writable. Create a writable copy if necessary: `points = np.asarray(points, dtype=np.float64, order='C').copy()`","cause":"Attempting to pass a read-only NumPy array (e.g., derived from certain views or immutable data) to the underlying C++ extension, which expects a writable buffer.","error":"ValueError: buffer source array is read-only"},{"fix":"Run `pip install fast-simplification` in your active Python environment. Verify the package is listed by `pip list`.","cause":"The package is not installed, or the environment is not activated, or there's a typo in the import statement.","error":"ModuleNotFoundError: No module named 'fast_simplification'"},{"fix":"Uninstall both `fast-simplification` and `numpy`, then reinstall them: `pip uninstall fast-simplification numpy && pip install numpy fast-simplification`. This ensures that `fast-simplification` is compiled or installed against the current NumPy version if wheels are available.","cause":"This usually indicates a major incompatibility between the version of NumPy and the `fast-simplification` wheel installed. It often happens when NumPy is upgraded or downgraded without reinstalling packages that have C extensions dependent on NumPy.","error":"ImportError: numpy.core.multiarray failed to import\n... SystemError: PY_SSIZE_T_CLEAN defined for 'fast_simplification.core' but not for 'numpy.core.multiarray'"}]}