Assignment 2

Enriching the 3D BAG with building metrics

Deadline is 24 March 2023 at 11:59 pm

Late submission? 10% will be removed for each day that you are late.

You’re allowed for this assignment to work in a group of 3 (and thus submit only one solution for all of you). If you prefer to work alone or in pairs, it’s also fine, but we really do not recommend it.

The assignment is worth 20% of your final mark.

cover

Overview

In its current form, the 3DBAG dataset contains for each of the 10M buildings in the Netherlands:

  1. the 3D geometry at three LoDs: 1.2+1.3+2.2
  2. several attributes, eg the construction year, the height of the ground, the type of roof, current status of the building, etc.

For this assignment, you are asked to calculate a few useful 3D building metrics to derive extra attributes, and to add them to the file. Those are described in the article 3D building metrics for urban morphology, where it is described how they are useful in practice. The metrics are a generalisation of the indicators that can be calculated in 2D by momepy (a nice library for urban morphology, you should check it).

For this assignment, you will need to calculate the following five (for the LoD2.2 geometries only):

  1. volume
  2. rectangularity
  3. hemisphericality
  4. roughness index
  5. an indicator of the orientation of the "RoofSurface" surfaces

The updated model must be delivered in the CityJSON format.

Your code should be able to read any 3D BAG file as input

The 3D BAG, developed by the 3D geoinformation group at TU Delft and further explained in Lesson 4.2, is a dataset containing 3D models of all the buildings in the Netherlands. The 3D BAG is open data and it contains 3D models at multiple levels of detail (LoDs), which are generated by combining two open datasets: the building data from the BAG and the height data from the AHN. The 3D BAG is updated regularly, keeping it up-to-date with the latest openly available building stock and elevation information. More details about the 3D BAG are available on its website.

The 10M buildings are tiled, and you can download a tile (which contains typically a few hundred buildings). To start, you can practice on the tile where BK-City is located:

3dbag_v210908_fd2cee53_5910.json

Methodology/workflow to use

You have to use C++ and the CGAL library to do this assignment.

Your code needs to be a single binary/executable that reads one (preprocessed, see next step) 3DBAG tile in CityJSON, and it will output a new one containing the required extra metrics and attributes.

You can use any packages of CGAL except the following functions, which you have to code (these are essential for the assignment and it’s one learning objective to learn how to implement those yourself):

Preprocessing of the 3DBAG file

The 3D BAG files are still in the version 1.0 of CityJSON (but the next release in March will fix this). However, we want to use the latest version 1.1 (see specifications v1.1.3). Also, we want to keep only LoD2.2 (and remove 0, 1.2, and 1.3; all those are bundled in the original CityJSON file).

All those operations can be performed with cjio with one command:

cjio 3dbag_v210908_fd2cee53_5910.json upgrade vertices_clean lod_filter 2.2 metadata_remove save myfile.city.json

You then obtain a v1.1 file myfile.city.json that is cleaned (duplicate vertices have been removed and metadata removed), and it only contains LoD2.2.

You can visualise that file using ninja.cityjson.org, QGIS (using the CityJSON Loader plugin), or azul (macOS only).

Volume

You have to calculate the volume of each building (specifically their LoD2.2 geometry).

If \(E\) is the exterior boundary/envelop of a building, then we define its volume by \(Vol(E)\).

You have to implement the method yourself, you are thus not allowed to use an off-the-shelf solution that you find somewhere or the CGAL::volume() functions.

Moreover, we prescribe the method that needs to be used, which is a generalisation of the method that you learned in GEO1002. You need to decompose the solid of the building into tetrahedra, and sum the (signed) volume of each.

Rectangularity

In the paper 3D building metrics for urban morphology, this is called “cuboidness”, and is defined as “it measures the volume deviation between a polyhedron and its minimum volume bounding box. Thus, it reveals a polyhedron’s degree of being curved inwards.”

As Appendix Table 1 shows, it is obtained by dividing the volume of the building by the volume of the oriented bounding box:

\[Rec(E) = \frac{Vol(E)}{Vol(OOBB(E))}\]

where \(OOBB(E)\) is the object oriented bounding box of \(E\) (also called optimal bbox, or object aligned bbox).

