|
| 1 | +## Earcut |
| 2 | + |
| 3 | +A C++ port of [earcut.js](https://github.com/mapbox/earcut), a fast, [header-only](https://github.com/mapbox/earcut.hpp/blob/master/include/mapbox/earcut.hpp) polygon triangulation library. |
| 4 | + |
| 5 | +[](https://travis-ci.com/github/mapbox/earcut.hpp) |
| 6 | +[](https://ci.appveyor.com/project/Mapbox/earcut-hpp-8wm4o/branch/master) |
| 7 | +[](https://coveralls.io/github/mapbox/earcut.hpp) |
| 8 | +[](https://scan.coverity.com/projects/14000) |
| 9 | +[](http://isitmaintained.com/project/mapbox/earcut.hpp "Average time to resolve an issue") |
| 10 | +[](http://isitmaintained.com/project/mapbox/earcut.hpp "Percentage of issues still open") |
| 11 | +[](https://github.com/mourner/projects) |
| 12 | + |
| 13 | +The library implements a modified ear slicing algorithm, optimized by [z-order curve](http://en.wikipedia.org/wiki/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. |
| 14 | + |
| 15 | +It's based on ideas from [FIST: Fast Industrial-Strength Triangulation of Polygons](http://www.cosy.sbg.ac.at/~held/projects/triang/triang.html) by Martin Held and [Triangulation by Ear Clipping](http://www.geometrictools.com/Documentation/TriangulationByEarClipping.pdf) by David Eberly. |
| 16 | + |
| 17 | +## Usage |
| 18 | + |
| 19 | +```cpp |
| 20 | +#include <earcut.hpp> |
| 21 | +``` |
| 22 | +```cpp |
| 23 | +// The number type to use for tessellation |
| 24 | +using Coord = double; |
| 25 | + |
| 26 | +// The index type. Defaults to uint32_t, but you can also pass uint16_t if you know that your |
| 27 | +// data won't have more than 65536 vertices. |
| 28 | +using N = uint32_t; |
| 29 | + |
| 30 | +// Create array |
| 31 | +using Point = std::array<Coord, 2>; |
| 32 | +std::vector<std::vector<Point>> polygon; |
| 33 | + |
| 34 | +// Fill polygon structure with actual data. Any winding order works. |
| 35 | +// The first polyline defines the main polygon. |
| 36 | +polygon.push_back({{100, 0}, {100, 100}, {0, 100}, {0, 0}}); |
| 37 | +// Following polylines define holes. |
| 38 | +polygon.push_back({{75, 25}, {75, 75}, {25, 75}, {25, 25}}); |
| 39 | + |
| 40 | +// Run tessellation |
| 41 | +// Returns array of indices that refer to the vertices of the input polygon. |
| 42 | +// e.g: the index 6 would refer to {25, 75} in this example. |
| 43 | +// Three subsequent indices form a triangle. Output triangles are clockwise. |
| 44 | +std::vector<N> indices = mapbox::earcut<N>(polygon); |
| 45 | +``` |
| 46 | +
|
| 47 | +Earcut can triangulate a simple, planar polygon of any winding order including holes. It will even return a robust, acceptable solution for non-simple poygons. Earcut works on a 2D plane. If you have three or more dimensions, you can project them onto a 2D surface before triangulation, or use a more suitable library for the task (e.g [CGAL](https://doc.cgal.org/latest/Triangulation_3/index.html)). |
| 48 | +
|
| 49 | +
|
| 50 | +It is also possible to use your custom point type as input. There are default accessors defined for `std::tuple`, `std::pair`, and `std::array`. For a custom type (like Clipper's `IntPoint` type), do this: |
| 51 | +
|
| 52 | +```cpp |
| 53 | +// struct IntPoint { |
| 54 | +// int64_t X, Y; |
| 55 | +// }; |
| 56 | +
|
| 57 | +namespace mapbox { |
| 58 | +namespace util { |
| 59 | +
|
| 60 | +template <> |
| 61 | +struct nth<0, IntPoint> { |
| 62 | + inline static auto get(const IntPoint &t) { |
| 63 | + return t.X; |
| 64 | + }; |
| 65 | +}; |
| 66 | +template <> |
| 67 | +struct nth<1, IntPoint> { |
| 68 | + inline static auto get(const IntPoint &t) { |
| 69 | + return t.Y; |
| 70 | + }; |
| 71 | +}; |
| 72 | +
|
| 73 | +} // namespace util |
| 74 | +} // namespace mapbox |
| 75 | +``` |
| 76 | + |
| 77 | +You can also use a custom container type for your polygon. Similar to std::vector<T>, it has to meet the requirements of [Container](https://en.cppreference.com/w/cpp/named_req/Container), in particular `size()`, `empty()` and `operator[]`. |
| 78 | + |
| 79 | +<p align="center"> |
| 80 | + <img src="https://camo.githubusercontent.com/01836f8ba21af844c93d8d3145f4e9976025a696/68747470733a2f2f692e696d6775722e636f6d2f67314e704c54712e706e67" alt="example triangulation"/> |
| 81 | +</p> |
| 82 | + |
| 83 | +## Additional build instructions |
| 84 | +In case you just want to use the earcut triangulation library; copy and include the header file [`<earcut.hpp>`](https://github.com/mapbox/earcut.hpp/blob/master/include/mapbox/earcut.hpp) in your project and follow the steps documented in the section [Usage](#usage). |
| 85 | + |
| 86 | +If you want to build the test, benchmark and visualization programs instead, follow these instructions: |
| 87 | + |
| 88 | +### Dependencies |
| 89 | + |
| 90 | +Before you continue, make sure to have the following tools and libraries installed: |
| 91 | + * git ([Ubuntu](https://help.ubuntu.com/lts/serverguide/git.html)/[Windows/macOS](http://git-scm.com/downloads)) |
| 92 | + * cmake 3.2+ ([Ubuntu](https://launchpad.net/~george-edison55/+archive/ubuntu/cmake-3.x)/[Windows/macOS](https://cmake.org/download/)) |
| 93 | + * OpenGL SDK ([Ubuntu](http://packages.ubuntu.com/de/trusty/libgl1-mesa-dev)/[Windows](https://dev.windows.com/en-us/downloads/windows-10-sdk)/[macOS](https://developer.apple.com/opengl/)) |
| 94 | + * Compiler such as [GCC 4.9+, Clang 3.4+](https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test), [MSVC12+](https://www.visualstudio.com/) |
| 95 | + |
| 96 | +Note: On some operating systems such as Windows, manual steps are required to add cmake and [git](http://blog.countableset.ch/2012/06/07/adding-git-to-windows-7-path/) to your PATH environment variable. |
| 97 | + |
| 98 | +### Manual compilation |
| 99 | + |
| 100 | +```bash |
| 101 | +git clone --recursive https://github.com/mapbox/earcut.hpp.git |
| 102 | +cd earcut.hpp |
| 103 | +mkdir build |
| 104 | +cd build |
| 105 | +cmake .. |
| 106 | +make |
| 107 | +# ./tests |
| 108 | +# ./bench |
| 109 | +# ./viz |
| 110 | +``` |
| 111 | + |
| 112 | +### [Visual Studio](https://www.visualstudio.com/), [Eclipse](https://eclipse.org/), [XCode](https://developer.apple.com/xcode/), ... |
| 113 | + |
| 114 | +```batch |
| 115 | +git clone --recursive https://github.com/mapbox/earcut.hpp.git |
| 116 | +cd earcut.hpp |
| 117 | +mkdir project |
| 118 | +cd project |
| 119 | +cmake .. -G "Visual Studio 14 2015" |
| 120 | +::you can also generate projects for "Visual Studio 12 2013", "XCode", "Eclipse CDT4 - Unix Makefiles" |
| 121 | +``` |
| 122 | +After completion, open the generated project with your IDE. |
| 123 | + |
| 124 | + |
| 125 | +### [CLion](https://www.jetbrains.com/clion/), [Visual Studio 2017+](https://www.visualstudio.com/) |
| 126 | + |
| 127 | +Import the project from https://github.com/mapbox/earcut.hpp.git and you should be good to go! |
| 128 | + |
| 129 | +## Status |
| 130 | + |
| 131 | +This is currently based on [earcut 2.2.4](https://github.com/mapbox/earcut#224-jul-5-2022). |
0 commit comments