Fast Quadratic Mesh Simplification

Common errors

• ValueError: buffer source array is read-only

  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.
  fix Ensure input arrays are writable. Create a writable copy if necessary: `points = np.asarray(points, dtype=np.float64, order='C').copy()`

• ModuleNotFoundError: No module named 'fast_simplification'

  cause The package is not installed, or the environment is not activated, or there's a typo in the import statement.
  fix Run `pip install fast-simplification` in your active Python environment. Verify the package is listed by `pip list`.

• ImportError: numpy.core.multiarray failed to import
  ... SystemError: PY_SSIZE_T_CLEAN defined for 'fast_simplification.core' but not for 'numpy.core.multiarray'

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

Warnings

• gotcha 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.
  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.
• gotcha 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.
  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.
• deprecated 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.
  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.

Install

• pip install fast-simplification Install with pip

Imports

• simplify

  import fast_simplification
  points, faces = fast_simplification.simplify(points, faces, reduction_factor)

  The main simplification function is directly accessible after a top-level import.
• replay_simplification

  import fast_simplification
  points_out, faces_out, indice_mapping = fast_simplification.replay_simplification(points, faces, collapses)

  Used to apply a previously recorded decimation process or to generate vertex mapping.

Quickstart

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.

import numpy as np
import fast_simplification

# Example mesh data (a simple tetrahedron)
points = np.array([
    [0.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [0.0, 1.0, 0.0],
    [0.0, 0.0, 1.0]
], dtype=np.float64)

# Faces: connectivity of points, typically flattened for PyVista/VTK style
# Each face is defined by its number of vertices (e.g., 3 for a triangle) followed by vertex indices.
faces = np.array([
    3, 0, 1, 2,
    3, 0, 1, 3,
    3, 0, 2, 3,
    3, 1, 2, 3
], dtype=np.int64)

# Perform simplification, e.g., reduce to 50% of original faces
reduction_factor = 0.5
points_simplified, faces_simplified = fast_simplification.simplify(
    points,
    faces,
    reduction_factor
)

print(f"Original points: {len(points)}, Original faces: {len(faces) // 4}") # //4 because each face is 3 indices + 1 count
print(f"Simplified points: {len(points_simplified)}, Simplified faces: {len(faces_simplified) // 4}")