{"id":13532794,"url":"https://github.com/mlivesu/cinolib","last_synced_at":"2025-04-01T21:31:16.373Z","repository":{"id":40633388,"uuid":"100456759","full_name":"mlivesu/cinolib","owner":"mlivesu","description":"A generic programming header only C++ library for processing polygonal and polyhedral meshes","archived":false,"fork":false,"pushed_at":"2025-01-25T06:57:15.000Z","size":40922,"stargazers_count":953,"open_issues_count":4,"forks_count":101,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-01-25T07:27:05.363Z","etag":null,"topics":["computer-graphics","geodesic","geometry-processing","hex-mesh","hexahedral-mesh","hexmesh","mesh-generation","mesh-processing","polygonal-meshes","polyhedral-meshes","quad-mesh","quadmesh","quadrilateral-mesh","surface-mesh","tet-mesh","tetmesh","tetrahedral-mesh","triangle-mesh","trimesh","volume-mesh"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlivesu.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-16T06:41:43.000Z","updated_at":"2025-01-25T06:57:20.000Z","dependencies_parsed_at":"2023-10-26T20:36:12.329Z","dependency_job_id":"d348d83c-549e-40b4-bc1e-70a4bc1a2367","html_url":"https://github.com/mlivesu/cinolib","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlivesu%2Fcinolib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlivesu%2Fcinolib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlivesu%2Fcinolib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlivesu%2Fcinolib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlivesu","download_url":"https://codeload.github.com/mlivesu/cinolib/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246713049,"owners_count":20821835,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["computer-graphics","geodesic","geometry-processing","hex-mesh","hexahedral-mesh","hexmesh","mesh-generation","mesh-processing","polygonal-meshes","polyhedral-meshes","quad-mesh","quadmesh","quadrilateral-mesh","surface-mesh","tet-mesh","tetmesh","tetrahedral-mesh","triangle-mesh","trimesh","volume-mesh"],"created_at":"2024-08-01T07:01:13.779Z","updated_at":"2025-04-01T21:31:11.357Z","avatar_url":"https://github.com/mlivesu.png","language":"C++","readme":"# CinoLib\n![MacOS](https://github.com/mlivesu/cinolib/actions/workflows/macos-build.yml/badge.svg?event=push)\n![Ubuntu](https://github.com/mlivesu/cinolib/actions/workflows/ubuntu-build.yml/badge.svg?event=push)\n![Linux](https://github.com/mlivesu/cinolib/actions/workflows/windows-build.yml/badge.svg?event=push)\n\nCinoLib is a C++ library for processing polygonal and polyhedral meshes. It supports surface meshes made of triangles, quads or general polygons as well as volumetric meshes made of tetrahedra, hexahedra or general polyhedra. \n\nA distinctive feature of the library is that all supported meshes inherit from a unique base class that implements their common traits, permitting to deploy algorithms that operate on _abstract_ meshes that may be any of the above. This allows to implement algorithms just once and run the same code on any possible mesh, thus avoiding code duplication and reducing the debugging effort.\n\n:boom:***CinoLib received the [Symposium on Geometry Processing Software Award](http://awards.geometryprocessing.org) in 2024***:boom:\n\n\u003cp align=\"center\"\u003e\u003cimg src=\"cinolib_rep_image.png\" width=\"500\"\u003e\u003c/p\u003e\n\n## Positioning\nGithub hosts a whole variety of great academic libraries for mesh processing. If you do mainly geometry processing on triangle meshes, then tools like [libigl](https://libigl.github.io), [GeometryCentral](https://geometry-central.net) or [VCG](https://github.com/cnr-isti-vclab/vcglib) may be what you want. If you are interested in rendering, [Yocto/GL](https://github.com/xelatihy/yocto-gl) is extremely fast and implements many relevant algorithms. [OpenMesh](https://www.graphics.rwth-aachen.de/software/openmesh/), [CGoGN2](https://github.com/cgogn/CGoGN_2/) and [PMP](http://www.pmp-library.org) have a slightly broader scope and can handle general polygonal surfaces. For volumes, tiny portions of [libigl](https://libigl.github.io) and [GeometryCentral](https://geometry-central.net) offer rudimentary support for specific solid elements such as tetrahedra or hexahedra, but most of the library is focused on surfaces. Conversely, [OpenVolumeMesh](https://www.graphics.rwth-aachen.de/software/openvolumemesh/) and [CGoGN3](https://github.com/cgogn/CGoGN_3/) are focused on volumes and can operate on general polyhedral elements, but they do not support surface meshes. To the best of my knowledge, only [Geogram](https://github.com/BrunoLevy/geogram) has a unified data structure that can host both surface and volume elements, but it only supports hexahedra, tetrahedra, prisms and pyramids as volume cells. Differently from all these alternatives, CinoLib has a unique data structure that is designed to host any type of surface and volumetric element. If this comes handy to you, I am not aware of any existing alternative. Data structures based on combinatorial maps have the potential to offer similar capabilities, but these are not fully implemented yet ([#171](https://github.com/mlivesu/cinolib/issues/171)). Note that CinoLib trades generality for efficiency, hence all this flexibilty comes at a cost. Many optimizations that are possible when one operates on a restricted set of mesh elements cannot be applied here, especially memory-wise, where generic elements with an unpredictable number of vertices edges and faces demand the use of dynamic allocators. For this reason, in some cases CinoLib may be sligthly less efficient than the aforementioned alternatives.\n\n\n## Getting started\nCinoLib is header only. It does not need to be installed, all you have to do is to clone the repo with\n```\ngit clone https://github.com/mlivesu/cinolib.git\n```\nand include in your C++ application the header files you need. For small projects this could already be done by instructing the compiler on where to find the library sources, e.g. with the `-I` option. For more convoluted projects it is suggested to rely on a building system such as [CMake](https://cmake.org), that can also handle optional external dependencies and compilation flags or symbols.\n\n## Build a sample project (with CMake)\nHere is an example of a toy program that reads a triangle mesh and displays it on a window\n```c++\n#include \u003ccinolib/meshes/drawable_trimesh.h\u003e\n#include \u003ccinolib/gl/glcanvas.h\u003e\n\nint main()\n{\n    using namespace cinolib;\n    DrawableTrimesh\u003c\u003e m(\"bunny.obj\");\n    GLcanvas gui;\n    gui.push(\u0026m);\n    return gui.launch();\n}\n```\nand this is the `CMakeLists.txt` that can be used to compile it\n```cmake\ncmake_minimum_required(VERSION 3.2)\nproject(cinolib_demo)\nadd_executable(${PROJECT_NAME} main.cpp)\nset(CINOLIB_USES_OPENGL_GLFW_IMGUI ON)\nfind_package(cinolib REQUIRED)\ntarget_link_libraries(${PROJECT_NAME} cinolib)\n```\nCompiling should be as easy as opening a terminal in the folder containing the two files above and type\n```\nmkdir build\ncd build\ncmake .. -DCMAKE_BUILD_TYPE=Release -Dcinolib_DIR=\u003cabsolute-path-to-cinolib\u003e\nmake\n```\nNote that for the rendering part CinoLib uses [GLFW](https://www.glfw.org), which will be automatically installed and linked by the script `cinolib-config.cmake`, contained in the main directory of the library. The same script can automatically download and install any other external dependency, meaning that if you want to access a functionality that depends on some external library `XXX`, all you have to do is setting to `ON` a cmake variable that looks like `CINOLIB_USES_XXX`. \nValid options are:\n* `CINOLIB_USES_OPENGL_GLFW_IMGUI`, used for rendering with OpenGL\n* `CINOLIB_USES_TRIANGLE`, used for polygon triangulation\n* `CINOLIB_USES_TETGEN`, used for tetrahedralization\n* `CINOLIB_USES_SHEWCHUK_PREDICATES`, used for exact geometric tests on input points\n* `CINOLIB_USES_INDIRECT_PREDICATES`, used for exact geometric tests on implicit points\n* `CINOLIB_USES_GRAPH_CUT`, used for graph clustering\n* `CINOLIB_USES_BOOST`, used for 2D polygon operations (e.g. thickening, clipping, 2D booleans...)\n* `CINOLIB_USES_VTK`, used just to support VTK file formats\n* `CINOLIB_USES_SPECTRA`, used for matrix eigendecomposition\n* `CINOLIB_USES_CGAL_GMP_MPFR`, used for rational numbers with a lazy kernel\n\n## GUI\nCinoLib is designed for researchers in computer graphics and geometry processing that need to quickly realize software prototypes that demonstate a novel algorithm or technique. In this context a simple OpenGL window and a side bar containing a few buttons and sliders are often more than enough. The library uses [ImGui](https://github.com/ocornut/imgui) for the GUI and [GLFW](https://www.glfw.org) for OpenGL rendering. Typical visual controls for the rendering of a mesh (e.g. shading, wireframe, texturing, planar slicing, ecc) are all encoded in two classes `cinolib::SurfaceMeshControls` and `cinolib::VolumeMeshControls`, that operate on surface and volume meshes respectively. To add a side bar that displays all such controls one can modify the sample progam above as follows:\n```c++\n#include \u003ccinolib/meshes/drawable_trimesh.h\u003e\n#include \u003ccinolib/gl/glcanvas.h\u003e\n#include \u003ccinolib/gl/surface_mesh_controls.h\u003e\n\nint main()\n{\n    using namespace cinolib;\n    DrawableTrimesh\u003c\u003e m(\"bunny.obj\");\n    GLcanvas gui;\n    SurfaceMeshControls\u003cDrawableTrimesh\u003c\u003e\u003e mesh_controls(\u0026m, \u0026gui);\n    gui.push(\u0026m);\n    gui.push(\u0026mesh_controls);\n    return gui.launch();\n}\n```\nThe canvas can host multiple mesh controls, ideally one of each mesh in the scene. Additional GUI elements that may be necessary to control the application (e.g. the parameters of your algorithm) can be added by implementing a dedicated callback:\n```c++\n#include \u003ccinolib/meshes/drawable_trimesh.h\u003e\n#include \u003ccinolib/gl/glcanvas.h\u003e\n#include \u003ccinolib/gl/surface_mesh_controls.h\u003e\n\nint main()\n{\n    using namespace cinolib;\n    DrawableTrimesh\u003c\u003e m(\"bunny.obj\");\n    GLcanvas gui;\n    SurfaceMeshControls\u003cDrawableTrimesh\u003c\u003e\u003e mesh_controls(\u0026m, \u0026gui);\n    gui.push(\u0026m);\n    gui.push(\u0026mesh_controls);\n    float val = 1.0, min = 0.0, max = 10.0;\n    gui.callback_app_controls = [\u0026]()\n    {\n        if(ImGui::Button(\"MyButton\"))\n        {\n            // button clicked: do something\n        }\n        if(ImGui::SliderFloat(\"MySlider\", \u0026val, min, max))\n        {\n            // slider moved: do something\n        }       \n    };\n    return gui.launch();\n}\n```\nThe full list of callbacks exposed by `GLcanvas` to interact with user events (e.g. for scene navigation, mouse picking, ecc) are:\n* `callback_key_pressed(int key, int modifiers)`\n* `callback_mouse_left_click(int modifiers)`\n* `callback_mouse_left_click2(int modifiers)` =\u003e double click\n* `callback_mouse_right_click(int modifiers)` \n* `callback_mouse_right_click2(int modifiers)` =\u003e double click\n* `callback_mouse_moved(double x_pos, double y_pos)`\n* `callback_mouse_scroll(double x_offset, double y_offset)`\n* `callback_app_controls(void)`\n\n\n## Other examples\nA tutorial with detailed info on how to use the library is under developement. In the meanwhile, you can explore the [**examples**](https://github.com/mlivesu/cinolib/tree/master/examples#examples)  folder, which contains a constantly growing number of sample projects that showcase the core features of the library, and will be the backbone of the forthcoming tutorial.\n\n## Contributors\nMarco Livesu is the creator and lead developer of the library. CinoLib has also received contributions from: Daniela Cabiddu (CNR IMATI), Claudio Mancinelli and Enrico Puppo (University of Genoa), Chrystiano Araújo (UBC), Thomas Alderighi (CNR ISTI), Fabrizio Corda (University of Cagliari), Gianmarco Cherchi (University of Cagliari) and Tommaso Sorgente (CNR IMATI).\n\n## Citing us\nIf you use CinoLib in your academic projects, please consider citing the library using the following \nBibTeX entry:\n\n```bibtex\n@article{cinolib,\n  title   = {cinolib: a generic programming header only C++ library for processing polygonal and polyhedral meshes},\n  author  = {Livesu, Marco},\n  journal = {Transactions on Computational Science XXXIV},\n  series  = {Lecture Notes in Computer Science},\n  editor  = {Springer},\n  note    = {https://github.com/mlivesu/cinolib/},\n  year    = {2019},\n  doi     = {10.1007/978-3-662-59958-7_4}}\n```\n\n## Acknowledgment\nThe software collected in CinoLib spans across a large period of time, starting from the beginning of my PhD to today. Since 2015, this work has been partly supported by various research projects, such as\n* [ProMED](http://arm.mi.imati.cnr.it/imati/detail_pages.php?language=ENG\u0026view=GEN\u0026voice_code=PRG\u0026fcode=WHA\u0026ref_idk=PJ-176)\n* [CHANGE](https://cordis.europa.eu/project/rcn/204834/en)\n* [CAxMan](https://cordis.europa.eu/project/id/680448)\n","funding_links":[],"categories":["General Libraries","[Libraries](#awesome-collision-detection)","Geometry, Graphics Processing, and Game Development","C++","Maths","Libraries"],"sub_categories":["Mesh Processing","C++"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlivesu%2Fcinolib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlivesu%2Fcinolib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlivesu%2Fcinolib/lists"}