Skip to content

Latest commit

 

History

History
152 lines (112 loc) · 9.31 KB

ReadMe.md

File metadata and controls

152 lines (112 loc) · 9.31 KB
Raw

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.

Despite being a research prototype, City3D has been used to create city-scale building models. This article explores its potential and limitations from a user's perspective, comparing results in Dutch and French datasets.

Obtain 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.14.2, v5.12.12, and v6.7.3 have been tested). 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.6, v5.5 and v5.4 have been tested). Newer versions of CGAL (v5.6 and later) are always preferred for better performance.
    • 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: This is a command-line program capable of reconstructing multiple buildings in a large scene using both point cloud and footprint data as input. Some test data is provided in the data directory.

  • CLI_Example_2: This command-line program demonstrates the reconstruction of pre-segmented buildings in a large scene using only the point cloud data as input. Each building has already been segmented, and individual buildings are stored as separate point cloud files. Our method generates a footprint for each building and then reconstructs it. Test data for this example can be found in the building_instances directory.

  • City3D: This is a demo version of our method with a graphical user interface (GUI). The demo provides a simple interface with numbered buttons. To run the workflow, click the buttons sequentially as specified. The UI was adapted from PolyFit.

Most buildings can be reconstructed using the default parameters. In case of unexpected behaviors/results, please refer to Parameter Tuning for guidance on adjusting the parameters.

Data

The method has been evaluated on approximately 20,000 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 testing, which can be found in the data directory.

City3D assumes the footprint of a building is a simple polygon. For a set of buildings, their footprint data consists of the same number of polygons. In this research prototype, City3D supports two file formats of footprint data:

  • OBJ file: each polygon is stored as a 3D polygon (with Z coordinates set to 0) in a polygonal mesh.
  • GeoJSON: an open standard format for representing simple geographical features and their attributes. In City3D, only polygon features are parsed to represent footprints. In case your footprints are store in the shapefile format, please check Converting shapefiles to geojson.

Sources of footprint data may include:

  • The cadastre of the city/country. Many countries maintain footprint data through their cadastre, which may be publicly available or can be obtained by contacting the relevant authorities.
  • Open data platforms such as OpenStreetMap may offer footprint data.

In case you have a point cloud of a scene containing multiple buildings, but don't have access to the footprint of the buildings, you will need to segment out the individual buildings either manually or using an automatic approach. There are various published papers addressing instance segmentation of urban buildings from point clouds. You can explore these methods to find one that fits your purpose, and then CLI_Example_2 will be suitable for the reconstruction.

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 raise an issue.

June 28, 2022

Copyright (C) 2022