Polygon Geometry Processing: Clipping, Boolean Ops, and Triangulation
clipper-lib and polygon-clipping are libraries designed for boolean operations on polygons, such as union, intersection, and difference. They are used when you need to calculate new shapes from existing ones. earcut serves a different purpose — it triangulates polygons for rendering in WebGL. While clipper-lib and polygon-clipping modify geometry logic, earcut prepares geometry for the GPU. Choosing the right tool depends on whether you need to compute shape relationships or draw them on screen.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
Polygon Geometry Processing: Clipping, Boolean Ops, and Triangulation
When working with 2D geometry in JavaScript, you usually face two distinct problems — either you need to calculate new shapes from existing ones (boolean operations), or you need to prepare shapes for rendering (triangulation). clipper-lib, polygon-clipping, and earcut address these needs differently. Understanding their core functions prevents architectural mismatches in your graphics pipeline.
🧩 Core Task: Boolean Operations vs. Triangulation
The most critical distinction is what each library actually computes. clipper-lib and polygon-clipping perform boolean logic like union or intersection. earcut does not do this — it only converts polygons into triangles.
clipper-lib executes boolean operations using a classic clipping algorithm. You must define a subject and a clip path.
// clipper-lib: Boolean Intersection
var clipper = new ClipperLib.Clipper();
clipper.AddPaths(subjectPaths, ClipperLib.PolyType.ptSubject, true);
clipper.AddPaths(clipPaths, ClipperLib.PolyType.ptClip, true);
clipper.Execute(ClipperLib.ClipType.ctIntersection, solutionPaths);
polygon-clipping performs similar boolean operations but with a simpler function call structure.
// polygon-clipping: Boolean Intersection
const result = polygonClipping.intersect(
[ [[0,0], [10,0], [10,10], [0,10]] ],
[ [[5,5], [15,5], [15,15], [5,15]] ]
);
earcut does not support boolean operations. It triangulates input vertices for rendering.
// earcut: Triangulation (No boolean ops supported)
// Returns indices for WebGL drawing, not new polygon shapes
const triangles = earcut(vertices, holeIndices, 2);
📥 Input Data Structure: Arrays vs. Objects
How you feed data into these libraries varies significantly. clipper-lib uses specific path objects. polygon-clipping uses nested arrays. earcut uses flat arrays for performance.
clipper-lib requires paths to be arrays of points with X and Y properties.
// clipper-lib: Path format
var subject = [{ X: 0, Y: 0 }, { X: 10, Y: 0 }, { X: 10, Y: 10 }];
var paths = [subject]; // Array of paths
polygon-clipping accepts standard nested coordinate arrays similar to GeoJSON.
// polygon-clipping: Coordinate arrays
const poly = [[[0, 0], [10, 0], [10, 10], [0, 10]]];
// Outer ring first, then holes
earcut expects a flat array of numbers for maximum speed.
// earcut: Flat array [x0, y0, x1, y1, ...]
const vertices = [0, 0, 10, 0, 10, 10, 0, 10];
const holes = []; // Indices where holes start
const dimensions = 2; // x,y
🎯 Precision Handling: Integers vs. Floats
Floating point errors can break geometry algorithms. clipper-lib avoids this by using integers. polygon-clipping and earcut work with floats directly.
clipper-lib scales coordinates to integers internally to maintain precision.
// clipper-lib: Scaling required
var scale = 1000;
var intPath = path.map(p => ({ X: p.x * scale, Y: p.y * scale }));
// Must scale back after processing
polygon-clipping handles floating point numbers natively.
// polygon-clipping: Floats supported directly
const poly = [[[0.1, 0.1], [10.5, 0.5], [10.9, 10.1]]];
// No manual scaling needed
earcut also works with floats but focuses on rendering precision.
// earcut: Floats for vertex positions
const vertices = [0.5, 0.5, 10.5, 0.5, 10.5, 10.5];
// Precision depends on WebGL buffer setup
⚡ Performance & Use Cases
Performance depends on the task. earcut is optimized for rendering loops. clipper-lib is optimized for complex boolean logic. polygon-clipping balances ease of use with speed.
clipper-lib is best for heavy computational loads where accuracy matters most.
// clipper-lib: Heavy duty processing
// Use when calculating thousands of intersections
clipper.Execute(ClipperLib.ClipType.ctUnion, solution);
polygon-clipping is best for interactive frontend features.
// polygon-clipping: Interactive UI
// Use for user-driven shape editing in browser
const updated = polygonClipping.union(shape1, shape2);
earcut is best for real-time rendering frames.
// earcut: Render loop
// Use inside requestAnimationFrame for maps
const indices = earcut(vertices, holes, 2);
gl.drawElements(gl.TRIANGLES, indices.length, gl.UNSIGNED_INT, 0);
📊 Summary: Capability Matrix
| Feature | clipper-lib | polygon-clipping | earcut |
|---|---|---|---|
| Boolean Ops | ✅ Union, Intersect, Diff | ✅ Union, Intersect, Diff | ❌ Not Supported |
| Triangulation | ❌ Not Supported | ❌ Not Supported | ✅ Primary Function |
| Coordinates | 🔢 Integer (Scaled) | 🔢 Floating Point | 🔢 Floating Point |
| Input Format | 📄 Path Objects | 📄 Nested Arrays | 📄 Flat Arrays |
| Primary Use | 🧮 Geometry Logic | 🧮 Geometry Logic | 🎨 Rendering |
💡 Final Recommendation
These libraries solve different parts of the geometry pipeline. If you need to calculate where shapes overlap or combine them, use polygon-clipping for simplicity or clipper-lib for maximum precision on large datasets. If you need to draw those shapes on a canvas or WebGL context, pass the result to earcut to generate triangles. Do not try to use earcut for logic — it only prepares data for the GPU. Combining polygon-clipping for logic and earcut for rendering is a common and effective pattern in modern frontend architecture.
How to Choose: clipper-lib vs earcut vs polygon-clipping
- clipper-lib:
Choose
clipper-libif you need robust boolean operations on complex polygons and can manage integer coordinate scaling. It is a port of a mature C++ library, making it reliable for heavy-duty geometry tasks where precision is critical. However, it requires more setup to handle coordinate conversion compared to pure JavaScript options. It is best suited for backend geometry processing or intensive client-side calculations. - earcut:
Choose
earcutif your goal is to render polygons efficiently in WebGL or Canvas. It does not perform boolean operations but excels at breaking polygons into triangles for graphics pipelines. This library is extremely fast and is the standard choice for map rendering and data visualization. Use it when you already have valid polygons and need to draw them. - polygon-clipping:
Choose
polygon-clippingif you need boolean operations in a pure JavaScript environment without integer scaling. It handles floating-point coordinates directly and returns GeoJSON-like structures, which simplifies integration with web maps. It is easier to set up thanclipper-libbut may be slower on very large datasets. It is ideal for frontend apps that need dynamic shape manipulation.
Popular Comparisons
README for clipper-lib
ClipperLib
forked from Javascript Clipper
Description
The Javascript Clipper library performs clipping and offsetting for both lines and polygons. All four boolean clipping operations are supported - intersection, union, difference and exclusive-or. Polygons can be of any shape including self-intersecting polygons.
Javascript Clipper is a port of Angus Johnson's Clipper library: https://sourceforge.net/projects/polyclipping/
LIVE DEMO: http://jsclipper.sourceforge.net/6.2.1.0/main_demo.html
Information and examples: http://jsclipper.sourceforge.net/6.2.1.0/
Donate Javascript Clipper Project: https://sourceforge.net/p/jsclipper/wiki/Donations/
Use cases:
- Over 1500 schools in the UK uses Javascript Clipper in Digimap for Schools service. Digimap for Schools is an online mapping service for use by teachers and pupils. Read more: https://mobilegeo.wordpress.com/ and http://digimapforschools.edina.ac.uk/cosmo-free/osmapper
Features
- Line and polygon clipping - intersection, union, difference & xor
- Line and polygon offsetting with 3 types of joining - miter, square and round
- Polygons can be of any shape, including self-intersecting polygons
- Minkowski Addition and Minkowski Difference functions included
- The library is written in Javascript
- Comprehensive documentation
- Demos use inline SVG and Canvas libraries
- The library is significantly faster than commercial alternatives
- Uses Tom Wu's fast big integer library
- UMD support
Categories
Algorithms, Graphics