Working with 3D city models in Python

Balázs Dukai @BalazsDukai, FOSS4G 2019

Tweet #CityJSON

3D geoinformation research group, TU Delft, Netherlands

Repo of this talk: https://github.com/balazsdukai/foss4g2019

3D + city + model ?

Probably the most well known 3d city model is what we see in Google Earth. And it is a very nice model to look at and it is improving continuously. However, certain applications require more information than what is stored in such a mesh model. They need to know what does an object in the model represent in the real world.

Semantic models

That is why we have semantic models, where for each object in the model we store a label of is meaning. Once we have labels on the object and on their parts, data preparation becomes more simple. An important property for analytical applications, such as wind flow simulations.

Useful for urban analysis

García-Sánchez, C., van Beeck, J., Gorlé, C., Predictive Large Eddy Simulations for Urban Flows: Challenges and Opportunities, Building and Environment, 139, 146-156, 2018.

But we can do much more with 3d city models. We can use them to better estimate the energy consumption in buildings, simulate noise in cities or analyse views and shadows. In the Netherlands sunshine is precious commodity, so we like to get as much as we can.

And many more...

There are many open 3d city models available. They come in different formats and quality. However, at our group we are still waiting for the "year of the 3d city model" to come. We don't really see mainstream use, apart of visualisation. Which is nice, I belive they can provide much more value than having a nice thing to simply look at.

...mostly just production of the models

many available, but who uses them? For more than visualisation?

In truth, 3D CMs are a bit difficult to work with

Our built environment is complex, and the objects are complex too

Software are lagging behind

• not many software supports 3D city models

• if they do, mostly propietary data model and format

• large, "eterprise"-type applications (think Esri, FME, Bentley ... )

• few tools accessible for the individual developer / hobbyist

That is why we are developing CityJSON, which is a data format for 3d city models. Essentially, it aims to increase the value of 3d city models by making it more simple to work with them and lower the entry for a wider audience than cadastral organisations.

Key concepts of CityJSON

• simple, as in easy to implement
• designed with programmers in mind
• fully developed in the open
• flattened hierarchy of objects
• implementation first

CityJSON implements the data model of CityGML. CityGML is an international standard for 3d city models and it is coupled with its GML-based encoding.

We don't really like GML, because it's verbose, files are deeply nested and large (often several GB). And there are many different ways to do one thing.

Also, I'm not a web-developer, but I would be surprised if anyone prefers GML over JSON for sending stuff around the web.

JSON-based encoding of the CityGML data model

Compression ~6x over CityGML

If you are interested in a more detailed comparison between CityGML and CityJSON you can read our article, its open access.

And yes, we are guilty of charge.

https://xkcd.com/927/

Let's have a look-see, shall we?

Now let's take a peek under the hood, what's going on in a CityJSON file.

An empty CityJSON file

In a city model we represent the real-world objects such as buildings, bridges, trees as different types of CityObjects. Each CityObject has its

• unique ID,
• attributes,
• geometry,
• and it can have children objects or it can be part of a parent object.

Note however, that CityObject are not nested. Each of them is stored at root and the hierachy represented by linking to object IDs.

A CityObject

Each CityObject has a geometry representation. This geometry is composed of boundaries and semantics.

Geometry

• boundaries definition uses vertex indices (inspired by Wavefront OBJ)
• We have a vertex list at the root of the document
• Vertices are not repeated (unlike Simple Features)
• semantics are linked to the boundary surfaces

import json
import os

path = os.path.join('data', 'rotterdam_subset.json')
with open(path) as fin:
    cm = json.loads(fin.read())
    
print(f"There are {len(cm['CityObjects'])} CityObjects")

# list all IDs
for id in cm['CityObjects']:
    print(id, "\t")

There are 16 CityObjects
{C9D4A5CF-094A-47DA-97E4-4A3BFD75D3AE} 	
{71B60053-BC28-404D-BAB9-8A642AAC0CF4} 	
{6271F75F-E8D8-4EE4-AC46-9DB02771A031} 	
{DE77E78F-B110-43D2-A55C-8B61911192DE} 	
{19935DFC-F7B3-4D6E-92DD-C48EE1D1519A} 	
{953BC999-2F92-4B38-95CF-218F7E05AFA9} 	
{8D716FDE-18DD-4FB5-AB06-9D207377240E} 	
{C6AAF95B-8C09-4130-AB4D-6777A2A18A2E} 	
{72390BDE-903C-4C8C-8A3F-2DF5647CD9B4} 	
{8244B286-63E2-436E-9D4E-169B8ACFE9D0} 	
{87316D28-7574-4763-B9CE-BF6A2DF8092C} 	
{CD98680D-A8DD-4106-A18E-15EE2A908D75} 	
{64A9018E-4F56-47CD-941F-43F6F0C4285B} 	
{459F183A-D0C2-4F8A-8B5F-C498EFDE366D} 	
{237D41CC-991E-4308-8986-42ABFB4F7431} 	
{23D8CA22-0C82-4453-A11E-B3F2B3116DB4} 	

