2D Geometry and Polygon Operations in JavaScript
These five libraries handle geometric calculations in JavaScript, but they serve different purposes within the graphics and mapping ecosystem. clipper-lib and polygon-clipping focus on boolean operations like union and intersection. d3-polygon provides basic 2D math such as area and centroids for visualization. earcut specializes in high-performance triangulation for rendering. turf offers a comprehensive suite of geospatial analysis tools based on the GeoJSON standard. Choosing the right one depends on whether you need raw speed, geospatial compliance, or specific mathematical operations.
Npm Package Weekly Downloads Trend
Github Stars Ranking
Stat Detail
2D Geometry and Polygon Operations in JavaScript
When building mapping tools, data visualizations, or graphics engines, you will inevitably need to process polygon data. The JavaScript ecosystem offers several options, but they solve different problems. clipper-lib, d3-polygon, earcut, polygon-clipping, and turf all handle geometry, but their input formats, core capabilities, and output structures vary significantly. Let's break down how they handle common engineering tasks.
🗂️ Defining Polygon Data: Input Formats
How you feed data into these libraries dictates how much preprocessing you must do. Some expect raw numbers, while others demand strict GeoJSON structures.
clipper-lib requires integer coordinates for precision.
- You must scale your floating-point coordinates manually.
- Paths are arrays of
{ X, Y }objects.
// clipper-lib: Scaled integer coordinates
const scale = 1000000;
const subject = [{ X: 100 * scale, Y: 100 * scale }, { X: 200 * scale, Y: 100 * scale }];
d3-polygon accepts simple arrays of numbers.
- No scaling needed.
- Uses
[x, y]tuples directly.
// d3-polygon: Raw coordinate arrays
const polygon = [[100, 100], [200, 100], [150, 200]];
earcut expects a flat array of vertices.
- You pass all coordinates in one long list.
- Holes are defined by separate index arrays.
// earcut: Flat vertex array
const vertices = [100, 100, 200, 100, 150, 200];
const holes = [];
const dimensions = 2;
polygon-clipping uses standard coordinate nests.
- Accepts arrays of
[x, y]pairs. - Supports multi-polygons naturally.
// polygon-clipping: Nested coordinate arrays
const polygon = [[[100, 100], [200, 100], [150, 200]]];
turf requires full GeoJSON Features.
- You must wrap coordinates in a Feature object.
- Enforces strict geospatial standards.
// turf: GeoJSON Feature
const polygon = {
type: "Feature",
geometry: {
type: "Polygon",
coordinates: [[[100, 100], [200, 100], [150, 200]]]
}
};
⚙️ Executing Primary Operations
Each library shines in a specific area. Some focus on boolean logic, others on rendering prep or basic math.
clipper-lib excels at boolean clipping.
- Use
Clipperclass for union, intersect, or difference. - Requires setting
ClipTypeandPolyFillType.
// clipper-lib: Boolean Union
const clipper = new ClipperLib.Clipper();
clipper.AddPath(subject, ClipperLib.PolyType.ptSubject, true);
clipper.AddPath(clip, ClipperLib.PolyType.ptClip, true);
const solution = new ClipperLib.Paths();
clipper.Execute(ClipperLib.ClipType.ctUnion, solution);
d3-polygon focuses on basic measurements.
- Calculate area or centroid directly.
- No boolean operations available.
// d3-polygon: Calculate Area
import { polygonArea } from "d3-polygon";
const area = polygonArea(polygon);
earcut is built for triangulation.
- Converts polygons into triangle indices.
- Essential for WebGL rendering.
// earcut: Triangulate
import earcut from "earcut";
const triangles = earcut(vertices, holes, dimensions);
// Returns indices like [0, 1, 2, 0, 2, 3...]
polygon-clipping handles boolean logic in pure JS.
- Functions like
unionorintersectionare top-level. - Returns coordinates ready for GeoJSON.
// polygon-clipping: Boolean Union
import pc from "polygon-clipping";
const result = await pc.union(subjectPolygon, clipPolygon);
turf provides geospatial boolean ops.
- Uses
union,intersect,difference. - Returns full GeoJSON Features.
// turf: Boolean Union
import { union } from "@turf/turf";
const result = union(poly1, poly2);
📦 Processing Results: Output Structures
What you get back determines how much post-processing is needed before rendering or saving.
clipper-lib returns scaled paths.
- You must divide coordinates by your scale factor.
- Output is an array of
{ X, Y }objects.
// clipper-lib: Deserialize results
const realPath = solution.map(p => ({
x: p.X / scale,
y: p.Y / scale
}));
d3-polygon returns single numbers or booleans.
- Area is a number.
polygonContainsreturns true or false.
// d3-polygon: Check containment
import { polygonContains } from "d3-polygon";
const isInside = polygonContains(polygon, [150, 150]);
earcut returns a flat index list.
- Indices reference the original vertex array.
- You must feed this directly to a buffer.
// earcut: Use indices for rendering
const indices = new Uint16Array(triangles);
// Upload to WebGL index buffer
polygon-clipping returns coordinate nests.
- Output matches input structure.
- Easy to convert to GeoJSON manually.
// polygon-clipping: Result format
// result is [[[x, y], [x, y]...]]
const geoJSON = {
type: "Polygon",
coordinates: result
};
turf returns GeoJSON Features.
- Ready to save or send to an API.
- Includes properties if preserved.
// turf: Result format
// result is a GeoJSON Feature
console.log(result.geometry.type); // "Polygon"
🌐 Real-World Scenarios
Scenario 1: Interactive Map Drawing
You are building a tool where users draw zones that merge together.
- ✅ Best choice:
polygon-clippingorturf - Why? You need boolean unions on geographic coordinates.
turfis better if you need map projections.
// turf: Merging zones
const merged = turf.union(zone1, zone2);
Scenario 2: High-Performance Vector Tiles
You need to render thousands of polygons in WebGL.
- ✅ Best choice:
earcut - Why? You need triangle indices for the GPU. Nothing else does this as fast.
// earcut: Preparing for GPU
const indices = earcut(vertices);
Scenario 3: Data Visualization Dashboard
You are showing chart areas and need to calculate centroids for labels.
- ✅ Best choice:
d3-polygon - Why? Lightweight and fits into D3 scales and axes.
// d3-polygon: Label placement
const center = d3.polygonCentroid(polygon);
Scenario 4: CAD-like Precision Cutting
You are building a laser cutter interface requiring exact boolean differences.
- ✅ Best choice:
clipper-lib - Why? Integer scaling prevents floating-point errors during complex cuts.
// clipper-lib: Precision difference
clipper.Execute(ClipperLib.ClipType.ctDifference, solution);
📊 Summary: Capability Matrix
| Feature | clipper-lib | d3-polygon | earcut | polygon-clipping | turf |
|---|---|---|---|---|---|
| Boolean Ops | ✅ Yes | ❌ No | ❌ No | ✅ Yes | ✅ Yes |
| Triangulation | ❌ No | ❌ No | ✅ Yes | ❌ No | ❌ No |
| Input Format | Scaled Objects | [x, y] Arrays | Flat Vertices | [x, y] Nests | GeoJSON |
| Precision | High (Integers) | Standard (Float) | Standard (Float) | Standard (Float) | Standard (Float) |
| GeoJSON Ready | ❌ No | ❌ No | ❌ No | ⚠️ Close | ✅ Yes |
💡 The Big Picture
clipper-lib is the heavy-duty engine 🏗️ for when precision matters most. It requires more setup but handles complex boolean logic without floating-point errors.
d3-polygon is the lightweight utility 🔧 for visualization tasks. It solves basic math problems quickly without pulling in heavy dependencies.
earcut is the renderer's friend 🎨 for turning shapes into triangles. It is the standard for WebGL and map tiles.
polygon-clipping is the balanced choice ⚖️ for boolean ops in pure JavaScript. It avoids the scaling hassle of clipper-lib while staying focused.
turf is the geospatial standard 🌍 for anything involving maps. It brings a full suite of analysis tools but comes with a larger bundle size.
Final Thought: Do not try to force one library to do another's job. Use earcut for rendering, turf for maps, and clipper-lib for precision engineering. Mixing them often leads to unnecessary data conversion and performance loss.
How to Choose: clipper-lib vs d3-polygon vs earcut vs polygon-clipping vs turf
- clipper-lib:
Choose
clipper-libwhen you need robust boolean operations on raw polygon paths and require high precision through integer scaling. It is a proven port of a C++ library, making it ideal for CAD-like applications or complex clipping tasks where floating-point errors are unacceptable. However, it requires manual coordinate scaling and has a steeper learning curve than pure JavaScript alternatives. - d3-polygon:
Choose
d3-polygonif you are already using the D3 ecosystem for data visualization and need lightweight helpers for area, centroid, or convex hull calculations. It works directly with simple coordinate arrays and integrates seamlessly with SVG rendering pipelines. Avoid it for complex boolean logic or geospatial tasks, as it lacks support for those operations. - earcut:
Choose
earcutwhen your primary goal is triangulating polygons for WebGL rendering or map vector tiles. It is extremely fast and designed specifically to convert polygon vertices into triangle indices. Do not use it for boolean operations or geometric measurements, as it does not support those features. - polygon-clipping:
Choose
polygon-clippingfor boolean operations when you want a pure JavaScript solution without native dependencies or coordinate scaling. It accepts standard coordinate arrays and returns GeoJSON-like structures, making it easier to integrate thanclipper-lib. Be aware that development activity is slower compared to larger ecosystems like Turf. - turf:
Choose
turfwhen working with geospatial data that requires GeoJSON compliance and a wide range of analysis tools beyond just polygons. It handles projections, units, and complex spatial queries out of the box. It is heavier than specialized libraries, so avoid it for simple 2D canvas tasks where performance and bundle size are critical.
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