Merge branch 'github-pages'

docs/_data/nav.yml

@@ -3,22 +3,27 @@
     - title: Introduction
     - title: Contents
     - title: How to run
+    - title: Settings
     - title: Known issues
+
+- title: Installation
+  pages:
     - title: Windows binaries
+    - title: Docker image
     - title: Windows compilation
-    - title: Ubuntu 14.04
     - title: Ubuntu 16.04
     - title: MacOS
 
 - title: Data preparation
   pages:
     - title: Overview
-
+    - title: Generate terrain
+    - title: Building footprints from OpenStreetMap
 - title: Examples
   pages:
     - title: Example data
-    - title: BGT with AHN3
     - title: Buildings without terrain
+    - title: Building statistics as CSV
     - title: Buildings with terrain
 
 - title: Output formats

docs/pages/data-preparation/building-footprints-from-openstreetmap.md

@@ -0,0 +1,45 @@
+---
+layout: default
+title: Building footprints from OpenStreetMap
+group: data-preparation
+---
+
+This guide is about extracting building footprints as a Shapefile of polygons from the [OpenStreetMap](https://www.openstreetmap.org) dataset, in order to use them as input for 3dfier.
+
+## Download OSM data 
+
+First, you need to download the OSM data for your area of interest:
+
+1. Through your browser, visit the [OpenStreetMap](https://www.openstreetmap.org) website
+
+1. Zoom at the area you want to work on
+
+1. Press the `Export` button on the top
+
+1. From the left panel, you may select to further specify the area you want to download (via the `Manually select a different area` option)
+
+1. When finished, press the `Export` button from the left panel.
+
+You should be asked to download an `.osm` file. Just store it somewhere on your computer.
+
+## Extract buildings through QGIS 
+
+Originally, the data from OpenStreetMap are just geometries with key-value pairs assigned to them. You can easily filter the buildings from all geometries inside an `.osm` file.
+
+1. Open QGIS.
+
+1. From the menu, select `Layers`->`Add Layer`->`Add Vector layer...`.
+
+1. Select the `.osm` file with the area downloaded.
+
+1. When prompted about the layer you want to add, you can only select the `multipolygons` layer (it's OK if you add all of them, but buildings are on this layer).
+
+1. From the `Layers Panel`, right-click on the multipolygons layer you've just added and select `Filter...`.
+
+1. On the dialog, provide the following expression: `"building" is not null` (essentially, what that means is that all polygons without a _building_ key, will be filtered out). You should now see only the buildings on the map.
+
+1. From the `Layers Panel`, right-click on the multipolygons layer, again, and now select `Save as...`.
+
+1. On the dialog, select the `ESRI Shapefile` format and provide the output file. You may also want to reproject the geometries on another CRS, now, if the elevation data you are going to use on 3dfier are not on WGS 84 (EPSG:4326).
+
+When you save, you should have a shapefile with footprint of the buildings for this area, at the CRS you specified. You can use this, now, as an input for 3dfier.

docs/pages/data-preparation/generate-terrain.md

@@ -0,0 +1,26 @@
+---
+layout: default
+title: Generate terrain
+group: data-preparation
+---
+
+Without a 2D polygon describing terrain extent, 3dfier is not able to create a terrain from a point cloud without. The solution is to create a polygon of the area of interest save this as a shapefile.
+
+We make sure the terrain and buildings are stitched nicely and the buildings do not intersect with the terrain. We do this by using symetrical difference between the terrain polygon and the buildings. For nice tutorial about this see section *D. Symmetrical Difference* at [GrindGIS](http://grindgis.com/software/qgis/basic-editing-tools-in-qgis).
+
+### Terrain
+![image](https://user-images.githubusercontent.com/30265851/32222599-30d38b70-be3a-11e7-90ad-000218305924.png)
+
+### Symmetrical Difference operation result
+![image](https://user-images.githubusercontent.com/30265851/32222645-62cf1964-be3a-11e7-9a70-746222d0c53a.png)
+
+### 2D terrain + buildings
+![image](https://user-images.githubusercontent.com/30265851/32222677-7acc1a3a-be3a-11e7-8737-c0637005a6ba.png)
+
+### 3D model as OBJ in Meshlab
+![image](https://user-images.githubusercontent.com/30265851/32222728-b87a5112-be3a-11e7-892e-32e4afee01ca.png)
+
+### Viewpoint below the 3D model
+![image](https://user-images.githubusercontent.com/30265851/32222770-e95b2a40-be3a-11e7-88c2-c026412ebc9e.png)
+
+Thanks to [@antoinebio](https://github.com/antoinebio) for the images supplied in [issue #48](https://github.com/tudelft3d/3dfier/issues/48).

docs/pages/examples/example-data.md

@@ -4,11 +4,17 @@ title: Example data
 group: examples
 ---
 
+## Prepare example data
+For this example we use [BGT_Delft_Example.zip]({{site.github.repository_url}}/raw/master/resources/Example_data/BGT_Delft_Example.zip) from the GitHub repository located in `3dfier/resources/Example_data/`. Create a folder with 3dfier and the depencency dll's and add the `example_data folder`.
+
+![Folder layout](/img/example_folder.png)
+
 ## Running with the example data
-Start by opening the Command Prompt (press windows button+R, type cmd and press enter) and navigate to the folder where 3dfier is located.
+Opening the Command Prompt (press windows button+R, type cmd and press enter) and navigate to the folder where 3dfier is located.
 
+Now go into the example data folder using `cd example_data` and run `..\3dfier.exe testarea_config.yml --OBJ output\myfirstmodel.obj`. Now 3dfier will start processing and when finished it produced its first 3D model!
 
-Now go into the example data folder using `cd example_data` and run `..\3dfier.exe testarea_config.yml --OBJ output\myfirstmodel.obj`. Now 3dfier will start processing and when finished it produced its first 3d model! The file can be found here `example_data\output\testarea.obj` and console output should be as follows.
+The output file can be found here `example_data\output\testarea.obj` and console output should be as follows.
 
 ```
 3dfier Copyright (C) 2015-2018  3D geoinformation research group, TU Delft

docs/pages/getting-started/contents.md

@@ -4,3 +4,8 @@ title: Contents
 group: getting-started
 ---
 
+## Release binaries content
+Description of files in the zip file 
+
+## Resources
+Description of the contents of the resources repository

docs/pages/getting-started/settings.md

@@ -0,0 +1,7 @@
+---
+layout: default
+title: Settings
+group: getting-started
+---
+
+You can validate the format of the config file using [www.yamllint.com](http://www.yamllint.com)

docs/pages/installation/docker-image.md

@@ -0,0 +1,65 @@
+---
+layout: default
+title: Docker image
+group: installation
+---
+
+The Dockerfile for building 3dfier (`Dockerfile_builder`) contains the complete instruction for setting up a build environment. If you don't want to install the required dependencies on your local machine, you can use this docker image to build and run 3dfier. If you want to build 3dfier locally, then please look into the Dockerfile for the libraries that you'll need.
+
+## Using Docker to compile and run 3dfier
+
+The builder image (`Dockerfile_builder`) does not contain the source code of 3dfier, neither the executable. We use this image for compiling 3dfier from different branches during development and testing. Nevertheless, it is suitable for 3dfying any data set.
+
+As an example, the complete process of building the docker image, compiling 3dfier and running looks like the following.
+
+
+**1. Build the docker image**
+
+```
+$ docker build -t 3dfier:builder -f Dockerfile_builder .
+```
+
+**2. Prepare a compiler script for 3dfier**
+
+The contents of `build_3dfier.sh`
+
+```
+#! /bin/sh
+
+rm -rf /opt/3dfier_src/build; \
+cd /opt/3dfier_src && mkdir build && cd ./build; \
+cmake \
+-DLIBLASC_LIBRARY=/opt/libLAS-1.8.1/build/lib/liblas_c.so \
+-DLIBLAS_INCLUDE_DIR=/opt/libLAS-1.8.1/build/include \
+-DLIBLAS_LIBRARY=/opt/libLAS-1.8.1/build/lib/liblas.so \
+-DLASZIP_INCLUDE_DIR=/opt/laszip-src-2.2.0/build/include \
+-DLASZIP_LIBRARY=/opt/laszip-src-2.2.0/build/lib/liblaszip.so \
+-DCGAL_DIR=/opt/cgal-releases-CGAL-4.12/build \
+-DCMAKE_BUILD_TYPE=Release ../3dfier \
+; \
+make
+```
+
+**3. Compile 3dfier in a container**
+
+If we set up an out of source build system in a root directory `3dfier_src` with the following sturcture,
+
+```
+/3dfier_src
+├── 3dfier
+├── build
+
+```
+then we execute the commands from the root dir. The `3dfier_src` dir is *bind-mount*-ed to the container where 3dfier is complied by running `build_3dfier.sh`. The script will place the executable into the `build` directory in `3dfier_src`.
+
+```
+$ docker run --rm -it -v "$(pwd)":/opt/3dfier_src 3dfier:builder /opt/3dfier_src/build_3dfier.sh
+```
+
+**4. Running 3dfier in a container**
+
+Then the previously built executable is mounted to the container and executed there. Note that the data and config files are also mounted in a similar fashion.
+
+```
+$ docker run --rm -it -v "$(pwd)":/opt/3dfier_src 3dfier:builder /opt/3dfier_src/build/3dfier /opt/3dfier_src/3dfier/example_data/testarea_config_docker.yml --CSV-BUILDINGS /opt/3dfier_src/test.csv
+```

docs/pages/installation/ubuntu-16-04.md

@@ -0,0 +1,38 @@
+---
+layout: default
+title: Ubuntu 16.04
+group: installation
+---
+
+## 1 Adding *ubuntugis* repositories
+To install *GDAL* on Ubuntu 16.04 LTS it is probably the easiest to add one of the *ubuntugis* repositories, either [*ubuntugis-stable*](https://launchpad.net/~ubuntugis/+archive/ubuntu/ppa?field.series_filter=xenial) or [*ubuntugis-unstable*](https://launchpad.net/~ubuntugis/+archive/ubuntu/ubuntugis-unstable?field.series_filter=xenial). Both contains *GDAL* >= 2.1.
+
+E.g. add the *ubuntugis-stable* repository by running:
+```
+sudo add-apt-repository ppa:ubuntugis/ppa
+sudo apt-get update
+```
+
+## 2 Install dependencies
+*CGAL* (`libcgal-dev`), *Boost* (`libboost-all-dev`) and *yaml-cpp* (`libyaml-cpp0.5v5`) are part of the *Ubuntu Universe* repository.
+
+Once you have all the repos added, you can use a package manager, e.g. `apt` or *Synaptic* to install them. 
+
+E.g. using apt-get:
+```
+sudo apt-get install libcgal-dev libboost-all-dev libyaml-cpp0.5v5
+```
+
+## 3 Run the build script 
+*LASzip*, *libLAS* and *3dfier* need to be built manually in this order, and this is what the [build script](https://github.com/tudelft3d/3dfier/blob/build_ubuntu_2/ressources/build_ubuntu1604.sh) can do for you. It downloads and compiles these three packages, and takes care that *libLAS* is compiled with *LASzip* support and that *3dfier* can find the executables of both. We try to take care that the download links are up to date with the upcoming releases. However, if you notice that the links are outdated, just update the version number in the script.
+
+To download and run the [build script](https://github.com/tudelft3d/3dfier/blob/build_ubuntu_2/ressources/build_ubuntu1604.sh) do:
+```
+wget https://raw.githubusercontent.com/tudelft3d/3dfier/build_ubuntu_2/ressources/build_ubuntu1604.sh
+sudo build_ubuntu1604.sh /opt
+```
+
+Where `/opt` is the directory where *3dfier* will be installed and *LASzip*, *libLAS* downloaded and compiled. *LASzip*, *libLAS* is installed into `/usr/local`, hence you'll probably need root privilage to run the script.
+
+**A note on GRASS GIS and libLAS**\
+If you already have GRASS installed from the *ubuntugis-(un)stable* PPA, you probably also have libLAS (`liblas-c3, liblas3`) installed, as GRASS depends on them. However, this *libLAS* install is without *LASzip* support as *LASzip* is not part of the *ubuntugis* PPA. Therefore, you will need to remove the GRASS and *libLAS* libraries first, then compile *libLAS* with *LASzip* support (with this script). Then you can install GRASS again from the *ubuntugis* PPA, it will be compiled with *libLAS* that now supports `.laz`.

docs/pages/getting-started/windows-binaries.md → docs/pages/installation/windows-binaries.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Windows binaries
-group: getting-started
+group: installation
 ---
 
 There exists a ready-to-use version of [3dfier for Windows 64-bit]({{site.github.repository_url}}/releases/latest). Download and extract the files to any given folder and [execute 3dfier]({{site.baseurl}}/pages/getting-started/how-to-run).

docs/pages/getting-started/windows-compilation.md → docs/pages/installation/windows-compilation.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Windows compilation
-group: getting-started
+group: installation
 ---
 
 This guide will talk you through the compilation of 3dfier on Windows 10 64-bit using Visual Studio 2017 (steps are identical for Visual Studio 2015).