VCGlib: the header-only mesh library underneath MeshLab and Metro

A header only mesh library with no external dependencies

VCGlib is the Visualization and Computer Graphics Library from the Visual Computing Lab at the Italian National Research Council institute ISTI. It is a C++ library, templated, portable, and described as having no external dependencies, and its purpose is manipulating, processing, cleaning and simplifying triangle meshes.

The dependency-free claim is the design decision that shapes everything else. A mesh library that pulls in nothing is one you can drop into an application without negotiating a transitive dependency tree, and that property has kept it stable for a long time. The cost of that choice is that a great deal has to live inside the library itself, and the project describes itself as fairly large, composed of more than 100k lines of code.

It is also header based. That matters for how you consume it. You include headers and instantiate templates, which means compile times are part of your build experience, and it means the library is source rather than a binary you link against.

The repository layout backs the description up. The vcg/ directory holds the library itself, apps/ holds the applications, wrap/ holds wrapper code, eigenlib/ holds a bundled linear algebra component, and there is a CMakeLists.txt at the root along with docs/. The library is targeted at triangular meshes specifically, which is a deliberate narrowing: if your data is quads or n-gons, the conversion step is yours to handle.

Quadric error simplification, and the out-of-core path it came from

The capability list starts with high quality quadric error edge collapse based simplification, which is the single most requested operation in mesh processing and the one with the most competing implementations.

The historical detail here matters more than the feature list. The project states that the first high quality out-of-core mesh simplifier came out of this work, and that it was used by the Stanford Digital Michelangelo project to process their huge 3D scanned models. Out-of-core means the simplification runs on data larger than memory, which is the hard case, and the scanned models of that project were large enough to require it. So this is not a feature list written by a marketing department; it is a library whose core algorithm was stress tested against some of the largest meshes anyone had digitized at the time.

The applications built on the library give you the same signal from the other direction. MeshLab is the open source mesh processing software, and Metro is the tool for measuring differences between meshes, with a Hausdorff distance computation among the listed capabilities. Metro measuring differences and VCGlib computing Hausdorff distance are the same domain, which tells you the lab cared about verification and comparison, not only authoring.

If simplification is your problem, note that the competing approach you would otherwise reach for is a standalone simplifier binary you invoke as a subprocess. The difference in approach is that VCGlib puts the algorithm in your process, so you can simplify, measure the result, and re-simplify with different parameters without a round trip through the file system.

Spatial structures, curvature, geodesics and fairing in one header set

Beyond simplification the library carries the algorithms a mesh processing pipeline usually needs, and the grouping in the project description says something about what is considered core.

The spatial layer covers efficient spatial query structures, specifically uniform grids, hashed grids and kdtree, which is the infrastructure that makes every other operation practical on a large mesh. The geometry layer covers computation of curvature, advanced smoothing and fairing algorithms, optimization of texture coordinates, geodesic paths, Hausdorff distance computation, and mesh repairing capabilities. The sampling layer covers isosurface extraction with advancing front meshing algorithms, plus Poisson Disk sampling and other tools for sampling point distributions over meshes. Subdivision surfaces sit in their own category.

Two of these are worth pausing on. Geodesic paths and Hausdorff distance are measurement operations, the kind you use to validate a processing pipeline rather than to author an asset. Texture coordinate optimization is the operation that separates a mesh you can display from a mesh you can wrap, and it is notoriously fiddly, so having it in the same library as the simplification it has to stay consistent with is a real convenience.

The practical note is that the library is templated, so the mesh type is a template parameter. That is how one implementation serves both the internal tools and external applications, and it is also how you can adapt it to a mesh class of your own rather than converting into the library's own type.

No install command in the documentation, so the build has to come from the sources

The project description does not give a package manager command, a binary distribution or a set of build instructions, and the README in the repository is a short overview rather than a getting started guide. So the honest statement is this: the library is obtained from the repository, and the build is driven by the CMakeLists.txt at the root, with the apps/ directory providing the example applications that the build system can produce.

