3D City Database (for PostgreSQL)

Quick installation guide

Giorgio Agugiaro

Last update: 1 August 2023

 License

This presentation is licensed under the Creative Commons License CC

BY-NC-SA 4.0. According to CC BY-NC-SA 4.0 permission is granted to
share this document, i.e. copy and redistribute the material in any
medium or format, and to adapt it, i.e. remix, transform, and build
upon the material under the following conditions:

• Attribution: You must give appropriate credit, provide a link to the license, and indicate if
changes were made. You may do so in any reasonable manner, but not in any way that suggests
the licensor endorses you or your use.
• NonCommercial: You may not use the material for commercial purposes.
• ShareAlike: If you remix, transform, or build upon the material, you must distribute your
contributions under the same license as the original.
• No additional restrictions: You may not apply legal terms or technological measures that legally
restrict others from doing anything the license permits.

2
 Overview

Connect to the
Install required Set up the
database via the
software database
Importer/Exporter

Add additional
Install ADE plug-ins
database schemas
(Optional)
(Optional)

3
 Overview

Connect to the
Install required Set up the
database via the
software database
Importer/Exporter

Add additional
Install ADE plug-ins
database schemas
(Optional)
(Optional)

4
 Software requirements
• Java 11 JDK or higher
– https://www.oracle.com/java/technologies/javase/jdk11-archive-downloads.html
Software required • PostgreSQL (e.g. v. 12.x) + PostGIS (e.g. v. 3.x) + PgAdmin 4 (e.g. v. 6.x)
Software install – https://www.postgresql.org/download/
Database setup
Further resources – https://postgis.net/install/ (generally already installed with PostgreSQL)
– https://www.pgadmin.org/download/ (generally already installed with PostgreSQL)
• CityGML 3D City Database Suite
– https://github.com/3dcitydb/3dcitydb-suite/releases
• Google Earth Pro (optional, only if you want to export to kml/Collada)
– https://www.google.com/earth/versions/#download-pro
• NodeJS (optional, needed only if you want to use the Web-map-client)
– https://nodejs.org/en/

5
 Software installation order
1) Install Java (if not yet installed)

Software required 2) Install PostgreSQL

Software install
– Install PostGIS (generally installed together with PostgreSQL, see next slides)
Database setup
Further resources – Install PgAdmin (generally installed together with PostgreSQL, see next slides)

3) Install the 3DCityDB suite

– Execute the .jar file, it will start the installation process

4) Install Google Earth (optional)

5) Install NodeJS (optional)

6
 PostgreSQL
• RECOMMENDED: Install PostgreSQL on your computer using the automatic installer
(Stack builder).
Software required
Software install
• Java
• PostgreSQL
• PgAdmin/PostGIS
• 3DCityDB
• Google Earth
• NodeJS
Database setup
Imp/Exp connection
Additional schemas
ADE plug-ins

• Please take care to:

– Properly set a password for your postgres user. The postgres user is the administrator of the
PostgreSQL database cluster. Do not lose the password!!
– You can generally set the default port of PostgreSQL to 5432.
7
 PgAdmin / PostGIS
• PGAdmin4 is generally installed by default, no need to do anything
• The Stack builder application allows you to install also other applications, such as
Software required PostGIS and (optionally) a webserver (here: PEM)
Software install
• Java
• PostgreSQL
• PgAdmin/PostGIS
• 3DCityDB
• Google Earth
• NodeJS
Database setup
Imp/Exp connection
Additional schemas
ADE plug-ins

8
 3DCityDB
NOTA BENE: The detailed installation guide can be found here:
https://3dcitydb-docs.readthedocs.io/en/latest/
Software required In the following slides, only the main points are presented
Software install
• Java
• PostgreSQL 1) Install the 3D City Database Suite
• PgAdmin/PostGIS
• 3DCityDB – If you want to install it in the program files directory (e.g. C:\Program Files\3DCityDB-Importer-
• Google Earth Exporter) you must make that directory writable by everybody (i.e. not only by the
• NodeJS administrator!)
Database setup – Alternatively, you can install the 3DcityDB in any other directory where you have writing
Imp/Exp connection privileges
Additional schemas
– At the end, you should have the icon of the Importer/Exporter on your desktop (or start menu)
ADE plug-ins

2) Launch the Importer/Exporter just to test whether it starts correctly

9
 Overview

Connect to the
Install required Set up the
database via the
software database
Importer/Exporter

Add additional
Install ADE plug-ins
database schemas
(Optional)
(Optional)

10
 Database setup
Procedure overview

Software required 1) In PostgreSQL (via the PgAdmin GUI)

Software install – Connect to the PostgreSQL server
Database setup – Create a new empty database that will contain your 3D city model data
Imp/Exp connection – Add the extensions for PostGIS, PostGIS-raster, etc.
Additional schemas
– See the next slides for details
ADE plug-ins

