CinoLib: one mesh abstraction for surfaces and volumes

Surfaces and volumes behind a single base class

CinoLib is a C++ library for processing polygonal and polyhedral meshes. It supports surface meshes made of triangles, quads or general polygons, and volumetric meshes made of tetrahedra, hexahedra or general polyhedra.

The distinctive feature, as the README puts it, is that all supported meshes inherit from a unique base class that implements their common traits. That permits deploying algorithms that operate on abstract meshes that may be any of the above, so an algorithm is implemented once and the same code runs on any possible mesh. The stated benefit is avoiding code duplication and reducing the debugging effort.

That is a real design decision rather than a convenience. Most mesh libraries pick a domain. A surface library has a vertex, an edge and a face, and a volume library has a cell and a volume mesh type, and code that has to work on both either lives in two worlds or lives in a weaker common base. CinoLib's claim is that a single base class covers the common traits of both, and the topics list confirms the breadth with triangle, quad, tet, hex, general polygon and general polyhedral meshes all named.

The cost is stated in the same breath. The library trades generality for efficiency, and the flexibility comes at a cost, with many optimizations that are possible when operating on a restricted set of mesh types being unavailable. The README adds that in some cases CinoLib may be slightly less efficient than the alternatives it names.

An award, and a crowded field to be different in

CinoLib received the Symposium on Geometry Processing Software Award in 2024, which is the kind of recognition that says a project has been noticed by the community that uses it rather than only by its author.

The positioning section explains where it fits, and it is a careful piece of writing. For triangle mesh geometry processing the README points at libigl, GeometryCentral and VCG. For rendering, Yocto/GL, which it calls extremely fast and which implements many relevant algorithms. For broader surface scope, OpenMesh, CGoGN2 and PMP. For volumes, OpenVolumeMesh and CGoGN3, which are focused on volumes and can operate on general polyhedral elements but do not support surface meshes.

The interesting comparison is with Geogram, which the README says, to the author's knowledge, is the only other library with a unified data structure that can host both surface and volume elements, and that it supports only hexahedra, tetrahedra, prisms and pyramids as volume cells. Differently from all the alternatives, CinoLib has a data structure designed to host any type of surface and volumetric element, and the README says that if this comes in handy, the author is not aware of any existing alternative.

There is an honest admission at the end of the section, that data structures based on combinatorial maps have the potential to offer similar capabilities, but those are not fully implemented yet, with an issue number attached.

Header only, and a viewer in a dozen lines

CinoLib is header only, and the README is explicit that it does not need to be installed. You clone the repository:

git clone https://github.com/mlivesu/cinolib.git

and include the header files you need in your C++ application. For small projects the README says this could already be done by instructing the compiler where to find the library sources, for example with the -I option. For more convoluted projects it suggests relying on a building system such as CMake, which can also handle optional external dependencies and compilation flags or symbols.

The sample program is the shortest possible demonstration of the point. It reads a triangle mesh and displays it in a window:

#include <cinolib/meshes/drawable_trimesh.h>
#include <cinolib/gl/glcanvas.h>

int main()
{
    using namespace cinolib;
    DrawableTrimesh<> m("bunny.obj");
    GLcanvas gui;
    gui.push(&m);
    return gui.launch();
}

The DrawableTrimesh template and the GLcanvas are the two pieces a reader has to understand, and the example directory then walks through the rest, with numbered projects from 01_trimesh_viewer up to 25_surface_painter, covering quad, polygon, tet, hex and polyhedral viewers, texture loading, picking, polyharmonic functions on both surfaces and volumes, sphere mapping, mesh generation for polygons and polyhedra, heat geodesics, polygon measures, sphere sampling, iso contours, iso surfaces, harmonic maps, coarse quad and hex layouts, a remesher, sharp creases, a sliced CLI loader and a surface painter.

The numbering is a good sign, because it means the library is used through worked examples rather than through a manual.

CMake, and one switch per optional dependency

The build story is the practical part of adopting a header-only library with optional pieces, and CinoLib handles it with a package configuration script and a set of variables.

The demo project needs a CMakeLists.txt like this:

cmake_minimum_required(VERSION 3.2)
project(cinolib_demo)
add_executable(${PROJECT_NAME} main.cpp)
set(CINOLIB_USES_OPENGL_GLFW_IMGUI ON)
find_package(cinolib REQUIRED)
target_link_libraries(${PROJECT_NAME} cinolib)

and the build is then a familiar three steps:

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -Dcinolib_DIR=<absolute-path-to-cinolib>
make

The detail worth understanding is how the dependencies arrive. For the rendering part CinoLib uses GLFW, which will be automatically installed and linked by the script cinolib-config.cmake in the main directory of the library. The same script can automatically download and install any other external dependency, so accessing a functionality that depends on some external library XXX means setting a CMake variable called CINOLIB_USES_XXX to ON.