CGAL implements the function (CGAL Optimal Bounding Box), you are allowed to use it (it’s rather complex to calculate yourself also).

Hemisphericality

“It measures the volume deviation between a polyhedron and its equal-area hemisphere. A hemisphere was selected to represent the space above ground.”

\[HEM(E) = \frac{3\sqrt{2\pi}Vol(E)}{Area(E)^{3/2}}\]

where \(Area(E)\) is the area of the surfaces of \(E\).

Roughness index

“The index was created as a measure of compactness. It has two advantages against the indices based on volume to surface area ratio such as hemisphericality: (1) less sensitive to the elongation (i.e. the aspect ratio of a polyhedron) and (2) more responsive to the roughness (i.e. intrusions and protrusions along the boundary of a polyhedron).”

\[RI(E) = \frac{\mu_{E}^3}{Vol(E) + Area(E)^{3/2}} \times 48.735\]

where \(\mu_E\) is the average distance of points sampled on \(E\) to the center of \(E\).

You are required to sample points on the surface of \(E\), and we require at least 2 samples per triangle (so yes the planar surfaces of \(E\) need to be triangulated, you can use your hw01 code); those samples can be randomly generated anywhere on the triangle. The vertices of the triangles should also be used.

Orientation of the "RoofSurface" surfaces

The surfaces with semantics "RoofSurface" need to have their orientation added as an attribute to the Semantic object, as explained there. There are 9 classes, all stored as a string. If the roof surface is horizontal, then "horizontal" should be put, if not then one of those 8 values:

Requirements for the program

It should take one argument (the input CityJSON file), and output in the same folder (as the program) a new file called out.city.json.

The demo code for hw02 shows how this can be done.

Requirements for the CityJSON output

  1. use CityJSON version 1.1
  2. the file should follow the same structure and have all the original content of the preprocessed input file (the one you cleaned with the cjio command above), eg a "Building" has all of its original attributes and the original LoD2.2 geometries are in the "children" as a "BuildingPart". The only difference allowed is that the order of the properties doesn’t need to be the same since your library might not allow you to have control over this.
  3. only the LoD2.2 should be present, the other LoDs (0, 1.2, and 1.3) should be deleted
  4. the file you produce must be valid according to the schema (use cjval to verify this).
  5. Be careful about the types and names of the attributes, they are shown below.

You have to add the attributes for each building (and their surfaces) this way:

Some tips

Report

The short report should only discuss, for each of the 5 required attributes/metrics, the engineering decisions you took (why did you do it this way or not another way?), and the difficulties/issues you faced and how you solved them.

Also, a who-did-what? section should be in the report: explain how the tasks were divided among the members of the team. It needs to be relatively equal, and one member cannot only write the report, all have to work on at least one of the 5 attributes.

We expect a report of about 5 pages max (including figures).

Marking

Criterion Points
report (quality/readability/etc) 2
file valid + rules respected 1
volume 2
rectangularity 1
hemisphericality 1
orientation 1
roughness index 1
uniqueness of the solution 1

The uniqueness is a subjective point we will award to solutions that are clearly unique (and not with tips and tricks used by everyone). This doesn’t mean that you need to find different and complex ways, but we want to avoid (as we have seen in some assignments for GEO1015) that one (often very clever!) trick ends up being used by most of the submissions… We encourage you to dive into the different methods to perform this assignment, and find your own solution!

What to submit and how to submit it

You must hand in one ZIP containing:

  1. the code (several files possible) you wrote to do the assignment.
  2. a report in PDF format (not in Microsoft Word please)

The name of the file consists of the studentIDs of the members separated by a “_”, for example 5015199_4018169_4123169.zip.

The structure of the ZIP should be:

5015199_4018169_4123169.zip/
  |-- src/
      |-- main.cpp
      |-- definitions.h
      |-- geomtools.h
      |-- geomtools.cpp
      |-- ... (you can add more here)
  |-- include/
      |-- json.hpp
  |-- report/
      |-- report.pdf
  |-- CMakeList.txt

Do not submit your assignment by email, but use this surfdrive link.

[last updated: 2023-03-02 08:53]