City3D: Large-scale Building Reconstruction from Airborne LiDAR Point Clouds

City3D implements the hypothesis-and-selection based building reconstruction method described in the following paper:

Jin Huang, Jantien Stoter, Ravi Peters, Liangliang Nan. 
City3D: Large-scale Building Reconstruction from Airborne LiDAR Point Clouds.
Remote Sensing. 14(9), 2254, 2022.

This implementation is based on PolyFit.

---

Obtaining City3D

You can build City3D from the source code˙

• Download the source code.

• Dependencies (Attention for Windows users: ALL dependencies must be for x64)

  • Qt (v5.12 and later). This is required by only the GUI demo of City3D. Without Qt, you should still be able to build the two command-line programs CLI_Example_1 and CLI_Example_2.
  • CGAL (v5.4 and later).
  • OpenCV (v4.0 and later, only the main modules are needed).
  • Gurobi. 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 PATH-TO-GUROBI/src/build and run make. Then replace the original libgurobi_c++.a (in the lib directory) with your generated file.

• Build

  There are many options to build City3D. 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 path-to-root-dir-of-City3D
      $ 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 path-to-root-dir-of-City3D           
      $ 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 City3D. 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? Then check this How to build I wrote for Easy3D.

Run City3D

This repository includes three executable programs:

• CLI_Example_1: a command-line program that can reconstruct multiple buildings in a large scene using both point cloud and footprint as input. Some test data is provided in the data directory.

• CLI_Example_2: a command-line program showing the reconstruction of all the pre-segmented buildings in a large scene using only the point clouds as input. The individual buildings have already been segmented and each building is stored as a separate point cloud file. Our method generates a footprint for each building and then reconstructs it. For this example, only the point cloud of a building is needed. See some test data in the building_instances directory.

• City3D: a demo version of our method with GUI. This demo provides a simple user interface with a few buttons (with numbered icons). Just click the buttons one by one in the specified order to run the workflow. The UI was adapted from PolyFit.

---

Data

The method has been evaluated on ~20K buildings, resulting in a new dataset consisting of the original point clouds and the reconstructed 3D models of all these buildings. The complete dataset can be found here.

This repository has included a few buildings from the above dataset for test, which can be found in the data directory.

---

About the solvers

This demo program can use either the SCIP solver or the commercial solver Gurobi for the core optimization step. The entire source code of the SCIP solver is already included in this repository.

The Gurobi solver is faster than SCIP and is thus highly recommended. To use Gurobi, install it first and make sure the headers and libraries of Gurobi can be found by CMake. This can be done by specifying the paths of Gurobi in FindGUROBI.cmake. Note: you need to obtain a license to use Gurobi, which is free for academic use.

---

Citation

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

@Article{HuangCity3d_2022,
    AUTHOR = {Huang, Jin and Stoter, Jantien and Peters, Ravi and Nan, Liangliang},
    TITLE = {City3D: Large-Scale Building Reconstruction from Airborne LiDAR Point Clouds},
    JOURNAL = {Remote Sensing},
    VOLUME = {14},
    YEAR = {2022},
    NUMBER = {9},
    ARTICLE-NUMBER = {2254},
}

---

### 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 feel free to contact me at:
J.Huang-1@tudelft.nl 

**_Jin Huang_**

https://yidahuang.github.io/

June 28, 2022

Copyright (C) 2022