manifold

About Manifold

C++ Documentation | ManifoldCAD User Guide | JS/TS/WASM API | Algorithm Documentation | Blog Posts | Web Examples

Manifold is a geometry library dedicated to creating and operating on manifold triangle meshes. A manifold mesh is a mesh that represents a solid object, and so is very important in manufacturing, CAD, structural analysis, etc. Manifold also supports arbitrary vertex properties and enables mapping of materials for rendering use-cases. Our primary goal is reliability: guaranteed manifold output without caveats or edge cases. Our secondary goal is performance: efficient algorithms that make extensive use of parallelization, or pipelining when only a single thread is available.

Users

Here is an incomplete list of our users, whose integrations may be anywhere from in-progress to released. Please feel free to send a PR to update this list with your own project - it's quite difficult for us to keep track.

Bindings & Packages

Manifold has bindings to many other languages, some maintained in this repository, and others elsewhere. It can also be built in C++ via vcpkg. There is also a native Rust port, manifold-rust, which passes Manifold's full test suite with identical results and has no C++ dependency — from a user's perspective it works like a binding.

Frontend Sandboxes

ManifoldCAD.org

If you like OpenSCAD / JSCAD, you might also like ManifoldCAD - our own solid modelling web app where you script in JS/TS. This uses our npm package, manifold-3d, built via WASM. It's not quite as fast as our raw C++, but it's hard to beat for interoperability.

Python Colab Example

If you prefer Python to JS/TS, make your own copy of the notebook. It demonstrates interop between our manifold3d PyPI library and the popular trimesh library, including showing the interactive model right in the notebook and saving 3D model output.

Manifold Library

This library is fast with guaranteed manifold output. As such you need manifold meshes as input, which this library can create using constructors inspired by the OpenSCAD API, as well as a level set function for evaluating signed-distance functions (SDF) that improves significantly over Marching Cubes. You can also pass in your own mesh data, but you'll get an error status if the imported mesh isn't manifold. We provide a Merge function to fix slightly non-manifold meshes, but in general you may need one of the automated repair tools that exist mostly for 3D printing.

The most significant contribution here is a guaranteed-manifold mesh Boolean algorithm, which I believe is the first of its kind. If you know of another, please open a discussion - a mesh Boolean algorithm robust to edge cases has been an open problem for many years. Likewise, if the Boolean here ever fails you, please submit an issue! This Boolean forms the basis of a CAD kernel, as it allows simple shapes to be combined into more complex ones.

Manifold has full support for arbitrary vertex properties, and also has IDs that make it easy to keep track of materials and what surfaces belong to what input objects or faces. See our web example for a simple demonstration of combining objects with unique textures.

Also included are a novel and powerful suite of refining functions for smooth mesh interpolation. They handle smoothing both triangles and quads, as well as keeping polygonal faces flat. You can easily create sharp or small-radius edges where desired, or even drive the curvature by normal vectors.

To aid in speed, this library makes extensive use of parallelization through TBB, if enabled. Not everything is so parallelizable, for instance a polygon triangulation algorithm is included which is serial. Even if compiled with parallel backend, the code will still fall back to the serial version of the algorithms if the problem size is small. The WASM build is serial-only for now, but still fast.

Look in the samples directory for examples of how to use this library to make interesting 3D models. You may notice that some of these examples bear a certain resemblance to my OpenSCAD designs on Thingiverse, which is no accident. Much as I love OpenSCAD, my library is dramatically faster and the code is more flexible.

Dependencies

Manifold no longer has any required dependencies! However, we do have several optional dependencies, of which the first two are strongly encouraged:

3D Formats

Please avoid saving to STL files! They are lossy and inefficient - when saving a manifold mesh to STL there is no guarantee that the re-imported mesh will still be manifold, as the topology is lost. Please consider using 3MF instead, as this format was designed from the beginning for manifold meshes representing solid objects.

If you use vertex properties for things like interpolated normals or texture UV coordinates, glTF is recommended, specifically using the EXT_mesh_manifold extension. This allows for the lossless and efficient transmission of manifoldness even with property boundaries. Try our make-manifold page to add this extension to your existing glTF/GLB models.

Manifold provides high precision OBJ file IO, but it is limited in functionality and is primarily to aid in testing. If you are using our npm module, we have a much more capable gltf-io.ts you can use instead. For other languages we strongly recommend using existing packages that focus on 3D file I/O, e.g. trimesh for Python, particularly when using vertex properties or materials. Example for integrating with Assimp is in extras/meshIO.cpp, which is used by files such as extras/convert_file.cpp.

Building

Only CMake, a C++ compiler, and Python are required to be installed and set up to build this library (it has been tested with GCC, LLVM, MSVC). However, a variety of optional dependencies can bring in more functionality, see below.

Build and test (Ubuntu or similar):

git clone --recurse-submodules https://github.com/elalish/manifold.git
cd manifold
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON .. && make
make test

CMake flags (usage e.g. -DMANIFOLD_DEBUG=ON):

• MANIFOLD_JSBIND=[OFF, <ON>]: Build js binding (when using the emscripten toolchain).
• MANIFOLD_CBIND=[<OFF>, ON]: Build C FFI binding.
• MANIFOLD_PYBIND=[OFF, <ON>]: Build python binding, requires nanobind.
• MANIFOLD_PAR=[<OFF>, ON]: Enables multi-thread parallelization, requires tbb.
• MANIFOLD_DEBUG=[<OFF>, ON]: Enables exceptions, timing, verbosity, OBJ test dumps. Has almost no effect on its