Bezier Boolean

Boolean operations on cubic Bezier loops — unite, intersect, subtract, exclude, and divide.

Built for font and vector editing workflows. Zero dependencies, plain ESM, ~5 kB gzipped.

Install

npm install bezier-boolean

Quick Start

import { combine } from 'bezier-boolean';

// Each loop is an array of cubic Bezier curves: [p1, cp1, cp2, p2]
// Use `false` for cp1/cp2 to represent a straight line segment.
const square = [
	[{ x: 0, y: 0 }, false, false, { x: 100, y: 0 }],
	[{ x: 100, y: 0 }, false, false, { x: 100, y: 100 }],
	[{ x: 100, y: 100 }, false, false, { x: 0, y: 100 }],
	[{ x: 0, y: 100 }, false, false, { x: 0, y: 0 }],
];

const offsetSquare = [
	[{ x: 50, y: 50 }, false, false, { x: 150, y: 50 }],
	[{ x: 150, y: 50 }, false, false, { x: 150, y: 150 }],
	[{ x: 150, y: 150 }, false, false, { x: 50, y: 150 }],
	[{ x: 50, y: 150 }, false, false, { x: 50, y: 50 }],
];

const result = combine([square, offsetSquare], 'unite');
// result is an array of loops representing the union

API

combine(collection, operation, options?)

Performs a boolean operation on a collection of Bezier loops.

Parameters:

| Name | Type | Description | | ----------------- | -------------- | ----------------------------------------------------------------------- | | collection | BezierLoop[] | Array of loops to operate on | | operation | string | 'unite' | 'intersect' | 'subtract' | 'exclude' | 'divide' | | options.epsilon | number | Numerical tolerance (default 1e-9) |

Returns: BezierLoop[] — the result loops.

Operations

| Operation | Description | | ----------- | ------------------------------------------------------------- | | unite | Union of all filled regions | | intersect | Only regions where all loops overlap | | subtract | First loop minus all subsequent loops | | exclude | Only non-overlapping regions (XOR) | | divide | All paths slice each other; every closed fragment is returned |

Data Structures

A BezierLoop is an array of BezierCurve segments that form a closed path. The end point of each curve must equal the start point of the next, and the last curve must connect back to the first.

A BezierCurve is a 4-element array: [p1, cp1, cp2, p2]

• p1 — start point { x, y }
• cp1 — first control point { x, y }, or false for a line
• cp2 — second control point { x, y }, or false for a line
• p2 — end point { x, y }

When both control points are false, the segment is a straight line.

Winding direction matters: CW loops define filled regions, CCW loops define holes (or vise-versa)(non-zero winding rule).

Development

git clone https://github.com/mattlag/bezier-boolean.git
cd bezier-boolean
npm install

Build

npm run build        # produces dist/bezier-boolean.js

Test

npm test             # run unit & integration tests (vitest)
npm run test:watch   # watch mode
npm run test:visual  # open visual test suite in browser (vite dev server)

Project Layout

src/              Source modules
  math/           Point, curve, intersection, winding math
  data/           Input validation and normalization
  algorithm/      Split, graph, classify, select, reconstruct
test/             Tests and fixtures
  visual/         Browser-based visual test suite
agent-files/      Design specs (data structures, API, algorithms, etc.)

Detailed design documents are in agent-files/ — useful if you want to understand the algorithm internals.

License

GPL-3.0