optimesh: several mesh smoothing methods behind one interface

A small tool with one interface and several algorithms

The pitch in the README is four bullet points, and they define the scope precisely. optimesh is fast, it preserves submeshes, it only works for triangular meshes that are flat and on a surface for now, and it supports all mesh formats that meshio can handle.

That last point is the one to sit with. The format support is inherited rather than implemented, which means the file handling side of the tool is not where the work is, and a new format becomes available as soon as meshio supports it rather than when optimesh does.

The package lives on PyPI as optimesh, and the repository carries badges for the PyPI version, the supported Python versions, a Zenodo DOI, the Discord server and the PyPI download statistics. The DOI badge is a signal worth noting: the project is archived with a persistent identifier, which is what you want for a piece of research software that other people's papers cite.

The intended users are people working with finite element meshes and simulation data, and the repository topics reflect that, listing engineering, fem, mathematics, mesh, mesh-generation, meshing, physics, pypi and python.

The command line reads a mesh and writes a better one

The usage example is a single command:

optimesh in.e out.vtk

An input file, an output file, and the extension decides the format, which is the meshio convention. The tool then prints two graphs, and the README explains what they show.

The left hand side graph is the distribution of angles, with the grid line at the optimal 60 degrees. The right hand side graph is the distribution of simplex quality, where quality is twice the ratio of the circumcircle and the incircle radius. Read together, they tell you the shape distribution of the elements and how close they are to equilateral.

That output is the point of the tool, because a mesh that has better element quality behaves better in a solver, and the two graphs are the evidence rather than a promise. It is also the reason the tool is useful on an existing mesh: you can run it, look at the distributions, and judge whether the smoothing actually helped.

Every command line option is documented through the help output:

optimesh -h

Three algorithm families and the trade-off between them

The examples section walks through the algorithms, all starting from the same randomly generated disk mesh, with the cell colouring indicating quality, dark green for bad and yellow for good.

Centroidal Voronoi tessellation smoothing is described as one of the oldest and most reliable approaches, following Du and others. The classical implementation is Lloyd's algorithm, selected with --method lloyd and an --omega parameter, and the uniform-density variants are quasi-Newton iterations, one with a block-diagonal Hessian given by --method cvt-block-diagonal and the default --method cvt-full using the full Hessian.

Centroidal patch tessellation comes from Chen and Holst and mimics CVT but is much easier to implement. The README makes a precise claim here: the density-preserving variant leads to the exact same equation system as Laplacian smoothing, so CPT smoothing can be thought of as a generalization of it. The uniform-density variants exist as a fixed-point iteration, --method cpt-fixed-point, and as a quasi-Newton method, --method cpt-quasi-newton, with the latter typically converging faster.

Optimal Delaunay triangulation, also from Chen and Holst, is typically superior to CPT but more expensive to compute. It is implemented as a density-preserving fixed-point iteration, --method odt-dp-fp, a uniform-density fixed-point iteration, --method odt-fixed-point, and a uniform-density BFGS method, --method odt-bfgs, where the nonlinear optimisation typically leads to better results.

So the choice is concrete: reliability first, then ease and generalisation, then quality at a higher cost.

Triangles only, and only where the maths is defined

The limitation is stated in the feature list rather than hidden in the documentation, and it is a real constraint. optimesh only works for triangular meshes, flat and on a surface, for now, and the README links an issue for readers interested in tetrahedral mesh smoothing, with a note to upvote it.

That is not an oversight but a scope decision. The methods implemented are defined for flat and surface meshes, and extending them to tetrahedra means solving a different problem rather than adding a flag. Anyone arriving with volumetric tetrahedral meshes will find the tool stops at the front door, and the honest advice is to treat the tetrahedral issue as a roadmap rather than a plan.

Two other constraints come from the same bullet list. Submeshes are preserved, which matters when a mesh contains several material regions that must stay separated, and the format support follows meshio, so the formats you can read and write are the ones meshio handles.

The upstream project is nschloe/optimesh, and this repository, meshpro/optimesh, is the distribution point: the logo, the star badge and the issue links in the README all point at nschloe. Its own top level holds only .nojekyll and README.md, so the code, the tests and the issue tracker all live in the upstream repository.

The Python API takes points, cells and a method name

For use inside a program, the package exposes a function that takes the mesh data and returns the improved mesh, and the README shows the shape of the call:

import optimesh

# [...] create points, cells [...]

points, cells = optimesh.optimize_points_cells(
    points, cells, "CVT (block-diagonal)", 1.0e-5, 10

The arguments are the point coordinates, the cell definitions, the method, a tolerance of 1.0e-5, and a limit of 10 iterations, with the result assigned back to the same two names. The method argument is a human readable name rather than the command line spelling, and CVT (block-diagonal) is the variant that corresponds to the block-diagonal Hessian option in the command line.

That difference in spelling is a small but real friction. The command line takes identifiers like cvt-block-diagonal, while the function takes a display string, so a script that mirrors a command line workflow needs the two names mapped by hand.

The other two arguments are the ones that matter for a pipeline. The tolerance sets when the iteration stops, and the iteration count caps the work, so a large production mesh needs both of them chosen with the run time in mind rather than left at the example values.

The licence is a purchase, not a grant

This is the part of the README that a technical reader tends to skim and an organisation should not, because the repository metadata and the licence section do not agree.

The project page lists the licence as unknown, and the README explains how to get a licence instead. Licences for personal and academic use can be purchased through a payment link, and you receive a confirmation email with a licence key, which is then installed on your machine with:

slim install <your-license-key>

For commercial use, the README says to contact [email protected]. The installation step itself is the ordinary one:

pip install optimesh

So the package installs freely from PyPI and the terms attach to use rather than to the download. That is a commercial licensing arrangement layered on top of code that a reader may well assume is open source, and the two facts need to be reconciled before the tool goes into a pipeline.

The company behind the arrangement is mondaytech, and the Discord server linked in the README is where support questions are asked. The Zenodo DOI and the pypistats badge suggest an academic and research audience, which fits the fem and physics topics, and it is exactly that audience that the personal and academic licence tier is written for.

Editorial conclusion

Adopt optimesh if you generate triangular meshes for finite element work or simulation and want to improve element quality with a method you can choose, either from the command line or from Python. Skip it if you need tetrahedral smoothing, since the project states it works on triangular meshes only for now, or if you need a licence you can read and comply with, since personal and academic use requires a purchased key. Before your first run, read the licence section carefully, because the package installs from PyPI without a key but usage is licensed, and check that your mesh is flat or on a surface. The last push was on 2026-05-18 and the repository has no GitHub releases.

Frequently asked questions

Official sources

1. Issues
2. meshpro/optimesh on GitHub
3. README