Versatile Volume Fitting with Automatic Feature Preservation

This is the reference implementation of the optimization approach presented in

Versatile Volume Fitting with Automatic Feature Preservation
F. Protais, G. Cherchi, M. Livesu

⚠️ This code is intended to be included in CGAL in the near future. As such, it may undergo noticeable changes in its structure. This repository will always remain as a link to the CGAL version, and hopefully provide python bindings.

The core of the code (Mesh_smoothing_3 directory) is header only and templated, hence fully agnostic to mesh representation. The target is to deploy a toolbox that can be used with any application with limited linking, relying solely on Eigen3 as an external tool. We accessed the functionalities of the solver through the following popular geometry processing libraries, which entirely take care of input/output, mesh storage and handling:

• Geogram
• Cinolib
• LibIGL
• CGAL

We have plans to extend this list to OpenVolumeMesh, GMDS and ultimaille. You want your data structure on this list? Let us know.

For building instructions, see Installation section. For most basic smoothing, see Basic usage section. We provide various examples from the paper. See examples Readme.

Installation

Compiling

Compilation on Unix-like devices can be done as follows:

mkdir build;
cd build;
cmake ..;
make -j;

CMake will automatically fetch the corresponding libs and link it to the executables. Executables for all examples will be created and installed in a dedicated /build/bin directory.

The code is tested to work on recent Windows, Linux and MacOS. But we leave non-linux installation to users. Note that OpenMP will provide significant performance gain, but it is non trivial to include on MacOS.

Requirements

The only general requirement is Eigen3, which will be accessed through cmake:

find_package(Eigen3 3.3.0 QUIET REQUIRED)

Similarly, the CGAL library must be installed independently and will be accessed by:

find_package(CGAL REQUIRED)

To avoid this requirement, it is possible to build the project with CGAL disabled:

cmake .. -DBUILD_CGAL=FALSE

Basic usage

This executable is the most standard use of the code: improve the quality of mesh and fit to its geometric target. The code can be called as:

./bin/geogram_smooth ../data/sphere.mesh ../data/max-planck.obj

sphere.mesh represent the volumetric tetrahedral mesh and max-planck.obj the geometric target represented as a surface triangle mesh. The code works with mesh containing Tetrahedra, Pyramids, Wedges and Hexahedra.

The same executable can also be called with a unique input parameter, as:

./bin/geogram_smooth ../data/fandisk_kenshi_hexmesh.mesh

In this case it will operate as a smoothing (or untangling algorithm), improving the mesh quality while trying to preserve the outer boundary.

In both cases, the result will be saved as output.mesh.

Exact predicates

The code can include exact predicates to strictly enforce the orientation of elements. This is disabled by default to support starting from invalid meshes. It can simply be enabled using the following instruction:

smoother.set_predicates_mode(Mesh_smoothing_3::Parameters::STRONG_ENFORCEMENT); 

Element orientations

Element orientation is key to optimize mesh quality (and guarantee validity). Not all available models and tools stick to the same convention, sometimes generating unexplainable failures in the software. We stick to the VTK convention for all mixed elements (see Figure 2 here). Notice that due to our untangling capabilities, we cannot autonomously guess or fix input element orientation. Cinolib and Geogram examples contain a void set_orientation(bool inv_tet, bool inv_hex, bool inv_pyr, bool inv_wed) function to help on that aspect but, as a rule of thumb, input meshes that stick to a different convention must be fixed prior to calling our solver.

Basic visualization

Meshes can be visualized using various tools depending on their format. GraphiteThree is capable of displaying all meshes provided in data and generated by our executables, and any file handled by geogram_smooth.

License

This code is under GPLv3 and shall not be distributed in or with closed source software. For commercial uses, alternative licensing will be provided after inclusion into the CGAL library.

Citing this repo

This project is currently described in the eponymous working paper. The status of the paper is subject to future change. If you use our code in your academic projects, please cite the following BibTeX entry:

@unpublished{protais:hal-05574616,
  TITLE = {{Versatile Volume Fitting with Automatic Feature Preservation}},
  AUTHOR = {Protais, Fran{\c c}ois and Cherchi, Gianmarco and Livesu, Marco},
  URL = {https://inria.hal.science/hal-05574616},
  NOTE = {working paper},
  YEAR = {2026},
  MONTH = Mar,
  KEYWORDS = {tetrahedral mesh ; hexahedral mesh ; fitting ; sharp features ; projection ; smoothing ; untangling},
  PDF = {https://inria.hal.science/hal-05574616v1/file/Smoothing__Unica_INRIA_techreport.pdf},
  HAL_ID = {hal-05574616},
  HAL_VERSION = {v1},
}