manifold-rust 0.9.1

Pure Rust port of the Manifold 3D geometry library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164

# manifold-rust


[![crates.io](https://img.shields.io/crates/v/manifold-rust.svg)](https://crates.io/crates/manifold-rust)
[![docs.rs](https://docs.rs/manifold-rust/badge.svg)](https://docs.rs/manifold-rust)
[![license](https://img.shields.io/crates/l/manifold-rust.svg)](https://github.com/larsbrubaker/manifold-rust/blob/main/LICENSE)

[![Demo](README_HERO.png)](https://larsbrubaker.github.io/manifold-rust/)

## Support the Project


<a href="https://buymeacoffee.com/larsbrubaker"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50" width="210"></a>

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](https://buymeacoffee.com/larsbrubaker) — every coffee helps.
- **Star the repo:** Costs nothing and helps others find the project.
- **Report issues:** [Open an issue](https://github.com/larsbrubaker/manifold-rust/issues) for bugs or feature ideas.
- **Contribute:** PRs welcome — open an issue first to discuss larger changes.

Pure Rust port of [Manifold](https://github.com/elalish/manifold) — a geometry library for 3D boolean operations on triangle meshes.

> Part of the [rust-apps](https://github.com/larsbrubaker/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](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](https://www.matterhackers.com) 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](https://crates.io/crates/manifold-rust):

```bash
cargo add manifold-rust
```

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

## Usage


```rust
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):

```toml
[dependencies]
manifold-rust = { version = "0.9", 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


```bash
cargo build
cargo test
```

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

```bash
git submodule update --init --recursive
```

Build and compare against the C++ reference with:

```powershell
./validate-reference.ps1
```

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

```powershell
./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:
```bash
cd demo
bun run build:wasm
bun run dev
```

## Architecture


The port follows the C++ module structure:

| Rust module | C++ source | Description |
|-------------|-----------|-------------|
| `vec` / `linalg` | `linalg.h`, `vec.h` | Vector math, linear algebra |
| `polygon` | `polygon.cpp` | 2D polygon triangulation |
| `impl` | `impl.cpp`, `impl.h` | Core mesh data structure |
| `constructors` | `constructors.cpp` | Primitive mesh constructors |
| `boolean3` | `boolean3.cpp` | 3D boolean operations |
| `boolean_result` | `boolean_result.cpp` | Boolean output assembly |
| `csg_tree` | `csg_tree.cpp` | CSG tree evaluation |
| `edge_op` | `edge_op.cpp` | Edge manipulation |
| `face_op` | `face_op.cpp` | Face manipulation |
| `smoothing` | `smoothing.cpp` | Smooth normals and subdivision |
| `subdivision` | `subdivision.cpp` | Mesh subdivision |
| `properties` | `properties.cpp` | Mesh properties |
| `sdf` | `sdf.cpp` | SDF-based mesh generation |
| `quickhull` | `quickhull.cpp` | Convex hull |
| `minkowski` | `minkowski.cpp` | Minkowski operations |
| `cross_section` | `cross_section/` | 2D cross section |

## License


Apache-2.0 — matching the original Manifold library.

## Credits


- **[Emmett Lalish](https://github.com/elalish)** — Author of the original Manifold library.
- **[Lars Brubaker](https://github.com/larsbrubaker)** — Port author.
- **[MatterHackers](https://www.matterhackers.com)** — Sponsor.