The continuous integration badge in the README points at a workflow named BuildExamples, which tells you what the project itself treats as the smoke test: the example applications compile. That is a reasonable indicator of what a newcomer should try first, since an application that builds proves the headers resolve, the templates instantiate and the dependencies inside eigenlib are in place.

There is a documentation directory in the repository, and the project has a homepage at vcglib.net, and both are where you would look for the build details that the README omits. This is the point in the evaluation where you should be honest with yourself about the cost: a library with more than 100k lines, a bundled eigenlib, a wrap layer and a set of applications is not something you evaluate in an afternoon. The compile times, the template instantiation surface and the size of the API are the real adoption costs, and none of them are visible from the outside.

Also worth noting for anyone who came looking for a modern package: there is no statement about a semantic versioning scheme. The releases are dated, 2025.07 being the most recent, which is a calendar versioning approach that tells you the release vintage but not how stable the API is between snapshots.

The GPL licence, and why the project names a contact for portions

The library is released under the GPL, and the README states that directly, with the more than 100k lines of code composed under that licence. There is a LICENSE.txt file at the repository root.

What that means in practice depends on how you use it, and this is where the README includes an unusual instruction: for any information about licensing portions of the library, the project directs you to a named contact, Paolo Cignoni, at the Visual Computing Lab of ISTI, with a mailing address for the institute. Bug reports go to the issue tracker instead.

The existence of that contact path tells you two things. It tells you that partial use of the library, typically a single algorithm or a single header, is something the authors anticipated and are willing to discuss. It also tells you that the answer is not a general permission you can rely on without asking. The default reading of a GPL library is that linking it into your program imposes GPL obligations on the combined work, and a narrow question about one header set is exactly the kind of thing a licence question should be directed to the copyright holders about rather than guessed at.

A practical note on scope: this is not legal advice, but the safe operating assumption is that if your product is proprietary and closed source, this library is a poor fit unless you have a separate arrangement. MeshLab, the most visible consumer, is itself open source, and the lab's tools around it share that posture.

Dated releases against a moving repository

The release history is sparse. The tags listed are 2025.07 from July 2025, 2023.12 from December 2023 and 2022.02 from February 2022. The last push to the repository was on 2026-10-11, and the repository is not archived.

Read together, those two facts describe a project that keeps working between dated snapshots. The July 2025 tag is a stable point you can point a build at, and there have been roughly fifteen months of further commits since. That is a healthy pattern for a library whose users are mostly internal tools and researchers, but it has a consequence: pinning to a tag means pinning to code that is not what the maintainers are currently using.

There is a second-order effect on the derived tools. MeshLab and Metro are built on the library, so when the library moves, those applications move with it, and their own release cycles are not the same as the library's. If you are integrating with a MeshLab format or a Metro report, you are depending on the behaviour of a moving base.

The maturity signal here is not the release list, it is the application list. A library that is the base of the lab's own tools, including the out-of-core simplifier used for the Stanford Digital Michelangelo scans, has been validated against real production workloads for a very long time. That history is a better argument for stability than a version number.

Editorial conclusion

VCGlib fits a research or tools team that needs mesh simplification, repair, spatial queries or isosurface extraction in C++ and would rather not assemble those from separate libraries, and it fits anyone who wants to read the algorithms that MeshLab is built on. It does not fit a commercial product that cannot ship GPL code, and it does not fit a project that wants a narrow, stable API surface, because the library is described as fairly large and the templates are the interface. Check three things before you commit. Check the licence exposure, since the library is released under the GPL and the project asks that questions about licensing portions of the library go to the named contact at the Visual Computing Lab, which is a sign that partial use is contemplated but not a blank cheque. Check the build entry point, since the repository root carries a CMakeLists.txt, an eigenlib directory that suggests a bundled linear algebra dependency, a wrap directory and an apps directory, and the README gives no install command, so the build story has to come from the project docs. And check the release cadence against your own timeline, because the newest tagged release is 2025.07 while the last push was on 2026-10-11, so development continues between dated snapshots. The last push was on 2026-10-11 and the library is licensed under GPL.

Frequently asked questions

Official sources

1. cnr-isti-vclab/vcglib on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases