Polygonal surface reconstruction from point clouds

PolyFit reconstruction pipeline

PolyFit implements the hypothesis and selection based surface reconstruction method described in the following paper:

Liangliang Nan and Peter Wonka. 
PolyFit: Polygonal Surface Reconstruction from Point Clouds. 
ICCV 2017.

Obtaining PolyFit

Prebuilt executable files (for macOS, Linux, and Windows) are available here.

You can also build PolyFit from the source code:

Clone the repository or download the source code.
Dependencies
- Qt5 (v5.12.12, v5.10.1, v5.9.2, and v5.8.0 were tested). Qt is required by the GUI demo. You should still be able to build the command-line example without Qt.
- CGAL (v5.5, v5.0, v4.11.1, and v4.10 were tested).
Build PolyFit

There are many options to build PolyFit. Choose one of the following (not an exhaustive list):
- Option 1 (purely on the command line): Use CMake to generate Makefiles and then make (on Linux/macOS) or nmake(on Windows with Microsoft Visual Studio).
  - On Linux or macOS
```
$ cd PolyFit
$ mkdir Release
$ cd Release
$ cmake -DCMAKE_BUILD_TYPE=Release ..
$ make
```
  - On Windows with Microsoft Visual Studio, use the x64 Native Tools Command Prompt for VS XXXX (don't use the x86 one), then
```
$ cd PolyFit
$ mkdir Release
$ cd Release
$ cmake -G "NMake Makefiles" -DCMAKE_BUILD_TYPE=Release ..
$ nmake
```
- Option 2: Use any IDE that can directly handle CMakeLists files to open the CMakeLists.txt in the root directory of PolyFit. Then you should have obtained a usable project and just build it. I recommend using CLion or QtCreator. For Windows users: your IDE must be set for x64.
- Option 3: Use CMake-Gui to generate project files for your favorite IDE. Then load the project to your IDE and build it. For Windows users: your IDE must be set for x64.
Don't have any experience with C/C++ programming? Have a look at How to build PolyFit step by step.

News: Since Aug. 5, 2019, PolyFit is also available in CGAL. Find more here.

Run PolyFit

This repository includes a command-line example and a GUI demo.

For the commandline example, you can simply build and run it (the path to the input file is hard-coded in the code).
The GUI demo provides a user interface with a few buttons (with numbered icons) and screen hints corresponding to these steps. Just click the buttons following the hints.

Data

Some test data can be downloaded from the project page.

More information about the data (e.g., data format) is described here.

Plane extraction. Incorporating plane extraction adds an unnecessary dependency to more third-party libraries (e.g., RANSAC). Besides, it has some randomness (due to the nature of RANSAC) and the data quality can vary a lot (it should be fine if some regions of the planes are missing). So I isolated this part from this demo version and you're expected to provide the planar segments as input.

You can use my Mapple to extract planes from point clouds. After you load the point cloud, go to the menu Partition -> Extract Primitives. To visualize the planes, change the renderer from 'Plain' to 'Group' in the Rendering panel (on the left side of Mapple). You can save the planes in bvg (Binary Vertex Group) format. The ASCII format vg also works but is slow. Please note, PolyFit assumes that the model is closed and all necessary planes are provided.

About the solvers

Four solvers, namely Gurobi, SCIP, GLPK, and lp_solve, are provided (with source code) in PolyFit. The Gurobi solver is more efficient and reliable and should always be your first choice. To use Gurobi, you need to install it and also obtain a license (free for academic use) from here. You may also need to modify the path(s) to Gurobi in FindGUROBI.cmake, for CMake to find Gurobi. In case you want a fast but open-source solver, please try SCIP, which is slower than Gurobi but acceptable. The GLPK and lp_solve solvers only manage to solve small problems. They are too slow (and thus may not guarantee to succeed). For example the data "Fig1", Gurobi takes only 0.02 seconds, while lp_solve 15 minutes.

Note for Linux users: You may have to build the Gurobi library (libgurobi_c++.a) because the prebuilt one in the original package might NOT be compatible with your compiler. To do so, go to src/build and run make. Then replace the original libgurobi_c++.a (in the lib directory) with your generated file.

About the timing

This demo implementation incorporates a progress logger in the user interface. Thus, running times should be (slightly) longer than those reported in our paper.

Citation

If you use the code/program (or part) of PolyFit in scientific work, please cite our paper:

@inproceedings{nan2017polyfit,
  title={Polyfit: Polygonal surface reconstruction from point clouds},
  author={Nan, Liangliang and Wonka, Peter},
  booktitle={Proceedings of the IEEE International Conference on Computer Vision},
  pages={2353--2361},
  year={2017}
}

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License or (at your option) any later version. The full text of the license can be found in the accompanying LICENSE file.

Should you have any questions, comments, or suggestions, please contact me at: liangliang.nan@gmail.com

Liangliang Nan

https://3d.bk.tudelft.nl/liangliang/

July 18, 2017

vanlic/PolyFit