Metadata-Version: 2.2
Name: wildmeshing
Version: 2.0.0
Summary: Python bindings for WildMeshingToolkit
Author: WildMeshingToolkit
License: MIT License
         
         Copyright (c) 2021 geometryprocessing
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
         
         
         
         ========
         For src/wmtk/utils/Morton.[cpp,h]
         
         BSD 3-Clause License
         
         Copyright (c) 2017, Nico Schertler
         All rights reserved.
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:
         
         * Redistributions of source code must retain the above copyright notice, this
           list of conditions and the following disclaimer.
         
         * Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
         
         * Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
         FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
         
Project-URL: GitHub, https://github.com/wildmeshing/wildmeshing-toolkit/
Requires-Python: >=3.9
Requires-Dist: numpy>=1.23
Provides-Extra: polyfem
Requires-Dist: gmsh; extra == "polyfem"
Requires-Dist: scipy; extra == "polyfem"
Requires-Dist: h5py; extra == "polyfem"
Description-Content-Type: text/markdown

# Wildmeshing Toolkit

[![Build](https://github.com/wildmeshing/wildmeshing-toolkit/actions/workflows/continuous.yml/badge.svg)](https://github.com/wildmeshing/wildmeshing-toolkit/actions/workflows/continuous.yml)
[![Docs](https://github.com/wildmeshing/wildmeshing-toolkit/actions/workflows/docs.yml/badge.svg)](https://wildmeshing.github.io/wildmeshing-toolkit/)

Robust, parallel triangle and tetrahedral mesh generation and editing. Each algorithm is written
as a set of local operations (split, collapse, swap, smooth), the invariants every operation must
keep, and the rules that update attributes. The toolkit schedules the operations in parallel,
checks the invariants, and rolls back any operation that breaks them.

**Documentation, tutorials and examples: https://wildmeshing.github.io/wildmeshing-toolkit/**

[![The Octocat: its input surface, and the tet mesh TetWild makes of it, cut open and colored by element quality](https://wildmeshing.github.io/wildmeshing-toolkit/gallery/assets/tetwild_octocat/poster.png)](https://wildmeshing.github.io/wildmeshing-toolkit/gallery/)

## What is in this repository

| Directory | Contents |
|---|---|
| [`src/wmtk`](https://github.com/wildmeshing/wildmeshing-toolkit/tree/main/src/wmtk) | The core library: triangle and tet mesh connectivity, local operations with rollback, the parallel scheduler, exact and sampled envelopes, rational positions, energies, mesh I/O, operation histories |
| [`components`](https://github.com/wildmeshing/wildmeshing-toolkit/tree/main/components) | The algorithms built on the library, each configured by JSON options checked against its `*_spec.json` |
| [`app`](https://github.com/wildmeshing/wildmeshing-toolkit/tree/main/app) | `wmtk_app`, the command line that runs any component from a JSON file |
| [`python`](https://github.com/wildmeshing/wildmeshing-toolkit/tree/main/python) | The `wildmeshing` Python package: every component, on files or on NumPy arrays |
| [`tests`](https://github.com/wildmeshing/wildmeshing-toolkit/tree/main/tests) | Unit, component and integration tests, in C++ and Python |
| [`docs`](https://github.com/wildmeshing/wildmeshing-toolkit/tree/main/docs) | The documentation site, its tested examples, and design notes |

## Components

| Component | Input → output | What it does |
|---|---|---|
| [`shortest_edge_collapse`](https://wildmeshing.github.io/wildmeshing-toolkit/tutorials/shortest_edge_collapse/) | triangle mesh → triangle mesh | Simplification by collapsing the shortest edges first ([Hoppe 1996](https://hhoppe.com/pm.pdf)) |
| [`qslim`](https://wildmeshing.github.io/wildmeshing-toolkit/tutorials/qslim/) | triangle mesh → triangle mesh | Simplification by quadric error ([Garland and Heckbert 1997](https://dl.acm.org/doi/10.1145/258734.258849)) |
| [`isotropic_remeshing`](https://wildmeshing.github.io/wildmeshing-toolkit/tutorials/isotropic_remeshing/) | triangle mesh → triangle mesh | Uniform remeshing to a target edge length, keeping feature curves ([Botsch and Kobbelt 2004](https://ls7-gv.cs.tu-dortmund.de/downloads/publications/2004/sgp04.pdf)) |
| [`tetwild`](https://wildmeshing.github.io/wildmeshing-toolkit/tutorials/tetwild/) | triangle soups → tet mesh | Robust tetrahedral meshing of imperfect surfaces ([TetWild](https://cims.nyu.edu/gcl/papers/2018-TetWild.pdf)) |
| [`triwild`](https://wildmeshing.github.io/wildmeshing-toolkit/tutorials/triwild/) | curve networks → triangle mesh | Robust 2D triangulation of curves ([TriWild](https://cims.nyu.edu/gcl/papers/2019-TriWild.pdf)) |
| [`simwild`](https://wildmeshing.github.io/wildmeshing-toolkit/tutorials/simwild/) | surfaces or curves → multi-region mesh | Multi-region meshing, and region editing: remeshing, hole filling, sealing, overlap resolution, tag replacement |
| [`topological_offset`](https://wildmeshing.github.io/wildmeshing-toolkit/tutorials/topological_offset/) | tagged tet mesh → tagged tet mesh | A region at a target distance around a selection ([Topological Offsets](https://dl.acm.org/doi/10.1145/3731157)); 2D input is refused for now |
| [`manifold_extraction`](https://wildmeshing.github.io/wildmeshing-toolkit/tutorials/manifold_extraction/) | tagged mesh → tagged mesh | A manifold boundary for a selected region |
| [`tracking`](https://wildmeshing.github.io/wildmeshing-toolkit/tutorials/tracking/) | operation history → map | Maps points and fields between a remeshing's input and output |
| `prismatic_mesh` | offset tet mesh → prism/tet mesh | *Work in progress.* Thins the offset band around a solid to a target thickness and rebuilds it as prisms |
| `c1_simplification` | surface, tet and UV meshes → simplified meshes | *Work in progress.* Simplification within a deviation threshold, for C1 (Clough–Tocher) surfaces |

Every option of every component is in the
[reference](https://wildmeshing.github.io/wildmeshing-toolkit/reference/).

## Installation

Requirements: CMake 3.25 or newer, a C++17 compiler, and GMP (`apt install libgmp-dev`,
`brew install gmp`; on Windows CMake downloads it). CMake downloads every other dependency.

The command line, the C++ library and the tests:

```bash
git clone https://github.com/wildmeshing/wildmeshing-toolkit.git
cd wildmeshing-toolkit
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j
```

The Python package, from PyPI (wheels for macOS arm64, Linux x86_64 and arm64, and Windows
x86_64):

```bash
python -m pip install wildmeshing
```

or built from the repository root with `python -m pip install .`. Versions before 2.0.0 on PyPI
are the older [wildmeshing-python](https://github.com/wildmeshing/wildmeshing-python) bindings.
See [Installation](https://wildmeshing.github.io/wildmeshing-toolkit/getting-started/installation/)
for the options.

## Usage

From the command line, with a JSON file of options (input paths relative to the file, outputs
written to the working directory):

```bash
./build/app/wmtk_app --list                         # the components
./build/app/wmtk_app --options isotropic_remeshing  # one component's options
./build/app/wmtk_app -j data/integration_tests/isotropic_remeshing_bunny.json
```

```json
{
  "application": "isotropic_remeshing",
  "input": "../models/bunny.obj"
}
```

From Python, on files or on NumPy arrays:

```python
import wildmeshing as wm

# files in, files out
wm.tetwild({"input": ["bunny.obj"], "output": "bunny_tets"})

# arrays in, arrays out
outputs, report = wm.qslim({"input": "surface", "target_rel": 0.1},
                           {"surface": wm.read_mesh("bunny.obj")})
V = outputs["mesh"]["V"]
```

From C++, linking `wmtk::qslim`:

```cpp
#include <wmtk/components/qslim/qslim.hpp>
#include <wmtk/io/mesh_io.hpp>

wmtk::MeshMap meshes{{"surface", wmtk::io::read_mesh("bunny.obj")}};
auto [outputs, report] = wmtk::components::qslim::qslim(
    {{"input", "surface"}, {"target_rel", 0.1}}, meshes);
wmtk::io::write_mesh("bunny_simplified.vtu", outputs.at("mesh"));
```

[A first run](https://wildmeshing.github.io/wildmeshing-toolkit/getting-started/first-run/) walks
through the three.

## Contributing

See [CONTRIBUTING.md](https://github.com/wildmeshing/wildmeshing-toolkit/blob/main/CONTRIBUTING.md) and the
[developer guide](https://wildmeshing.github.io/wildmeshing-toolkit/developer/).

## Citing

The toolkit is described in *Declarative Specification for Unstructured Mesh Editing
Algorithms*, ACM Transactions on Graphics (SIGGRAPH Asia 2022); see
[Citing](https://wildmeshing.github.io/wildmeshing-toolkit/about/citing/) for the BibTeX and the
papers of each algorithm. The API has changed since; the version the paper describes is tag
[`1.0`](https://github.com/wildmeshing/wildmeshing-toolkit/releases/tag/1.0).

## License

[MIT](https://github.com/wildmeshing/wildmeshing-toolkit/blob/main/LICENSE). The libraries the
toolkit builds with have their own licenses.
