gptoolbox and what a decade of geometry processing code looks like in MATLAB

A function library, not an application

gptoolbox is described as a toolbox of useful matlab functions for geometry processing, with tools related to constrainted optimization and image processing, and the readme is explicit about what that means in practice: typically these are utility functions that are not stand alone applications.

That framing is the whole design, and it determines how you use it. There is no application here, no command line tool and no scene graph. You clone the repository, add it to the MATLAB path, and call functions. The functions have been organized into folders based on their primary application: `external/`, `imageprocessing/`, `images/`, `matrix/`, `mex/`, `utility/` and `wrappers/`.

The breadth is the other thing worth noting. The feature list is long and covers wrappers for TetGen, Triangle, QSlim and meshfix; mesh smoothing; mesh clean up to remove duplicates and unreferenced items; geodesic distances on triangle and tetrahedral meshes; mesh quantities and queries including normals, discrete gaussian curvature, boundary edges, topology, angles and dihedral angles; mesh deformation through as-rigid-as-possible and moving least squares; mesh parameterization through harmonic, least squares conformal and ARAP methods; automatic skinning weight computation with bounded biharmonic weights and bone heat; 2D triangle meshes from binary images; input and output for many mesh formats; discrete differential geometry operators such as the cotangent Laplacian, gradient and divergence; quadratic programming and an active set solver; scribble based image colorization and diffusion curves; exact signed and unsigned distance field computation for meshes; constructive solid geometry operations and booleans; accelerated point location in triangle and tetrahedral meshes; image dithering; and deep MATLAB function dependency.

The last item on that list, deep MATLAB function dependency, is the mechanism that makes the collection usable at all. A geometry processing library is a web of functions calling each other, and if each function only knew about the ones directly above it, users would have to know the call graph. The dependency tooling makes the toolbox self-contained in a way that matters when you are pulling in one function from a directory of two hundred.

The formats list is also worth reading as a compatibility statement: `.obj`, `.off`, `.stl`, `.wrl`, `.ply`, `.mesh`, `.node`, `.ele`, `.poly`, `.smf`, `.bdl` and `.face`.

Installation is a path statement, and then a compiler

The installation is unusually simple for a toolbox of this size, and the simplicity is the point.

The vast majority of the code is straight MATLAB, `*.m` files, so only installing MATLAB and adding the gptoolbox directory and its subdirectories to the MATLAB path is needed. Assuming you cloned gptoolbox at `/Users/ajx/Repos/gptoolbox/`, the readme gives the exact statement:

addpath(strjoin(strcat(['/Users/ajx/Repos/gptoolbox/'],{'external','imageprocessing', 'images', 'matrix', 'mesh', 'mex', 'quat','utility','wrappers'}),':'))

Note that the list of directories in that statement includes `quat`, which is not in the folder list in the feature section of the readme but is present in the repository layout.

To make the change permanent you then issue `savepath`.

The second half of the installation is the compiled part. There are some mex files, whose documentation for installation is included in the respective `mex/README.md` file, and the readme notes the full installation strives to be full but will no doubt remain incomplete for some time. Most of the mex files depend on libigl, some depend on CGAL and embree, and the project recently switched to a cmake-based build.

There is also a separate build for one bundled external tool, in MATLAB issue:

cd external/toolbox_fast_marching/
compile_mex

The order of operations is the sensible one. Add the path and the pure MATLAB functions work immediately, and the compiled parts are optional until you need them. For a researcher who wants one function to read rather than a library to deploy, that is the right trade.

The dependencies are the hard part, and they need hand configuration

The dependencies section is where the honest costs of this toolbox live.

gptoolbox depends on MATLAB and some of its toolbox extensions, and many functions should also work with Octave, though this has not been tested. That caveat matters, because Octave compatibility is exactly the kind of claim that a graphics researcher would want to rely on, and a half tested path is worth knowing about before you plan on it.

The optimisation functions have their own dependency story. Functions that rely on `quadprog` have been tested and optimized assuming that the Mosek toolbox has been installed, but should also work with the `quadprog` in MATLAB's Optimization Toolbox. So there is a performance and a numerics difference between the two routes through the same function, which is the kind of thing that changes results in a tight optimisation.

Mex files may have other external dependencies, such as CGAL, Eigen and libigl, and the readme is candid that when installing mex libraries you may need to modify the files in `wrappers/`, giving `path_to_libigl.m` as the example, so that gptoolbox knows where to look.

That last point is the real operational detail. There is no package manager, no dependency resolution and no vendored binary. The compiled half of the toolbox expects you to have libigl, and possibly CGAL and embree, installed on the machine at a path that the wrapper files know about, and it expects you to edit those wrapper files to point at it. On a shared cluster or a CI runner, that is a per-machine setup step rather than a one line install, and it is the part of this project that will consume your time.

The `external/` directory is a related concern, and it is where the licence complexity lives too.

Dual licensing, with a directory that is not

The licensing is stated in three sentences and one of them needs reading twice.

This work is dual licensed under MIT and Apache 2, and the repository carries both `LICENSE-MIT` and `LICENSE.Apache-2.0` at the root. The third sentence is the important one: please take extra note that the `external/` directory contains code from elsewhere with potentially more restricted licenses. Most of the `mex/` directory includes libigl and Eigen, and some include CGAL, each with their own licenses.

