{"author":null,"author_email":"Emmett Lalish ","bugtrack_url":null,"classifiers":["Development Status :: 5 - Production/Stable","License :: OSI Approved :: Apache Software License","Operating System :: OS Independent","Programming Language :: C++","Topic :: Multimedia :: Graphics :: 3D Modeling"],"description":"# About Manifold\n\n[![codecov](https://codecov.io/github/elalish/manifold/branch/master/graph/badge.svg?token=IIA8G5HVS7)](https://codecov.io/github/elalish/manifold)\n[![PyPI version](https://badge.fury.io/py/manifold3d.svg)](https://badge.fury.io/py/manifold3d)\n[![npm version](https://badge.fury.io/js/manifold-3d.svg)](https://badge.fury.io/js/manifold-3d)\n[![twitter](https://img.shields.io/twitter/follow/manifoldcad?style=social&logo=twitter)](https://twitter.com/intent/follow?screen_name=manifoldcad)\n\n[**C++ Documentation**](https://manifoldcad.org/docs/html/classmanifold_1_1_manifold.html) | [**TS Documentation**](https://manifoldcad.org/jsdocs) | [**Algorithm Documentation**](https://github.com/elalish/manifold/wiki/Manifold-Library) | [**Blog Posts**](https://elalish.blogspot.com/search/label/Manifold) | [**Web Examples**](https://manifoldcad.org/model-viewer.html)\n\n[Manifold](https://github.com/elalish/manifold) is a geometry library dedicated to creating and operating on manifold triangle meshes. A [manifold mesh](https://github.com/elalish/manifold/wiki/Manifold-Library#manifoldness) 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.\n\n## Users\n\nHere 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.\n\n| | | |\n| --- | --- | --- |\n| [OpenSCAD](https://openscad.org/) | [Blender](https://www.blender.org/) | [IFCjs](https://ifcjs.github.io/info/) |\n| [Nomad Sculpt](https://apps.apple.com/us/app/id1519508653?mt=8&platform=ipad) | [Grid.Space](https://grid.space/) | [badcad](https://github.com/wrongbad/badcad) |\n| [Godot Engine](https://godotengine.org/) | [OCADml](https://github.com/OCADml/OManifold) | [Flitter](https://flitter.readthedocs.io/en/latest/) |\n| [BRL-CAD](https://brlcad.org/) | [PolygonJS](https://polygonjs.com/) | [Spherene](https://spherene.ch/) |\n| [Babylon.js](https://doc.babylonjs.com/features/featuresDeepDive/mesh/mergeMeshes#merging-meshes-with-constructive-solid-geometry) | [trimesh](https://trimesh.org/) | [Gypsum](https://github.com/playkostudios/gypsum) |\n| [Valence 3D](https://apps.apple.com/us/app/valence-3d/id6450967410?mt=8&platform=ipad) | [bitbybit.dev](https://bitbybit.dev) | [PythonOpenSCAD](https://github.com/owebeeone/pythonopenscad) |\n| [Conversation](https://james-bern.github.io/conversation.html) | [AnchorSCAD](https://github.com/owebeeone/anchorscad-core) | [Dactyl Web Configurator](https://github.com/rianadon/dactyl-configurator) |\n\n### Bindings & Packages\n\nManifold has bindings to many other languages, some maintained in this repository, and others elsewhere. It can also be built in C++ via [vcpkg](https://github.com/microsoft/vcpkg.git).\n\n| Language | Packager | Name | Maintenance |\n| --- | --- | --- | --- |\n| C | N/A | N/A | internal |\n| C++ | vcpkg | [manifold](https://github.com/microsoft/vcpkg/tree/master/ports/manifold) | external |\n| TS/JS | npm | [manifold-3d](https://www.npmjs.com/package/manifold-3d) | internal |\n| Python | PyPI | [manifold3d](https://pypi.org/project/manifold3d/) | internal |\n| Java | N/A | [manifold](https://github.com/SovereignShop/manifold) | external |\n| Clojure | N/A | [clj-manifold3d](https://github.com/SovereignShop/clj-manifold3d) | external |\n| C# | NuGet | [ManifoldNET](https://www.nuget.org/packages/ManifoldNET) | external |\n| Julia | Packages | [ManifoldBindings.jl](https://juliapackages.com/p/manifoldbindings) | external |\n| OCaml | N/A | [OManifold](https://ocadml.github.io/OManifold/OManifold/index.html) | external |\n| Swift | SPM | [Manifold-Swift](https://github.com/tomasf/manifold-swift) | external |\n\n## Frontend Sandboxes\n\n### [ManifoldCAD.org](https://manifoldcad.org)\n\nIf 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](https://www.npmjs.com/package/manifold-3d), built via WASM. It's not quite as fast as our raw C++, but it's hard to beat for interoperability.\n\n### [Python Colab Example](https://colab.research.google.com/drive/1VxrFYHPSHZgUbl9TeWzCeovlpXrPQ5J5?usp=sharing)\n\nIf you prefer Python to JS/TS, make your own copy of the example notebook above. It demonstrates interop between our [`manifold3d`](https://pypi.org/project/manifold3d/) PyPI library and the popular [`trimesh`](https://pypi.org/project/trimesh/) library, including showing the interactive model right in the notebook and saving 3D model output.\n\n![A metallic Menger sponge](https://manifoldcad.org/samples/models/mengerSponge192.png \"A metallic Menger sponge\")\n\n## Manifold Library\n\nThis 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`](https://manifoldcad.org/docs/html/structmanifold_1_1_mesh_g_l_p.html) 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.\n\nThe most significant contribution here is a guaranteed-manifold [mesh Boolean](https://github.com/elalish/manifold/wiki/Manifold-Library#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.\n\nManifold 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](https://manifoldcad.org/model-viewer.html) for a simple demonstration of combining objects with unique textures.\n\nAlso 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.\n\nTo aid in speed, this library makes extensive use of parallelization through TBB, if enabled. Not everything is so parallelizable, for instance a [polygon triangulation](https://github.com/elalish/manifold/wiki/Manifold-Library#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.\n\nLook in the [samples](https://github.com/elalish/manifold/tree/master/samples) directory for examples of how to use this library to make interesting 3D models. You may notice that some of these examples bare a certain resemblance to my OpenSCAD designs on [Thingiverse](https://www.thingiverse.com/emmett), which is no accident. Much as I love OpenSCAD, my library is dramatically faster and the code is more flexible.\n\n### Dependencies\n\nManifold no longer has **any** required dependencies! However, we do have several optional dependencies, of which the first two are strongly encouraged:\n| Name | CMake Flag | Provides |\n| --- | --- | --- |\n| [`TBB`](https://github.com/oneapi-src/oneTBB/) |`MANIFOLD_PAR=ON` | Parallel acceleration |\n| [`Clipper2`](https://github.com/AngusJohnson/Clipper2) | `MANIFOLD_CROSS_SECTION=ON` | 2D: [`CrossSection`](https://manifoldcad.org/docs/html/classmanifold_1_1_cross_section.html) |\n| [`Assimp`](https://github.com/assimp/assimp) | `MANIFOLD_EXPORT=ON` | Basic Mesh I/O |\n| [`Nanobind`](https://github.com/wjakob/nanobind) | `MANIFOLD_PYBIND=ON` | Python bindings |\n| [`Emscripten`](https://github.com/emscripten-core/emscripten) | `MANIFOLD_JSBIND=ON` | JS bindings via WASM |\n| [`GTest`](https://github.com/google/googletest/) | `MANIFOLD_TEST=ON` | Testing framework |\n\n### 3D Formats\n\nPlease 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](https://3mf.io/) instead, as this format was designed from the beginning for manifold meshes representing solid objects. \n\nIf you use vertex properties for things like interpolated normals or texture UV coordinates, [glTF](https://www.khronos.org/Gltf) is recommended, specifically using the [`EXT_mesh_manifold`](https://github.com/KhronosGroup/glTF/blob/main/extensions/2.0/Vendor/EXT_mesh_manifold/README.md) extension. This allows for the lossless and efficient transmission of manifoldness even with property boundaries. Try our [make-manifold](https://manifoldcad.org/make-manifold) page to add this extension to your existing glTF/GLB models. \n\nManifold provides an optional [`MeshIO`](https://manifoldcad.org/docs/html/group___mesh_i_o.html) component based on [Assimp](https://assimp.org/), 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](https://github.com/elalish/manifold/blob/master/bindings/wasm/examples/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](https://trimesh.org/) for Python, particularly when using vertex properties or materials. \n\n## Building\n\nOnly 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.\n\nBuild and test (Ubuntu or similar):\n```\ngit clone --recurse-submodules https://github.com/elalish/manifold.git\ncd manifold\nmkdir build\ncd build\ncmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON .. && make\nmake test\n```\n\nCMake flags (usage e.g. `-DMANIFOLD_DEBUG=ON`):\n- `MANIFOLD_JSBIND=[OFF, ]`: Build js binding (when using the emscripten toolchain).\n- `MANIFOLD_CBIND=[, ON]`: Build C FFI binding.\n- `MANIFOLD_PYBIND=[OFF, ]`: Build python binding, requires `nanobind`.\n- `MANIFOLD_PAR=[, ON]`: Enables multi-thread parallelization, requires `tbb`.\n- `MANIFOLD_CROSS_SECTION=[OFF, ]`: Build CrossSection for 2D support (needed by language bindings), requires `Clipper2`.\n- `MANIFOLD_EXPORT=[, ON]`: Enables `MeshIO` and GLB export of 3D models from the tests, requires `assimp`.\n- `MANIFOLD_DEBUG=[, ON]`: Enables exceptions, timing, verbosity, OBJ test dumps. Has almost no effect on its own, but enables further runtime parameters to dump various outputs.\n- `MANIFOLD_ASSERT=[, ON]`: Enables internal assertions. This incurs around 20% runtime overhead. Requires MANIFOLD_DEBUG to work.\n- `MANIFOLD_TEST=[OFF, ]`: Build unit tests, requires `GTest`.\n- `TRACY_ENABLE=[, ON]`: Enable integration with tracy profiler. \n See profiling section below.\n\nDependency version override:\n- `MANIFOLD_USE_BUILTIN_TBB=[, ON]`: Use builtin version of tbb.\n- `MANIFOLD_USE_BUILTIN_CLIPPER2=[, ON]`: Use builtin version of clipper2.\n- `MANIFOLD_USE_BUILTIN_NANOBIND=[, ON]`: Use builtin version of nanobind.\n\n> Note: These three options can force the build to avoid using the system\n> version of the dependency. This will either use the provided source directory\n> via `FETCHCONTENT_SOURCE_DIR_*` (see below), or fetch the source from GitHub.\n> Note that the dependency will be built as static dependency to avoid dynamic\n> library conflict. When the system package is unavailable, the option will be\n> automatically set to true.\n\nOffline building (with missing dependencies/dependency version override):\n- `MANIFOLD_DOWNLOADS=[OFF, ]`: Automatically download missing dependencies.\n Need to set `FETCHCONTENT_SOURCE_DIR_*` if the dependency `*` is missing.\n- `FETCHCONTENT_SOURCE_DIR_TBB`: path to tbb source (if `MANIFOLD_PAR` is enabled).\n- `FETCHCONTENT_SOURCE_DIR_CLIPPER2`: path to tbb source (if `MANIFOLD_CROSS_SECTION` is enabled).\n- `FETCHCONTENT_SOURCE_DIR_NANOBIND`: path to nanobind source (if `MANIFOLD_PYBIND` is enabled).\n- `FETCHCONTENT_SOURCE_DIR_GOOGLETEST`: path to googletest source (if `MANIFOLD_TEST` is enabled).\n\n> Note: When `FETCHCONTENT_SOURCE_DIR_*` is set, CMake will use the provided\n> source directly without downloading regardless of the value of\n> `MANIFOLD_DOWNLOADS`.\n\nThe build instructions used by our CI are in [manifold.yml](https://github.com/elalish/manifold/blob/master/.github/workflows/manifold.yml), which is a good source to check if something goes wrong and for instructions specific to other platforms, like Windows.\n\n### WASM\n\n> Note: While we support compiling with `MANIFOLD_PAR=ON` in recent emscripten\n> versions, this is not recommended as there can potentially be memory\n> corruption issues.\n\nTo build the JS WASM library, first install NodeJS and set up emscripten:\n\n(on Mac):\n```\nbrew install nodejs\nbrew install emscripten\n```\n(on Linux):\n```\nsudo apt install nodejs\ngit clone https://github.com/emscripten-core/emsdk.git\ncd emsdk\n./emsdk install latest\n./emsdk activate latest\nsource ./emsdk/emsdk_env.sh\n```\nThen build:\n```\ncd manifold\nmkdir buildWASM\ncd buildWASM\nemcmake cmake -DCMAKE_BUILD_TYPE=MinSizeRel .. && emmake make\ncd test\nnode ./manifold_test.js\n```\n\n### Python\n\nThe CMake script will build the python binding `manifold3d` automatically. To\nuse the extension, please add `$BUILD_DIR/bindings/python` to your `PYTHONPATH`, where\n`$BUILD_DIR` is the build directory for CMake. Examples using the python binding\ncan be found in `bindings/python/examples`. To see exported samples, run:\n```\nsudo apt install pkg-config libpython3-dev python3 python3-distutils python3-pip\npip install trimesh pytest\npython3 run_all.py -e\n```\n\nRun the following code in the interpreter for\npython binding documentation:\n\n```\n>>> import manifold3d\n>>> help(manifold3d)\n```\n\nFor more detailed documentation, please refer to the C++ API.\n\n### Windows Shenanigans\n\nWindows users should build with `-DBUILD_SHARED_LIBS=OFF`, as enabling shared\nlibraries in general makes things very complicated.\n\nThe DLL file for manifoldc (C FFI bindings) when built with msvc is in `${CMAKE_BINARY_DIR}/bin/${BUILD_TYPE}/manifoldc.dll`.\nFor example, for the following command, the path relative to the project root directory is `build/bin/Release/manifoldc.dll`.\n```sh\ncmake . -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF -DMANIFOLD_DEBUG=ON -DMANIFOLD_PAR=${{matrix.parallel_backend}} -A x64 -B build\n```\n\n## Contributing\n\nContributions are welcome! A lower barrier contribution is to simply make a PR that adds a test, especially if it repros an issue you've found. Simply name it prepended with DISABLED_, so that it passes the CI. That will be a very strong signal to me to fix your issue. However, if you know how to fix it yourself, then including the fix in your PR would be much appreciated!\n\n### Formatting\n\nThere is a formatting script `format.sh` that automatically formats everything.\nIt requires clang-format, black formatter for python and [gersemi](https://github.com/BlankSpruce/gersemi) for formatting cmake files.\n\nNote that our script can run with clang-format older than 18, but the GitHub\naction check may fail due to slight differences between different versions of\nclang-format. In that case, either update your clang-format version or apply the\npatch from the GitHub action log.\n\n### Profiling\n\nThere is now basic support for the [Tracy profiler](https://github.com/wolfpld/tracy) for our tests.\nTo enable tracing, compile with `-DTRACY_ENABLE=on` cmake option, and run the test with Tracy server running.\nTo enable memory profiling in addition to tracing, compile with `-DTRACY_MEMORY_USAGE=ON` in addition to `-DTRACY_ENABLE=ON`.\n\n## About the author\n\nThis library was started by [Emmett Lalish](https://elalish.blogspot.com/), currently a senior rendering engineer at Wētā FX. This was my 20% project when I was a Google employee, though my day job was maintaining [\\](https://modelviewer.dev/). I was the first employee at a 3D video startup, [Omnivor](https://www.omnivor.io/), and before that I worked on 3D printing at Microsoft, including [3D Builder](https://www.microsoft.com/en-us/p/3d-builder/9wzdncrfj3t6?activetab=pivot%3Aoverviewtab). Originally an aerospace engineer, I started at a small DARPA contractor doing seedling projects, one of which became [Sea Hunter](https://en.wikipedia.org/wiki/Sea_Hunter). I earned my doctorate from the University of Washington in control theory and published some [papers](https://www.researchgate.net/scientific-contributions/75011026_Emmett_Lalish).\n","description_content_type":"text/markdown","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":null,"license":null,"license_expression":null,"license_files":null,"maintainer":null,"maintainer_email":null,"name":"manifold3d","package_url":"https://pypi.org/project/manifold3d/","platform":null,"project_url":"https://pypi.org/project/manifold3d/","project_urls":{"Bug Tracker":"https://github.com/elalish/manifold/issues","Homepage":"https://github.com/elalish/manifold"},"provides_extra":null,"release_url":"https://pypi.org/project/manifold3d/3.1.0/","requires_dist":["numpy; python_version < \"3.12\"","numpy>=1.26.0b1; python_version >= \"3.12\""],"requires_python":">=3.8","summary":"Library for geometric robustness","version":"3.1.0","yanked":false,"yanked_reason":null}

Package search

manifold3d

project_urls

Dependencies

All package metadata

Releases