diff options
Diffstat (limited to 'extern/quadriflow/README.md')
| -rw-r--r-- | extern/quadriflow/README.md | 134 |
1 files changed, 134 insertions, 0 deletions
diff --git a/extern/quadriflow/README.md b/extern/quadriflow/README.md new file mode 100644 index 00000000000..dae22414184 --- /dev/null +++ b/extern/quadriflow/README.md @@ -0,0 +1,134 @@ +# QuadriFlow: A Scalable and Robust Method for Quadrangulation + +Source code for the paper: + +Jingwei Huang, Yichao Zhou, Matthias Niessner, Jonathan Shewchuk and Leonidas Guibas. [**QuadriFlow: A Scalable and Robust Method for Quadrangulation**](http://stanford.edu/~jingweih/papers/quadriflow/quadriflow.pdf), The Eurographics Symposium on Geometry Processing (SGP) 2018. + +<!-- ## Processing Result --> + + +## WebGL Application +Our 3D WebGL Apps for QuadriFlow are online! Without any installation, you are able to +* [**Compare**](https://yichaozhou.com/publication/1805quadriflow/#demo) QuadriFlow with previous methods; +* [**Quadrangulate**](https://yichaozhou.com/publication/1805quadriflow/#tool) your own meshes and + download the result! + +## Desktop Software +The software supports cmake build for Linux/Mac/Windows systems. For linux and mac users, run **`sh demo.sh`** to build and try the QuadriFlow example, which converts `examples/Gargoyle_input.obj` to `examples/Gargoyle_quadriflow.obj`. + +### Install + +``` +git clone git://github.com/hjwdzh/quadriflow +cd quadriflow +mkdir build +cd build +cmake .. -DCMAKE_BUILD_TYPE=release +make -j +``` + +### QuadriFlow Software + +We take a manifold triangle mesh `input.obj` and generate a manifold quad mesh `output.obj`. The face number increases linearly with the resolution controled by the user. + +``` +./quadriflow -i input.obj -o output.obj -f [resolution] +``` + +Here, the resolution is the desired number of faces in the quad mesh. + +## Advanced Functions + +### Min-cost Flow +By default, `quadriflow` uses the Boykov maximum flow solver from boost becuase it is faster. To +enable the adaptive network simplex minimum-cost flow solver, you can enable the `-mcf` option: + +``` +./quadriflow -mcf -i input.obj -o output.obj -f [resolution] +``` + +### Sharp Preserving +By default, `quadriflow` does not explicitly detect and perserve the sharp edges in the model. To +enable this feature, uses + +``` +./quadriflow -sharp -i input.obj -o output.obj -f [resolution] +``` + +### SAT Flip Removal (Unix Only) +By default, `quadriflow` does not use the SAT solver to remove the flips in the integer offsets +map. To remove the flips and guarantee a watertight result mesh, you can enable the SAT solver. +First, make sure that `minisat` and `timeout` is properly installed under your `${PATH}`. The +former can be done by building `3rd/MapleCOMSPS_LRB/CMakeLists.txt` and copying `minisat` to `/usr/bin`. +In addition, `timeout` is included in coreutils. If you are using Mac, you can install it using +homebrew: +``` +brew install coreutils +export PATH="/usr/local/opt/coreutils/libexec/gnubin:$PATH" +``` + +You can verify if those binaries are properly installed by executing +``` +which minisat +which timeout +``` + +After that, you can enable SAT flip removal procedure by executing +``` +./quadriflow -sat -i input.obj -o output.obj -f [resolution] +``` + +When using the SAT flip removal, we also suggest you enabling the verbose logging to understand +what is going on. You can build quadriflow with the following options: +``` +cmake .. -DCMAKE_BUILD_TYPE=release -DBUILD_LOG=ON +``` + +### GUROBI Support (For Benchmark Purpose) + +To use the Gurobi integer programming to solve the integer offset problem, you can build QuadriFlow with +``` +cmake .. -DCMAKE_BUILD_TYPE=release -DBUILD_GUROBI=ON -DBUILD_LOG=ON +``` +This override other solvers and should only be used for benchmark purpose. + +## External Dependencies +* Boost +* Eigen +* OpenMP (optional in CMake) +* TBB (optional in CMake) +* GUROBI (for benchmark purpose only) + +## Licenses + +QuadriFlow is released under [MIT License](LICENSE.txt). +For 3rd dependencies, +* Boost and Lemon are released under [Boost Software License](https://lemon.cs.elte.hu/trac/lemon/wiki/License) +* Most part of Eigen is released under [MPL2](https://www.mozilla.org/en-US/MPL/2.0/FAQ/) + * Sparse Cholesky Decomposition algorithms are released under LGPL + * To replace it using Sparse LU decomposition with a more permissive MPL2 license (a little slower), enable `BUILD_FREE_LICENSE` in CMake (e.g., `-DBUILD_FREE_LICENSE=ON`). +* `pcg32.h` is released under the Apache License, Version 2.0 +* `parallel_stable_sort.h` is released under the MIT License + +## Authors +- [Jingwei Huang](mailto:jingweih@stanford.edu) +- [Yichao Zhou](mailto:zyc@berkeley.edu) + +© 2018 Jingwei Huang and Yichao Zhou All Rights Reserved + +**IMPORTANT**: If you use this software please cite the following in any resulting publication: +``` +@article {10.1111:cgf.13498, + journal = {Computer Graphics Forum}, + title = {{QuadriFlow: A Scalable and Robust Method for Quadrangulation}}, + author = {Huang, Jingwei and Zhou, Yichao and Niessner, Matthias and Shewchuk, Jonathan Richard and Guibas, Leonidas J.}, + year = {2018}, + publisher = {The Eurographics Association and John Wiley & Sons Ltd.}, + ISSN = {1467-8659}, + DOI = {10.1111/cgf.13498} +} +``` + +## Triangle Manifold + +In case you are dealing with a triangle mesh that is not a manifold, we implemented the software that converts any triangle mesh to watertight manifold. Please visit https://github.com/hjwdzh/Manifold for details. |