So the licence of a given function depends on where it lives. A function in `mesh/` is under MIT and Apache 2, and a function in `external/` or in the vendored parts of `mex/` carries whatever the upstream project required. If you are publishing work that uses this toolbox, the obligation is not uniform across the tree, and the directory a function came from is the thing you have to track.

There is also a documentation-related request in the attribution section, which is unusual to see. If you use gptoolbox in your academic projects, please cite the papers we implement as appropriate, and to cite the library in general you could use a BibTeX entry.

The provenance of the project is worth knowing too, because it explains the code style. The Geometry Processing Toolbox grew out of Alec Jacobson's private codebase during his PhD, and it has benefited from collaborators at NYU, ETH Zurich, Columbia, the University of Toronto and elsewhere. The readme says it is now a group endeavour and invites contributions through Alec Jacobson or a pull request on GitHub.

The top level listing supports that reading of the project as a research codebase rather than a packaged library. There is a `RELEASE_HISTORY.txt`, a `TODO.todo`, a `style.md`, a `CLAUDE.md`, a `.mailmap` file, a `python/` directory that is not documented in the readme, and a `quat/` directory that the readme's folder list omits.

Documentation is one help command at a time

The documentation section is the shortest part of the readme and the most revealing about how the project is meant to be consumed.

For now, documentation is limited to a per-function basis, and the example given is to find documentation for `cotmatrix` by issuing `help cotmatrix` in MATLAB. So the docstrings inside the `.m` files are the reference, and the readme is a map to them rather than a manual.

For a project whose function list runs to a hundred and fifty entries, per-function docstrings are a defensible choice, and they are the only kind of documentation that stays correct as the code changes. The cost is that you cannot answer structural questions from the documentation alone. There is no guide to which smoothing method suits which mesh, no table mapping a task to a function, and no explanation of the conventions the toolbox follows.

The function names are the main navigational aid, and many of them are the standard names from the geometry processing literature, which is a point in the toolbox's favour. A researcher who knows the field will guess at names like `cotmatrix` and be right. A practitioner who does not will have to try them.

So the adoption path is: skim the feature list in the readme, find the two or three functions you actually need, and read their docstrings. That works, and it is fast, provided you already know what you are looking for. It does not work if you want to survey what is available before choosing an approach, and the readme's own list is explicitly described as incomplete.

There is a Python directory in the repository that the readme does not mention at all. Whether it is a port, a binding or a work in progress is not something the visible documentation answers, and it is worth a look before you assume the toolbox is MATLAB only.

Where a MATLAB research toolbox is the wrong tool

There are three situations where gptoolbox is the wrong choice, and they are more common than the feature list suggests.

The first is a production pipeline. This is research code that grew out of a PhD codebase, with no package manager, hand-edited path configuration for native libraries, and per-function documentation. That is an excellent shape for a research toolbox and a poor shape for software that has to run in CI on a machine you do not administer. The mex build alone, with libigl located by a wrapper file you edit, is a blocker for reproducible builds.

The second is a team that does not have MATLAB. The Octave path is described as should also work but has not been tested, and the toolbox depends on MATLAB toolbox extensions. A team standardising on Python, with the `python/` directory in the repository as a hint of where that could go, is looking at a porting project rather than an install.

The third is a case where you need a maintained library with a stable API. gptoolbox functions are utilities without stand alone applications, which means there is no versioned interface, no deprecation policy and no compatibility promise between releases. The repository publishes no GitHub releases at all, and while it does carry a `RELEASE_HISTORY.txt` and a `TODO.todo`, the versioning story is not the one a dependency needs.

The fourth, smaller point is about the algorithms themselves. This is a toolbox of implementations, and the readme does not claim they are the fastest or the most dependable. For a production mesh pipeline where deformation quality and speed both matter, a maintained library with a performance focus is a different investment.

What gptoolbox is genuinely good for is reading. If you want to understand how an as-rigid-as-possible deformation is implemented, or how bounded biharmonic weights are computed, or how a signed distance field is computed exactly, a readable MATLAB implementation with a docstring is a good way to read them, and then reimplement in whatever you actually ship.

Editorial conclusion

gptoolbox fits a researcher or student who needs to read how a geometry processing algorithm is written, who wants the reference implementation rather than a library with a stable API, and who already has MATLAB. It is the wrong choice for a production pipeline, because the documentation is per-function, the external dependencies have to be located by hand, and the licence varies by directory. Before you rely on it, verify three things: which of the functions you need are pure MATLAB and run without compiling, how the mex libraries in `mex/` are configured for your machine, since the installation notes say you may need to modify files in `wrappers/` such as `path_to_libigl.m` so the toolbox knows where to look, and which licence applies to the specific subdirectory you are using. The code is dual licensed under MIT and Apache 2, the `external/` directory carries more restrictive licences, and the last push was on 2026-10-09.

Frequently asked questions

Official sources

1. alecjacobson/gptoolbox on GitHub
2. Issues
3. License: Apache-2.0
4. README