2) From the 3DCityDB installation folder

– Edit the CONNECTION_DETAILS.bat file and run the CREATEDB script to create the tables (and
other objects) in the database you have created in the previous step
– See the next slides for details

3) Connect to the database (e.g. via PgAdmin) just to check that you created the tables

4) Connect to the database from the 3DCityDB Importer/Exporter

11
 Connecting to the database
• AFTER you have successfully installed PostgreSQL, you can access the database server
via PgAdmin
Software required ALTERNATIVELY
Software install
Database setup • You do not have PostgreSQL installed on your own computer, but you know the
• Database
connection connection parameters to connect to a remote server
• Database creation
• Create tables etc.
• Check via PgAdmin
Imp/Exp connection • In both cases, you will need information about:
Additional schemas
– Server name or IP address ("localhost" if it is on your computer)
ADE plug-ins
– Database name (generally "postgres" if it is on your computer)
– Port (generally 5432 if it is on your computer)
– Username, Password (e.g. the ones created before if it is on your computer)

12
 Connecting to the database from PgAdmin
• Create a (link to the) database server
– You are actually creating a connection to the database server from PgAdmin
Software required – Click on menu Object\Create\Server OR right mouse-click\Create\Server and fill out the fields
Software install – Please note: this step may not be required if you already have a server connection established
Database setup
• Database
connection
• Database creation
• Create tables etc. In the "General" tab, you
• Check via PgAdmin simply add a name to
Imp/Exp connection identify your connection
Additional schemas
Here, FOR EXAMPLE, the
ADE plug-ins
string is "PostgreSQL-12
on my PC"

13
 Connecting to the database from PgAdmin
• Create a (link to the) database server
– You are actually creating a connection to the database server from PgAdmin
Software required – Click on menu Object\Create\Server OR right mouse-click\Create\Server and fill out the fields
Software install – Please note: this step may not be required if you already have a server connection established
Database setup
• Database
connection
• Database creation
• Create tables etc.
• Check via PgAdmin
Imp/Exp connection
Additional schemas
ADE plug-ins In the "Connection" tab,
you add the connection
parameters
• Host name / IP address
• Port
• Database name
• Username
• Password

14
 Database creation
• Once you have created a connection, you can create the database that will contain
your city mode data
Software required – Click on menu Object\Create\Database OR right mouse-click\Create\Database and fill out the
Software install fields
Database setup – Choose the name you want,
• Database connection ideally the name of the city
• Database creation
• Create tables etc.
• Check via PgAdmin
Imp/Exp connection
Additional schemas
ADE plug-ins
Here, for example, it is "alderaan", but
you can choose any name you want

Best if you use only small letters!

15
 Database creation

1
Software required 3
Software install
Database setup
• Database connection
• Database creation
• Create tables etc.
• Check via PgAdmin 2
Imp/Exp connection
Add PostGIS (and othe extensions) to the database you have just created
Additional schemas
ADE plug-ins 1) Open a SQL query window
2) Copy and paste the text written in the yellow box into the query window
3) Run the query

CREATE EXTENSION IF NOT EXISTS postgis SCHEMA public;

CREATE EXTENSION IF NOT EXISTS postgis_raster SCHEMA public;
CREATE EXTENSION IF NOT EXISTS postgis_sfcgal SCHEMA public;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp" SCHEMA public;
16
 Database creation
• Check that you have correctly installed the extensions in your database
– Open "Extensions" item in your database (e.g. "alderaan")
Software required – Check that the extensions are listed there (the "plpgsql" one is installed by default)
Software install
Database setup
• Database connection
• Database creation
• Create tables etc.
• Check via PgAdmin
Imp/Exp connection
Additional schemas
ADE plug-ins

17
 Create tables and other database objects
NOTA BENE: The detailed installation guide can be found here:
https://3dcitydb-docs.readthedocs.io/en/latest/first-steps/index.html
Software required In the following slides, only the main points are presented
Software install
Database setup
• Database connection • Go to the 3DCityDB installation folder and look for the
• Database creation
• Create tables etc.
3dcitydb\postgresql\ShellScrips directory. It should look like in the next slides
• Check via PgAdmin – Open the CONNECTION_DETAILS.bat file in a text editor and insert your PostgreSQL connection
Imp/Exp connection details
Additional schemas – Run the CREATEDB script (for Windows and Unix in the corresponding subfolders)
ADE plug-ins

18
 Create tables and other database objects

Software required
Software install
Database setup
• Database connection
• Database creation
• Create tables etc.
• Check via PgAdmin
Imp/Exp connection
Additional schemas
ADE plug-ins

19
 Create tables and other database objects

