nnaemekaibe / 3dfier

Takes 2D GIS datasets and "3dfies" them by lifting each polygon to its height (obtained with LiDAR). Then outputs to variety of formats (OBJ, CityJSON, etc).

Continuous integration

Build server	Platform	Build status
AppVeyor	Windows
Travis	Ubuntu

Wiki

The 3dfier wiki has extensive information on the installation, data preparation, usage and output of 3dfier.

SETTINGS

For all available setting and default values look at the config files folder

3dfier

Takes 2D GIS datasets (e.g. topographical datasets) and "3dfies" them (as in "making them three-dimensional") by lifting every polygon to 3D. The elevation is obtained from a point cloud (we support LAS/LAZ at this moment), and the semantics of every polygon is used to perform the lifting. That is, water polygons are extruded to horizontal polygons, buildings to LOD1 blocks, roads as smooth surfaces, etc. Every polygon is triangulated (constrained Delaunay triangulation) and the lifted polygons are "stitched" together so that one digital surface model (DSM) is constructed. Our aim is to obtain one DSM that is error-free, i.e. no intersecting triangles, no holes (the surface is watertight), where buildings are integrated in the surface, etc. This surface will then be used as input in simulation software for instance.

This video illustrates the process and what 3dfier is about.

The lifting options can be configured in the YAML file provided, an examples are provided in /resources/config_files/myconfig.yml. Any 2D input (which should be a planar partition) can be used as input, and each class must be mapped to one of the following:

1. Building
2. Terrain
3. Road
4. Water
5. Forest
6. Bridge
7. Separation (used for concrete slabs used along canals for instance, surely very "Dutch")

It is possible to define new classes, although that would require a bit of programming.

Output is in the following formats: OBJ, CityGML, CityJSON, CSV (for buildings only, i.e. their ID and height (ground+roof) are output in a tabular format), and PostGIS. The ID of each polygon is preserved, and there is a 1-to-1 mapping between the input and the output.

If you use it, feedback is very much appreciated.

LAS/LAZ Pointcloud

We expect the LAS/LAZ to be classified according to the ASPRS Standard LIDAR Point Classes v1.4 (Table 4.9 of this PDF), and at a minimum these should be defined:

• 0-1: Created, never classified and/or unclassified
• 2: Ground
• 3-5: Vegetation

If the vegetation is not classified or not filtered out, then buildings might be taller and there might be artefacts in the terrain.

Binary releases for Windows and Mac OS X

In order to make easy use of 3dfier we created pre-build binaries which can be downloaded from the releases page.

Download the latest release and unzip the archive in a easy to find location, not in the download folder of your browser.

To be able to quickly test 3dfier one can download the example dataset and unzip the archive in the folder of 3dfier.

Test data

In the folder example_data (download example dataset) there is a small part of the BGT datasets (2D 1:1k topographic datasets of the Netherlands), and a part of the AHN3 LIDAR dataset that can be used for testing. The resulting model (in OBJ) can be found in example_data/output/test_area.obj

Further, there is an open data website that contains 3D models of a few Dutch cities, generated with 3dfier.

Validate config file

The configuration is stored in YAML format and needs to be valid for the parser to read the file. Config files can be schema validated using YAML Lint

A configuration file with description of all possible settings is myconfig_README.yml

Run 3dfier:

Windows Open a command line (click start and type command or cmd). Using the command line browse to the folder where you extracted the example files and run: 3dfier myconfig.yml -o output.ext

Mac OS X and Linux Open a console. Using the console browse to the folder where you extracted the example files and run: $ ./3dfier myconfig.yml -o output.ext

There is also a tutorial on how to generate a 3D model with 3dfier.

Prepare BGT data

For preparing BGT data as input for 3dfier look at resources/BGT_prepare/ReadMe.md

Compiling Mac OS X/Linux

To build you'll normally do (from 3dfier root directory):

mkdir build && cd build
cmake .. 
cmake ..
make

Notice that cmake is indeed called twice, we have noticed that on some machines the compiler optimisation is activated only when you cmake twice. Why that is we are not sure, but to be sure do it twice. With the optimisation, the test dataset should take around 20s to produce; if more (>5min) then the optimisation is not activated properly.

The dependencies that are necessary (under Mac we suggest using Homebrew):

1. LIBLAS with LASzip support (brew install liblas --with-laszip)
2. GDAL (brew install gdal)
3. Boost (brew install boost)
4. CGAL (brew install cgal)
5. yaml-cpp (brew install yaml-cpp)

For Linux we suggest taking a look at the travis build scripts for Ubuntu.

Compiling Windows using Visual Studio

Detailed instructions can be found on our wiki. Short version:

1. Download and install Boost precompiled binaries
2. Download and install OSGeo4W
3. Compile your own copies of Yaml-cpp and CGAL
4. Add environment variables for:
5. • OSGEO4W_ROOT (set by OSGeo4W installer)
   • BOOST_ROOT (root of the boost directory)
   • BOOST_LIBRARYDIR (dir of the boost lib files)
   • LIBLAS_ROOT (same as OSGEO4W_ROOT if that liblas is used)
   • LASZIP_ROOT (same as OSGEO4W_ROOT if that liblas is used)
   • YAML-CPP_DIR (root of the Yaml-cpp directory)
   • CGAL_DIR (root of the CGAL directory)
6. Build solution using Visual Studio