• Working with a CityJSON file is straightforward. One can open it with the standard library and get going.
• But you need to know the schema well.
• And you need to write everything from scratch.

That is why we are developing cjio.

cjio is how we eat what we cook

Aims to help to actually work with and analyse 3D city models, and extract more value from them. Instead of letting them gather dust in some governmental repository.

cjio has a (quite) stable CLI

$ cjio city_model.json reproject 2056 export --format glb /out/model.glb

and an experimental API

from cjio import cityjson

cm = cityjson.load('city_model.json')

cm.get_cityobjects(type='building')

pip install cjio

This notebook is based on the develop branch.

pip install git+https://github.com/tudelft3d/cjio@develop

cjio's CLI

! cjio --help

Usage: cjio [OPTIONS] INPUT COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...

  Process and manipulate a CityJSON file, and allow different outputs. The
  different operators can be chained to perform several processing in one
  step, the CityJSON model goes through the different operators.

  To get help on specific command, eg for 'validate':

      cjio validate --help

  Usage examples:

      cjio example.json info validate
      cjio example.json assign_epsg 7145 remove_textures export output.obj
      cjio example.json subset --id house12 save out.json

Options:
  --version                Show the version and exit.
  --ignore_duplicate_keys  Load a CityJSON file even if some City Objects have
                           the same IDs (technically invalid file)
  --help                   Show this message and exit.

