manifold-rust

Support the Project

manifold-rust is open-source and free to use, maintained in spare time as a labor of love. Friends James Smith and Dan Ruskin help out from time to time too.

If you find it useful, here are a few ways to help keep development going:

• Donations: Buy Me a Coffee — every coffee helps.
• Star the repo: Costs nothing and helps others find the project.
• Report issues: Open an issue for bugs or feature ideas.
• Contribute: PRs welcome — open an issue first to discuss larger changes.

Pure Rust port of Manifold — a geometry library for 3D boolean operations on triangle meshes.

Part of the rust-apps suite — a collection of Rust graphics and geometry libraries by Lars Brubaker.

Status: Port complete. All 18 phases of the C++ engine (v3.5.0) are implemented and every C++ test is ported or covered — 520 tests passing, 0 failing (the handful of #[ignore]d tests are debug-build-speed only and pass in release). Heavy boolean/CSG workloads run at parity with the sequential C++ build, and the optional parallel feature roughly doubles them. See PORTING_PLAN.md for the full record.

What is Manifold?

Manifold is a high-performance C++ library for 3D solid modeling. It supports:

• Boolean operations (union, intersection, difference) on triangle meshes
• Mesh constructors (sphere, cube, cylinder, extrude, revolve)
• Cross-section (2D polygon) operations
• Smooth subdivision and SDF-based mesh generation
• Convex hull
• Minkowski sum/difference

This Rust port targets exact numerical match with the C++ implementation — same algorithms, same floating-point results, same triangle topology. Exactness is validated by instrumented, boolean-by-boolean trace comparison against a locally built C++ reference (see validate-reference.ps1), down to the tie-breaking order of symbolic-perturbation predicates.

Why

MatterHackers uses 3D mesh boolean operations extensively in production for 3D printing workflows. A pure Rust implementation avoids FFI overhead and integrates cleanly with Rust tooling including WASM compilation.

Installation

Available on crates.io:

cargo add manifold-rust

API documentation: https://docs.rs/manifold-rust

Usage

use manifold_rust::manifold::Manifold;
use manifold_rust::linalg::Vec3;

// Constructors
let cube = Manifold::cube(Vec3::new(1.0, 1.0, 1.0), true);
let sphere = Manifold::sphere(0.6, 32);

// Guaranteed-manifold booleans (also available as + - operators)
let difference = cube.difference(&sphere);
assert_eq!(difference.status(), manifold_rust::types::Error::NoError);

// Measure
println!("volume = {}", difference.volume());
println!("area   = {}", difference.surface_area());
println!("genus  = {}", difference.genus());

// Mesh I/O via MeshGL
let mesh = difference.get_mesh_gl(0);
let round_tripped = Manifold::from_mesh_gl(&mesh);

Enable parallel execution (results stay bit-identical to the sequential build — only determinism-preserving sites are parallelized):

[dependencies]
manifold-rust = { version = "0.10", features = ["parallel"] }

Demo

An interactive WASM demo is live at https://larsbrubaker.github.io/manifold-rust/ — booleans, extrude/revolve with twist, convex hull, subdivision, a Menger sponge, and more, all running the Rust engine compiled to WebAssembly.

Building

cargo build
cargo test

Restore the upstream C++ reference before doing exact-match validation:

git submodule update --init --recursive

Build and compare against the C++ reference with:

./validate-reference.ps1

You can also run a narrower validation slice by phase, for example:

./validate-reference.ps1 -Phase phase8

This configures and builds cpp-reference/manifold, runs the matching C++ reference tests, and then runs the corresponding Rust tests for the selected phase.

For the WASM demo:

cd demo
bun run build:wasm
bun run dev

Performance

The port is benchmarked against the C++ reference using Rust ports of the upstream perf drivers, printing identical output lines so runs diff cleanly:

• cargo run --release --example perf_test — a sphere-minus-sphere boolean at doubling tessellation levels (extras/perf_test.cpp)
• cargo run --release --example large_scene_test -- <n> — union of an n×n×n grid of unit spheres through the CSG tree (extras/large_scene_test.cpp)

Representative timings, best of several runs on the same machine (Windows 10, i7-7660U 2C/4T, 8 GB RAM; both sides sequential: C++ built Release with MANIFOLD_PAR=OFF, Rust default features, MSVC 19.44 / rustc via fat LTO):

Both implementations produce identical triangle counts on every benchmark (and the test suite validates bit-exact geometry). The largest perf_test round (8.4 M input tris) needs several GB of working set and is dominated by paging on the 8 GB test machine, so its timings are not comparable there. Peak memory is within ~10 % of C++ (1.47 GB vs 1.34 GB peak working set on the 2 M-tri round) after slimming the cached collider to the C++ storage layout and dropping assembly intermediates at the same points the C++ clears them; use cargo run --release --example mem_profile with MANIFOLD_TIMING=1 to see per-stage heap use.

Per-stage timing is available on both sides for gap hunting: set the MANIFOLD_TIMING environment variable for the Rust build (stage boundaries match the C++ MANIFOLD_TIMING build's output) — this is how the cached-face- collider optimization was found, which brought the intersection stage from 2.7× slower than C++ to faster than C++.

An optional parallel cargo feature parallelizes determinism-preserving sites with rayon (results stay bit-identical to the sequential build); see PORTING_PLAN.md for which stages it covers.

Architecture

The port follows the C++ module structure:

License

Apache-2.0 — matching the original Manifold library.

Credits

• Emmett Lalish — Author of the original Manifold library.
• Lars Brubaker — Port author.
• MatterHackers — Sponsor.