The list of switches is the actual feature map of the library, and it is worth reading as one. CINOLIB_USES_OPENGL_GLFW_IMGUI for rendering with OpenGL, CINOLIB_USES_TRIANGLE for polygon triangulation, CINOLIB_USES_TETGEN for tetrahedralization, CINOLIB_USES_SHEWCHUK_PREDICATES for exact geometric tests on input points, CINOLIB_USES_INDIRECT_PREDICATES for exact geometric tests on implicit points, CINOLIB_USES_GRAPH_CUT for graph clustering, CINOLIB_USES_BOOST for 2D polygon operations such as thickening, clipping and 2D booleans, CINOLIB_USES_VTK just to support VTK file formats, CINOLIB_USES_SPECTRA for matrix eigendecomposition, and CINOLIB_USES_CGAL_GMP_MPFR for rational numbers with a lazy kernel.

A GUI layer aimed at prototypes, not at products

The GUI section explains the intended user precisely. CinoLib is designed for researchers in computer graphics and geometry processing who need to quickly realise software prototypes that demonstrate a novel algorithm or technique. In that context, a simple OpenGL window and a sidebar with a few buttons and sliders are often more than enough.

The implementation is ImGui for the GUI and GLFW for OpenGL rendering. ImGui is the right choice for that audience, because it is immediate-mode, so a control is drawn in the same loop iteration that reads its value and there is no widget tree to maintain, which is exactly what a prototype wants.

The visual controls for rendering a mesh, shading, wireframe, texturing, planar slicing and the rest, are encoded in two classes, cinolib::SurfaceMeshControls and cinolib::VolumeMeshControls, operating on surface and volume meshes respectively. The split mirrors the two mesh families the library supports, and the README shows how to add a sidebar displaying them to the sample program.

This is worth stating plainly as a limitation. The GUI is a research tool. It is immediate-mode, and it assumes a developer at a desk with an OpenGL context. There is no attempt to make the interface look like anything other than a debugging aid.

Where CinoLib is the wrong choice

The first wrong-tool case is triangle meshes only. The README itself says that if you do mainly geometry processing on triangle meshes, libigl, GeometryCentral or VCG may be what you want. Those libraries have a smaller abstraction to pay for, they are more focused, and the generality CinoLib buys you buys you nothing if every mesh in your project is a triangle mesh.

The second is a production performance requirement. The library trades generality for efficiency, and the trade is explicit. Code written against an abstract mesh has to be conservative about what it can assume about the topology, and the specialised libraries can do things CinoLib's abstraction will not allow.

The third is a build environment that cannot fetch dependencies. The convenience of CINOLIB_USES_XXX is that the script downloads and links what you need, and that convenience requires network access at configure time and a working toolchain for each dependency. An air-gapped build, or a project with a strict dependency policy, has to vendor those libraries itself and turn the switches into something it controls.

There is also the question of maturity signals, and here the picture is mixed. The project won a geometry processing award in 2024 and the repository is actively worked on, with the last push in September 2026 and CI workflows for macOS, Ubuntu and Windows. But the release list shows a single tag, v1.0 from 2021, and the README points at open issues in the repository for work that is not finished, including the combinatorial map data structure that would offer similar capabilities.

MIT, a single v1.0 tag, and a busy examples directory

The project is MIT licensed, with the LICENSE file at the repository root. The repository is not archived, and the last push was on 2026-09-11.

The release history is the one weak spot. The only listed release is v1.0, dated 2021-05-31, so a project that has been developed for years and has won a community award has exactly one tagged version. For a header-only library that is less serious than it would be for a binary, since the normal consumption path is a clone or a copy of the headers, but it does mean there is no obvious pin for a reproducible build, and the CI badges are the signal of quality rather than a version history.

The repository layout supports that consumption model. There is an include/ directory holding the headers, an external/ directory for the bundled third-party material, examples/ with the numbered projects, scripts/ for the build helpers, and cinolib-config.cmake at the root, which is the piece that makes the dependency switches work. There is a TODO.md, which is worth reading before you plan anything, and a .github/ directory with the three platform build workflows, one each for macOS, Ubuntu and Windows.

The two images at the root, cinolib_rep_image.png and the PDF beside it, are the project report material, which is what the geometry processing symposium award was given for.

Editorial conclusion

Adopt CinoLib if your geometry processing code has to run over mixed element types, because the single base class is the whole point of the project and it removes the per-element-type duplication that most mesh libraries leave you with. Do not adopt it if your work is triangle meshes only, where libigl or GeometryCentral will get you further faster, and do not adopt it expecting fast code, since the README says the library trades generality for efficiency. Before you commit, read the positioning section against the other libraries it names, confirm the element types you actually have are supported, and budget for a build system that pulls in several external dependencies, since the CMake switches exist because the default build is deliberately small.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mlivesu/cinolib on GitHub
4. README
5. Releases