The fastest and smallest JavaScript polygon triangulation library. 2.5KB gzipped.
The library implements a modified ear slicing algorithm, optimized by z-order curve hashing and extended to handle holes, twisted polygons, degeneracies and self-intersections in a way that doesn't guarantee correctness of triangulation, but attempts to always produce acceptable results for practical data like geographical shapes.
It's based on ideas from FIST: Fast Industrial-Strength Triangulation of Polygons by Martin Held and Triangulation by Ear Clipping by David Eberly.
The aim of this project is to create a JS triangulation library that is fast enough for real-time triangulation in the browser, sacrificing triangulation quality for raw speed and simplicity, while being robust enough to handle most practical datasets without crashing or producing garbage. Some benchmarks:
| (ops/sec) | pts | earcut | libtess | poly2tri | pnltri |
|---|---|---|---|---|---|
| OSM building | 15 | 580,351 | 27,832 | 28,151 | 216,352 |
| dude shape | 94 | 29,848 | 6,194 | 3,575 | 13,027 |
| holed dude shape | 104 | 18,688 | 5,428 | 3,378 | 2,264 |
| complex OSM water | 2523 | 445 | 63.72 | failure | failure |
| huge OSM water | 5667 | 80.09 | 23.73 | failure | failure |
The original use case it was created for is Mapbox GL, WebGL-based interactive maps.
If you want to get correct triangulation even on very bad data with lots of self-intersections and earcut is not precise enough, take a look at libtess.js.
var triangles = earcut([[[10,0],[0,50],[60,60],[70,10]]]);
// [[0,50],[10,0],[70,10], [70,10],[60,60],[0,50]]Input should be an array of rings, where the first is outer ring and others are holes;
each ring is an array of points, where each point is of the [x, y] form.
Each group of three points in the resulting array forms a triangle.
NPM and Browserify:
npm install earcutBrowser builds:
npm install
npm run build-dev # builds dist/earcut.dev.js, a dev version with a source map
npm run build-min # builds dist/earcut.min.js, a minified production buildRunning tests:
npm test- Significantly improved performance for polygons with self-intersections (e.g. big OSM water polygons are now handled 2-3x faster)
- Significantly improved performance on polygons with high number of vertices by using z-order curve hashing for vertice lookup.
- Slightly improved overall performance with better point filtering.
- Improved performance on polygons with holes by switching from Held to Eberly hole elimination algorithm
- More robustness fixes and tests
- Various robustness improvements and fixes.
- Initial release.