pyfqmr : Python Fast Quadric Mesh Reduction

Cython wrapper around sp4acerat's quadrics mesh reduction algorithm.

Requirements:

• Numpy
• Cython (only for compilation, but not needed if installed from PyPI)

Installation :

pyfqmr can be installed via pip :

pip install pyfqmr

Compilation :

Run:

pip install .

Usage:

>>> # We assume you have a numpy based mesh processing software
>>> # Where you can get the vertices and faces of the mesh as numpy arrays.
>>> # For example Trimesh or meshio
>>> import pyfqmr
>>> import trimesh as tr
>>> bunny = tr.load_mesh('example/Stanford_Bunny_sample.stl')
>>> # Simplify object
>>> mesh_simplifier = pyfqmr.Simplify()
>>> mesh_simplifier.setMesh(bunny.vertices, bunny.faces)
>>> mesh_simplifier.simplify_mesh(target_count = 1000, aggressiveness=7, preserve_border=True, verbose=True)
>>> vertices, faces, normals = mesh_simplifier.getMesh()
>>>
>>> # To make verbose visible, use logging module :
>>> import logging
>>>
>>> # Configure the logger to show debug messages
>>> logging.basicConfig(level=logging.DEBUG)
>>> logger = logging.getLogger("pyfqmr")
>>>
>>> # Optionally, log to a file:
>>> # logging.basicConfig(filename='mesh_simplification.log', level=logging.DEBUG)
>>>
>>> # Now, when `simplify_mesh(verbose=True)` is called,
>>> # messages will appear in the console or the log file

Controlling the reduction algorithm

Parameters of the `simplify_mesh` method that can be tuned.

• target_count

  Target number of triangles.

• update_rate

  Number of iterations between each update.

• max_iterations

  Maximal number of iterations

• aggressiveness

  Parameter controlling the growth rate of the threshold at each iteration when lossless is False.

• preserve_border

  Flag for preserving the vertices situated on open borders. Applies the method described in this issue.

• alpha

  Parameter for controlling the threshold growth. Exact implication described below.

• K

  Parameter for controlling the threshold growth. Exact implication described below.

• lossless

  Flag for using the lossless simplification method. Sets the update rate to 1 .

• threshold_lossless

  Maximal error after which a vertex is not deleted, only when the lossless flag is set to True.

• verbose

  Falg controlling verbosity

Controlling the lossless reduction algorithm

Parameters of the `simplify_mesh_lossless` method that can be tuned.

• verbose

  Falg controlling verbosity

• epsilon

  Maximal error after which a vertex is not deleted.

• max_iterations

  Maximum number of iterations.

• preserve_border

  Flag for preserving the vertices situated on open borders. Applies the method described in this issue.

Note

• The `simplify_mesh_lossless` method is different from the `simplify_mesh` method with the lossless flag enabled, and should be prefered when quality is the aim and not a precise number of target triangles.
• Tests have shown that the threshold_lossless argument has little to no influence on the reduction of the meshes.

Implications of the parameters for the threshold growth rate :

(`simplify_mesh` method when not in lossless mode)

$$threshold = alpha * (iteration + K)^{agressiveness}$$

More information is to be found on Sp4cerat's repository :

Fast-Quadric-Mesh-Simplification

Huge thanks to Sp4cerat for making his code available!