Commands:
  assign_epsg                Assign a (new) EPSG.
  clean                      Clean = remove_duplicate_vertices +...
  compress                   Compress a CityJSON file, ie stores its...
  decompress                 Decompress a CityJSON file, ie remove the...
  export                     Export the CityJSON to another format.
  extract_lod                Extract only one LoD for a dataset.
  info                       Output info in simple JSON.
  locate_textures            Output the location of the texture files.
  merge                      Merge the current CityJSON with others.
  partition                  Partition the city model into tiles.
  remove_duplicate_vertices  Remove duplicate vertices a CityJSON file.
  remove_materials           Remove all materials from a CityJSON file.
  remove_orphan_vertices     Remove orphan vertices a CityJSON file.
  remove_textures            Remove all textures from a CityJSON file.
  reproject                  Reproject the CityJSON to a new EPSG.
  save                       Save the city model to a CityJSON file.
  subset                     Create a subset of a CityJSON file.
  translate                  Translate the file by its (-minx, -miny,...
  update_bbox                Update the bbox of a CityJSON file.
  update_textures            Update the location of the texture files.
  upgrade_version            Upgrade the CityJSON to the latest version.
  validate                   Validate the CityJSON file: (1) against its...

! cjio data/rotterdam_subset.json info

Parsing data/rotterdam_subset.json
{
  "cityjson_version": "1.0",
  "epsg": 7415,
  "bbox": [
    90454.18900000001,
    435614.88,
    0.0,
    91002.41900000001,
    436048.217,
    18.29
  ],
  "transform/compressed": true,
  "cityobjects_total": 16,
  "cityobjects_present": [
    "Building"
  ],
  "materials": false,
  "textures": true
}

! cjio data/rotterdam_subset.json \
    subset --exclude --id "{CD98680D-A8DD-4106-A18E-15EE2A908D75}" \
    merge data/rotterdam_one.json \
    reproject 2056 \
    save data/test_rotterdam.json

Parsing data/rotterdam_subset.json
Subset of CityJSON
Merging files
Reproject to EPSG:2056
  [####################################]  100%          
Saving CityJSON to a file /home/balazs/Reports/talk_cjio_foss4g_2019/data/test_rotterdam.json

• The CLI was first, no plans for API

• Works with whole city model only

• Functions for the CLI work with the JSON directly, passing it along

• Simple and effective architecture

cjio's API

Allow read --> explore --> modify --> write iteration

Work with CityObjects and their parts

Functions for common operations

Inspired by the tidyverse from the R ecosystem

Load a CityJSON

path = os.path.join('data', 'rotterdam_subset.json')

cm = cityjson.load(path)

print(type(cm))

<class 'cjio.cityjson.CityJSON'>

Getting objects from the model

Get CityObjects by their type, or a list of types. Also by their IDs.

Note that get_cityobjects() == cm.cityobjects

buildings = cm.get_cityobjects(type='building')

# both Building and BuildingPart objects
buildings_parts = cm.get_cityobjects(type=['building', 'buildingpart'])

r_ids = ['{C9D4A5CF-094A-47DA-97E4-4A3BFD75D3AE}',
         '{6271F75F-E8D8-4EE4-AC46-9DB02771A031}']
buildings_ids = cm.get_cityobjects(id=r_ids)

Vertex coordinates are kept 'as is' on loading the geometry. CityJSON files are often compressed and coordinates are shifted and transformed into integers so probably you'll want to transform them back. Otherwise geometry operations won't make sense.

But it might be easier to transform (decompress) the whole model on load.

Analysing CityModels

In the following I show how to compute some attributes from CityObject geometry and use these attributes as input for machine learning. For this we use the LoD2 model of Zürich.

Download the Zürich data set from https://3d.bk.tudelft.nl/opendata/cityjson/1.0/Zurich_Building_LoD2_V10.json

path = os.path.join('data', 'zurich.json')
zurich = cityjson.load(path, transform=True)

A simple geometry function

Here is a simple geometry function that computes the area of the groundsurface (footprint) of buildings in the model. It also show how to cast surfaces, in this case the ground surface, to Shapely Polygons.

def compute_footprint_area(co):
    """Compute the area of the footprint"""
    footprint_area = 0
    for geom in co.geometry:
        
        # only LoD2 (or higher) objects have semantic surfaces
        if geom.lod >= 2.0:
            footprints = geom.get_surfaces(type='groundsurface')
            
            # there can be many surfaces with label 'groundsurface'
            for i,f in footprints.items():
                for multisurface in geom.get_surface_boundaries(f):
                    for surface in multisurface:
                        
                        # cast to Shapely polygon
                        shapely_poly = Polygon(surface)
                        footprint_area += shapely_poly.area
                        
    return footprint_area

Compute new attributes

Then we need to loop through the CityObjects and update add the new attributes. Note that the attributes CityObject attribute is just a dictionary.

Thus we compute the number of vertices of the CityObject and the area of is footprint. Then we going to cluster these two variables. This is completely arbitrary excercise which is simply meant to illustrate how to transform a city model into machine-learnable features.

for co_id, co in zurich.cityobjects.items():
    co.attributes['nr_vertices'] = len(co.get_vertices())
    co.attributes['fp_area'] = compute_footprint_area(co)
    zurich.cityobjects[co_id] = co

df = zurich.to_dataframe()
df.head()

	creationDate	Geomtype	nr_vertices	fp_area	class	Herkunft	QualitaetStatus	FileCreationDate	Region	GebaeudeStatus
UUID_93fc5bae-4446-4336-9ff8-6679ebfdfde3	2017-01-23	1.0	24	65.209763	NaN	NaN	NaN	NaN	NaN	NaN
UUID_c9884c4e-1cac-47f5-b88b-6fb074c0ae50	2017-01-23	NaN	0	0.000000	BB01	EE_LB_2007	1.0	2012-02-23	2.0	1.0
UUID_a4a09780-153f-4385-ad19-3a92a6c4eec4	2017-01-23	1.0	38	20.784309	NaN	NaN	NaN	NaN	NaN	NaN
UUID_ba0bb815-5276-4e35-b4c1-878cbf6ba934	2017-01-23	NaN	0	0.000000	BB07	EE_LB_2007	1.0	2012-02-23	2.0	1.0
UUID_bb1835bc-7437-453f-ac08-885de0503aaa	2017-01-23	1.0	87	69.363823	NaN	NaN	NaN	NaN	NaN	NaN

In order to have a nicer distribution of the data, we remove the missing values and apply a log-transform on the two variables. Note that the FuntionTransformer.transform transforms a DataFrame to a numpy array that is ready to be used in scikit-learn. The details of a machine learning workflow is beyond the scope of this tutorial however.

Since we transformed our DataFrame, we can fit any model in scikit-learn. I use DBSCAN because I wanted to find the data points on the fringes of the central cluster.

%matplotlib notebook
model = cluster.DBSCAN(eps=0.2).fit(df_logtransform)

plot_model_results(model, df_logtransform)

Save the results back to CityJSON

And merge the DataFrame with cluster labels back to the city model.

for co_id, co in zurich.cityobjects.items():
    if co_id in df_subset.index:
        ml_results = dict(df_subset.loc[co_id])
    else:
        ml_results = {'nr_vertices': 'nan', 'fp_area': 'nan', 'dbscan': 'nan'}
    new_attrs = {**co.attributes, **ml_results}
    co.attributes = new_attrs
    zurich.cityobjects[co_id] = co

path_out = os.path.join('data', 'zurich_output.json')
cityjson.save(zurich, path_out)

And view the results in QGIS again

However, you'll need to set up the styling based on the cluster labels by hand.

Other software

Online CityJSON viewer

QGIS plugin

Azul

Full conversion CityGML <--> CityJSON

Thank you!

Balázs Dukai

b.dukai@tudelft.nl

@BalazsDukai

A few links

Repo of this talk: https://github.com/balazsdukai/foss4g2019

cityjson.org

viewer.cityjson.org

QGIS plugin: github.com/tudelft3d/cityjson-qgis-plugin

Azul – CityJSON viewer on Mac – check the AppStore

cjio: github.com/tudelft3d/cjio & tudelft3d.github.io/cjio/