Software required
Software install
Database setup
• Database connection

}
• Database creation Adapt the file using your database
• Create tables etc. connection parameters
• Check via PgAdmin
When you are done, save the file.
Imp/Exp connection
Additional schemas • The PGBIN variable contains the path to the psql executable (e.g. psql.exe). Depending on your PostgreSQL
ADE plug-ins installation, it could be in other (but similar) locations.
• PGHOST is the IP address of the PostgreSQL server. If you are using the database on your own computer, you can
write "localhost", otherwise you have to write the IP address of the server
• PGPORT is the port PostgreSQL is listening to. Generally, it is 5432 (this is the default value).
• CITYDB contains the name of the database that you have created before (see slide 6) and that will contain the
3DCityDB tables, e.g. "alderaan"
• PGUSER contains the name of the user to connect to the database. On your local machine, you may use postgres.
You will be asked the password during the installation process later

20
 Create tables and other database objects
Find out the EPSG codes that apply to your city/region. Here some examples:

Software required • Netherlands

Software install
– Horizontal datum EPSG: 28992
Database setup
• Database connection – Vertical datum EPSG: 5109
• Database creation – (Will automatically create the GMLSrsName: urn:ogc:def:crs,crs:EPSG::28992,crs:EPSG:5109)
• Create tables etc.
• Check via PgAdmin • Trento (Italy)
Imp/Exp connection – Horizontal datum EPSG: 25832
Additional schemas – Vertical datum EPSG: 5214
ADE plug-ins
– (Will automatically create the GMLSrsName: urn:ocg:def:crs,crs:EPSG::25832,crs:EPSG::5214)
• Vienna (Austria)
– Horizontal datum EPSG: 31256
– Vertical datum EPSG: 1267
– (Will automatically create the GMLSrsName: urn:ocg:def:crs,crs:EPSG::31256,crs:EPSG::1267)

21
 Create tables and other database objects
• Run the batch file CREATE_DB and set the EPSG codes for horizontal and vertical datum, as
shown in the image here
Software required
Software install
Database setup
• Database connection
• Database creation
• Create tables etc.
• Check via PgAdmin
Imp/Exp connection
Additional schemas
ADE plug-ins

• Then press enter, the GMLSRSNAME variable will be automatically generated (accept the
proposed value) and the install script will start and install all tables etc.
22
 Create tables and other database objects
• Upon successful installation, you should get something like this

Software required
Software install
Database setup
• Database connection
• Database creation
• Create tables etc.
• Check via PgAdmin
Imp/Exp connection
Additional schemas
ADE plug-ins

23
 Check via PgAdmin
• Open PgAdmin and check that the citydb and citydb_pkg schemas are there. The
citydb schema should contain 66 tables
Software required
Software install
Database setup
• Database connection
• Database creation
• Create tables etc.
• Check via PgAdmin
Imp/Exp connection
Additional schemas
ADE plug-ins

24
 Overview

Connect to the
Install required Set up the
database via the
software database
Importer/Exporter

Add additional
Install ADE plug-ins
database schemas
(Optional)
(Optional)

25
 Connecting to the database via Importer/Exporter
• AFTER you have successfully installed PostgreSQL, you can access the database server
via PgAdmin
Software required ALTERNATIVELY
Software install
Database setup • You do not have PostgreSQL installed on your own computer, but you know the
• Database connection
• Database creation connection parameters to connect to a remote server
• Create tables etc.
• Check via PgAdmin
Imp/Exp
connection • In both cases, you will need information about:
Additional schemas – Server name or IP address ("localhost" if it is on your computer)
ADE plug-ins
– Database name (generally "postgres" if it is on your computer)
– Port (generally 5432 if it is on your computer)
– Username, Password (e.g. the ones created before if it is on your computer)

26
 Connecting to the database via Importer/Exporter
• Launch the 3DCityDB Importer/Exporter, select the "Database" tab
– The Description field contains a simple string to identify the connection
Software required – Fill out the remaining fields with the connection parameters
Software install – Click on Connect
Database setup
• Database connection
• Database creation
• Create tables etc.
• Check via PgAdmin
Imp/Exp
connection
Additional schemas
ADE plug-ins

27
 Connecting to the database via Importer/Exporter
• Launch the 3DCityDB Importer/Exporter, select the "Database" tab
– Upon successful connection, you will see the notification in the console
Software required
Software install
Database setup
• Database connection
• Database creation
• Create tables etc.
• Check via PgAdmin
Imp/Exp
connection
Additional schemas
ADE plug-ins

28
 Connecting to the database via Importer/Exporter
• Launch the 3DCityDB Importer/Exporter, select the "Database" tab
– You can optionally also Generate a database report
Software required – If starting from an empty database, it will simply show that all tables are empty! ☺
Software install
Database setup
• Database connection
• Database creation
• Create tables etc.
• Check via PgAdmin
Imp/Exp
connection
Additional schemas
ADE plug-ins
In this example, the database
is empty, so all tables have 0
(zero) records!

