VEMesh

A quality-driven mesh improvement library for planar polygonal meshes

Full documentation: rram.bitbucket.io/vemesh-docs

Pages: About · Rationale · Get Started · Tutorials · User Guide · VEMesh in practice

VEMesh improves planar polygonal meshes through local, atomic, quality-driven updates. It provides two mesh-modification primitives — element agglomeration and vertex relaxation — that are accepted only when they provably improve a user-supplied quality metric. Poorer-quality entities are prioritised, so computational effort is focused where it matters most.

The library is named for its primary application: improving the robustness and performance of the Virtual Element Method (VEM), which is naturally suited to polygonal discretisations. It is also useful as a general-purpose polygonal mesh-improvement tool. See the rationale for the motivation behind the library.

Highlights

• Operates on pmp::SurfaceMesh from the pmp-library.
• User-defined polygon quality metrics are easy to plug in.
• Two atomic operations with overloaded interfaces for full control over scope and sequencing.
• Preserves mesh validity, boundary, subdomains, and embedded interfaces.
• Callbacks for monitoring and visualising updates.
• Reads/writes OFF and VTK.

VEMesh is not a mesh generator or repair tool, is only lightly parallelised (OpenMP for read-only quality evaluation and relaxation candidate scoring), and is restricted to planar meshes. The full feature list and non-features are on the About page.

Dependencies

Required:

• C++20 compiler (GCC ≥ 11.4 or AppleClang ≥ 14)
• CMake ≥ 3.17
• Boost ≥ 1.87
• Eigen
• PMP 3.0

Optional:

• Doxygen (with Graphviz) — required only to build the documentation

The command-line app and performance tools use CLI11, which is provided as a single header in external/ — no separate installation is required.

Platform-specific install commands are listed on the Get Started page.

Installation

git clone https://github.com/rram84/vemesh.git
cd vemesh
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_TESTS=ON
cmake --build build -j
ctest --test-dir build -j
sudo cmake --install build

To link from your own CMake project:

find_package(vemesh REQUIRED)
target_link_libraries(your_target PUBLIC vemesh::vemesh)

Getting started

• Tutorials walk through each operation with runnable examples in tutorial/.
• The command-line app lets you try VEMesh on your own mesh without writing code.
• The User Guide covers quality metrics, conventions, and algorithmic details.

Documentation

Full documentation is generated with Doxygen (cmake -S . -B build -DBUILD_DOCS=ON && cmake --build build --target docs) and hosted at rram.bitbucket.io/vemesh-docs. Main entry points:

• About — overview and feature list
• Rationale — design philosophy and motivation
• Get Started — dependencies, build, and install
• Tutorials — worked examples for each operation
• User Guide — quality metrics, conventions, and algorithmic details
• VEMesh in practice — benchmark results on real meshes

Contributing

Bug reports, feature requests, and pull requests are welcome via the issue tracker. See CONTRIBUTING.md for guidelines, and please run ctest locally before submitting a PR.

License and citation

VEMesh is released under the MIT License; see LICENSE.txt. If you use VEMesh in your work, please cite (TBA).