mach/earcut: industrial-strength polygon triangulation
Turning polygons into triangle meshes is a challenging problem, with numerous edge-cases. Popular libraries that try to solve this problem include libtess2, libtess3, and poly2tri (including the MetricPanda poly2tri variant.) Some of these libraries are better than others, but all of them suffer from performance and correctness issues-often failing on some very simple polygon inputs.
State-of-the-art research into polygon tesselation includes CMU researcher Jonathan Shewchuk's outstanding 'Triangle' library, which is probably the most industrial-strength and correct polygon tesselator in existence today. Despite widespread adoption in some open source projects, it is proprietary and not legally suitable for inclusion in open source software.
The second most industrial-strength tesselation library in existence today is from a company called Mapbox, and is at the core of their map rendering technology. mach/earcut
is a port of their library to Zig. It is open-source and permissively licensed, and based on ideas from FIST: Fast Industrial-Strength Triangulation of Polygons by Martin Held and Triangulation by Ear Clipping by David Eberly - and optimized by z-order curve hashing.
It can handle holes, twisted polygons, degeneracies and self-intersections. While it doesn't guarantee correctness of triangulation, it attempts to always produce acceptable results for practical data. In effect, it is good for turning polygons into triangles for visualization.
It is faster and more correct than other libraries such as libtess, poly2tri, and others.
This Zig implementation is a direct port, and should theoretically be equally correct - and possibly faster than the mapbox version.
(This repository is a separate copy of the same library in the main Mach repository, and is automatically kept in sync, so that anyone can use this library in their own project if they like!)
Experimental
This is an experimental Mach library, according to our stability guarantees:
Experimental libraries may have their APIs change without much notice, and you may have to look at recent changes in order to update your code.
Why this library is not declared stable yet
Getting started
Adding dependency
Create a build.zig.zon
file in your project (replace $LATEST_COMMIT
with the latest commit hash):
.{
.name = "mypkg",
.version = "0.1.0",
.dependencies = .{
.mach_earcut = .{
.url = "https://github.com/hexops/mach-earcut/archive/$LATEST_COMMIT.tar.gz",
},
},
}
Run zig build
in your project, and the compiler instruct you to add a .hash = "..."
field next to .url
.
Then use the dependency in your build.zig
:
...
pub fn build(b: *Build) void {
...
exe.addModule("mach-earcut", b.dependency("mach_earcut", .{
.target = target,
.optimize = optimize,
}).module("mach-earcut"));
}
You may then const earcut = @import("mach-earcut);
and use it.
Usage
For usage, see src/main.zig
(look for test "basic"
)
Join the community
Join the Mach community on Discord to discuss this project, ask questions, get help, etc.
Issues
Issues are tracked in the main Mach repository.
Contributing
Contributions are very welcome. Pull requests must be sent to the main repository to avoid some complex merge conflicts we'd get by accepting contributions in both repositories. Once the changes are merged there, they'll get sync'd to this repository automatically.
Version
We currently reflect this version of the upstream library.