qhull-wasm

Qhull (the reentrant libqhull_r) compiled to WebAssembly with a small JavaScript API for computing convex hulls and Delaunay triangulations from JS, in Node or the browser.

Install

npm install qhull-wasm

The published package ships the prebuilt dist/qhull.mjs + dist/qhull.wasm, so no native toolchain is needed to use it.

Layout

qhull/             upstream qhull source (git submodule, pinned to v8.1-alpha6)
src/qhull_wasm.c   thin C wrapper over libqhull_r
src/qhull.mjs      JS API wrapping the WASM module
src/qhull.d.ts     TypeScript declarations
build.sh           emcc build script
dist/              build output: qhull.mjs + qhull.wasm (committed; published)
test.mjs           sanity tests

Build from source

Only needed to rebuild the WASM (the prebuilt dist/ is committed). Requires the Emscripten SDK (emsdk); the build script sources ~/emsdk/emsdk_env.sh automatically if emcc is not already on PATH.

git submodule update --init   # fetch the pinned qhull source
npm run build                 # -> dist/qhull.mjs (~63 KB) + dist/qhull.wasm (~380 KB)

Usage

import { loadQhull } from "qhull-wasm";

const qhull = await loadQhull();   // loads the WASM module once

// Convex hull of a 3D point set. Points may be [[x,y,z], ...] or a flat
// Float64Array of length N*dim.
const { dim, facets } = qhull.convexHull(points, 3);
// facets: array of facets; each is an array of input point indices.
// With the default `triangulate: true`, every facet is a simplex
// (3 indices in 3D, 2 in 2D, ...).

// Delaunay triangulation (2D here -> triangles as point-index triples).
const { facets: simplices } = qhull.delaunay(points2d, 2);

API

• loadQhull(): Promise<Qhull> — instantiate the module (call once, reuse).
• qhull.convexHull(points, dim, opts?) — returns { dim, facets }.
  • opts.triangulate (default true) adds qhull's Qt.
  • opts.options — full qhull option string, overrides the default (must begin with qhull), e.g. "qhull QJ".
• qhull.delaunay(points, dim, opts?) — returns { dim, facets }, each facet a simplex of input point indices.
  • Default options qhull d Qt Qbb Qc Qz mirror qdelaunay; Qz adds a point-at-infinity so cocircular/cospherical inputs (e.g. a perfect square) are handled exactly.
  • opts.options overrides the default.

points accepts an array of tuples (number[][]), a flat row-major numeric array, or a Float64Array of length N*dim.

Test

npm test   # node test.mjs

License

The wrapper (everything except qhull/) is MIT licensed — see LICENSE. Copyright (c) 2026 Flatiron Institute.

This package bundles Qhull (compiled, unmodified, into dist/qhull.wasm), which is distributed under the Qhull license — see LICENSE-QHULL.txt. Qhull is Copyright (c) 1993-2020 C.B. Barber and The Geometry Center; its source is available at www.qhull.org and github.com/qhull/qhull (pinned here to v8.1-alpha6). The combined SPDX expression is (MIT AND Qhull).

Notes

• The wrapper returns facets as original input point indices, so you can map them back to your own coordinates.
• On precision errors (e.g. cocircular Delaunay input without Qz/QJ), qhull prints a diagnostic to stderr and the call throws with the qhull exit code.
• Extending the wrapper (Voronoi vertices, halfspace intersection, facet normals) is a matter of reading more out of the qhT struct in src/qhull_wasm.c — see qhull/src/user_eg/user_eg_r.c for the patterns.