Triangula: genetic-algorithm triangulation art from the command line

What Triangula produces, and who the output is for

Triangula is a Go program that reconstructs an image out of triangles or polygons. The README describes it as "an iterative algorithm to generate high quality triangulated and polygonal art from images", and the repository is organised around that single job: algorithm/, fitness/, generator/, mutation/, triangulation/, polygonation/, rasterize/ and render/ are the directories that do the work. This is not a filter you apply and forget. It is a search process that keeps proposing new point arrangements and keeps the ones that look more like the source image.

The intended user is someone producing a still image, not someone processing a stream. The README's own guidance is that it "works best with images smaller than 3000px and with fewer than 3000 points", and that it typically produces an optimal result "within a couple of minutes". Those two numbers set the ceiling on the input and on the search space. A 6000px photograph is outside the stated range, and asking for 5000 points puts you outside it as well.

There is a second audience: Go developers who want the algorithm as a library rather than as an application. The main module is importable, the package documentation is published on pkg.go.dev, and the README includes an API example that wires the algorithm together by hand. The GUI and the CLI are separate repositories, which tells you the maintainers treat the core as the product and the front ends as wrappers.

How the modified genetic algorithm actually runs

The pipeline starts with an image decoded into pixel data. A point factory generates a starting set of normalised points. An evaluator scores a candidate arrangement by comparing a rendered version against the original image, and a mutator perturbs points to create the next generation. The algorithm object steps forward one generation at a time, and a stats call exposes the best fitness so far.

The word modified matters. A plain genetic algorithm would treat a whole point set as one genome and recombine two parents. Triangula's README points to a wiki page, "Explanation of the algorithm", for the full account, and the repository's directory names suggest the structure: generator/ for point sets, mutation/ for the perturbation methods, fitness/ for scoring, and triangulation/ or polygonation/ for turning points into a mesh. The Go module requires github.com/fogleman/delaunay, which is consistent with a Delaunay-based triangulation step, and github.com/panjf2000/ants/v2, a goroutine pool, which is consistent with the parallel evaluator used in the API example.

That parallelism is where the speed comes from. The example constructs the evaluator with a cache size and a block size, then wraps it in a parallel evaluator. Rendering is done in blocks, and the cache is specified as a power of two, 22 by default. The README's options table exposes the same two values as --cache and --block. In practice the evaluator is the hot loop: every generation scores every candidate, so block size and cache size are the knobs that trade memory for evaluation speed, while --threads decides how many cores join in.

The output is not the image itself. The CLI writes a JSON file describing the geometry, and a separate render step turns that JSON plus the original image into an SVG. That split is deliberate. You can keep improving the JSON, or render it repeatedly with different effects, without re-running the search.

Installing the CLI and running a first triangulation

The README offers two install paths. The GUI is downloaded from the Triangula-GUI releases page and uses Wails for its frontend; on Linux the README says to open the executable's properties, go to the Permissions tab, and tick "Allow executing file as program" if the app does not start. The CLI is installed with go get from a separate repository:

go get -u github.com/RH12503/Triangula-CLI/triangula

The README notes that your PATH must include your go/bin directory, which it gives as ~/go/bin on macOS, $GOPATH/bin on Linux, and c:\Go\bin on Windows. If the command is not found after installing, that is the first thing to check.

The run step takes an image and an output path for the JSON:

triangula run -img <path to image> -out <path to output JSON>

Expect this to take minutes, not seconds. The CLI saves to the output file every --reps generations, 500 by default, so you can inspect intermediate JSON while the process is still running. When the fitness looks acceptable, render an SVG from the saved JSON and the original image:

triangula render -in <path to outputted JSON> -img <path to image> -out <path to output SVG>

The README points to the Triangula-CLI repository for rendering PNGs with effects. On options, the README is blunt: for almost all cases, changing only the number of points and leaving everything else at its default generates an optimal result. The point count is set with --points or -p, and the default is 300. The other defaults are --mutations 2, --variation 0.3, --population 400, --cutoff 5, --cache 22, --block 5, and --threads 0, where 0 means use all cores.

Where Triangula is the wrong tool