29
 Overview

Connect to the
Install required Set up the
database via the
software database
Importer/Exporter

Add additional
Install ADE plug-ins
database schemas
(Optional)
(Optional)

30
 3D City Database: additional schemas
• To add additional schemas (OPTIONAL, besides the
default citydb):
Software required – Check the connection parameters in file
Software install CONNECTION_DETAILS.bat (should be the same as
Database setup before)
• Database connection – Run the CREATE_SCHEMA script. You will be requested
• Database creation
to enter the name of the additional schema (e.g.
• Create tables etc.
• Check via PgAdmin "citydb_a1", or "scenario_1", etc.)
Imp/Exp connection – You can choose any name you want, but try to use only
Additional small letters
schemas – The new schema and its contents will be added
ADE plug-ins automatically. The new schema will have the same CRS
of the citydb schema
– You can repeat these steps and add more schemas to
the same database. At the end you will have
• The citydb schema and n additional schemas
• Only one citydb_pkg schema

31
 3D City Database: additional schemas
• When using the Importer/Exporter, you can choose which schema to use to
import/export data from the GUI.
Software required
Software install
Database setup
• Database connection
• Database creation
• Create tables etc.
• Check via PgAdmin
Imp/Exp connection
Additional
schemas
ADE plug-ins

32
 Overview

Connect to the
Install required Set up the
database via the
software database
Importer/Exporter

Add additional
Install ADE plug-ins
database schemas
(Optional)
(Optional)

33
34
ADE plug-in installation
Please note: These slides refer to the Energy ADE
plug-in for the 3DCityDB. However, a similar
Software required procedure can be followed for other ADE plug-ins.
Software install
Database setup
Imp/Exp connection 1) Download the energy-ade-citydb extension
Additional schemas for the Importer/Exporter
ADE plug-ins – https://github.com/3dcitydb/energy-ade-
• Installation citydb/releases/
• Data import
• Data export
2) Unzip it in folder ade-extensions of your
3DCityDB install path

Detailed instructions available on-line

• https://3dcitydb-docs.readthedocs.io/en/latest/plugins/ade-manager/index.html
34
35
ADE plugin installation
• From the Importer/Exporter, connect to an existing 3DCityDB instance
– In the "ADE extension package" add the path to the plug-in folder unzipped before
Software required – "Register" the ADE from the ADE Manager tab
Software install – The ADE will be added to the ADE list (and all tables, etc. will be added to the current schema)
Database setup
Imp/Exp connection
Additional schemas
ADE plug-ins
• Installation
• Data import
• Data export

35
36
ADE plugin installation
• Check also in the database tab the ADEs properties

Software required
Software install
Database setup
Imp/Exp connection
Additional schemas
ADE plug-ins
• Installation
• Data import
• Data export

36
37
ADE plugin installation
• Check in PgAdmin: new tables (and functions) with prefix "ng" have been added

Software required
Software install
Database setup
Imp/Exp connection
Additional schemas
ADE plug-ins
• Installation
• Data import
• Data export The prefix depends on the ADE!

For example, the prefix "ng" is

used here for the Energy ADE

37
38
ADE data import
• To import ADE data into the extended 3DCityDB, the procedure is the same as with
non-ADE data via the Import tab
Software required
Software install
Database setup
Imp/Exp connection
Additional schemas
ADE plug-ins
• Installation
• Data import
• Data export

38
39
ADE data import
• To import ADE data into the extended 3DCityDB, the procedure is the same as with
non-ADE data via the Import tab
Software required
Software install
Database setup
Imp/Exp connection
Additional schemas
ADE plug-ins
• Installation
• Data import
• Data export

39
40
ADE data import
• Check also the database report in the database tab!

Software required
Software install
Database setup Records added
Imp/Exp connection (also) to the ng_*
Additional schemas tables
ADE plug-ins
• Installation
• Data import
• Data export

40
41
ADE data export
• Conceptually analogous to the procedure without ADE content. Simply choose what
to export, and run the exporter!
Software required
Software install
Database setup
Imp/Exp connection
Additional schemas
ADE plug-ins
• Installation
• Data import
• Data export

41
 Further resources
• Fur further information, check the official 3DCityDB documentation regarding the
installation procedure details
Software required
PostgreSQL • Online documentation
3DCityDB
– https://3dcitydb-docs.readthedocs.io/en/latest/
Further resources

• Online tutorial by TU Munich

– https://github.com/3dcitydb/tutorials

42
 Thank you for your attention!

Dr. Giorgio Agugiaro

[email protected]
3D Geoinformation Group
TU Delft
The Netherlands
https://3d.bk.tudelft.nl/gagugiaro

43