The clearest limitation is stated by the project itself in its comparison with esimov/triangle: the other tool "generates an image almost instantaneously, while Triangula needs to run many iterations". If your workflow is interactive, if you are generating thumbnails in a request handler, or if you need to re-render after every small edit, a genetic search is the wrong shape of computation. There is no documented way to resume a run from a saved JSON and continue improving it; the README describes writing JSON during a run, not loading one back into the algorithm.

Scale is the second boundary. The README's own guidance puts the useful range under 3000px and under 3000 points. A point count in the thousands means a large search space, and the fitness evaluation cost grows with it. Nothing in the README claims the algorithm degrades gracefully past those numbers, and nothing documents a timeout or a convergence guarantee. You stop when the fitness looks good enough to you.

The polygon mode is easy to misread. The v1.2.0 release is titled "Polygonal art", and the API example notes that you use PolygonsImageFunctions for polygons instead of the triangles variant. That is a different rendering function inside the same search loop, not a different algorithm, and the README's options table has no flag for switching between them. The CLI documentation is where the polygon path is spelled out, and the main README does not cover it.

Finally, the release history is old relative to the repository's activity. The most recent release listed is v1.2.0 from 2021-05-21, while the last push to the repository was on 2026-03-21. Code has moved since the last tagged release, so a build from the default branch is not the same artifact as the v1.2.0 release.

Triangula against esimov/triangle and fogleman/primitive

The README addresses both comparisons directly, which is unusual and useful. Against esimov/triangle, also written in Go, the stated difference is style and speed: the two "appear to generate very different styles", and triangle's advantage is near-instant output. The README's comparison images were, by its own account, generated over 1 to 2 minutes for the Triangula side. So the decision is not which is better but which constraint you are under. If you need a result now, triangle wins on the only axis that matters.

Against fogleman/primitive and gheshu/image_decompiler, the README makes a structural distinction rather than a quality one. All three are iterative, but in the other algorithms "triangles can overlap while Triangula generates a triangulation". A triangulation is a mesh: triangles meet edge to edge and do not intersect. That constraint is visible in the output. Overlapping primitives can paint over earlier shapes, which lets a primitive algorithm add a small shape late in the run to fix a local error. A triangulation cannot do that without disturbing its neighbours, so the search has to move points rather than stack shapes.

The practical consequence is that Triangula's output reads as a faceted surface, while primitive-style output reads as a collage. If you want the collage look, Triangula is the wrong choice regardless of how long you let it run. The README's own example gallery splits the two modes into triangulated and polygonal sets, and the polygon results are still meshes, not overlapping primitives.

Licence, maintenance and what an upgrade costs

Triangula is MIT licensed, and the LICENSE file sits at the top level of the repository. MIT is permissive: it allows use, modification and redistribution, including in closed products, provided the copyright notice and permission notice are kept. That is the general shape of the licence, not legal advice, and the file itself is short enough to read in full before you ship anything.

One licence detail worth noting for anyone embedding the library: the go.mod file lists dependencies including github.com/fogleman/delaunay, github.com/panjf2000/ants/v2 and github.com/stretchr/testify, and those carry their own licences. The main repository's MIT licence does not automatically cover them. If you vendor the module, check each dependency's terms.

On maintenance: the repository is not archived, and the last push was on 2026-03-21. The most recent tagged release is v1.2.0 from 2021-05-21. That gap is the real upgrade cost. There is no published changelog beyond the release titles ("Polygonal art", "Dark mode", "Major bug fix"), so a consumer pinning v1.2.0 has no documented list of what changed between that tag and the current default branch. The Go module declares go 1.16, which is old enough that a modern toolchain will still build it but will not be exercising the same language and module behaviour the author used.

The GUI is a separate repository pinned to Wails, and the CLI is a third repository. Upgrading the core library does not upgrade either front end, and the reverse is also true. If you depend on the CLI, you are depending on two repositories moving together, and only one of them is in the module you import.

Editorial conclusion

Triangula suits people who want a triangulation, meaning non-overlapping triangles that share edges, and who accept a run measured in minutes rather than milliseconds. It is the wrong tool when you need an image back immediately, and it is the wrong tool if you want overlapping shapes, which is what fogleman/primitive and gheshu/image_decompiler produce. Before committing, verify two things: which repository you are installing, since the GUI and the CLI live outside the main module, and how the --points value interacts with the --reps and --cutoff defaults, because the README states that changing the point count alone is enough for almost all cases.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. rh12503/triangula on GitHub