3d city database for citygml · 3d city database for citygml 3d city database version 2.0.2 to...

3D City Database for CityGML

3D City Database Version 2.0.2 to 2.1.0

Importer/Exporter Version 1.3.0 to 1.6.0

Addendum to the

3D City Database Documentation Version 2.0.1

12 September 2013

2 Documentation of the 3D City Database v2.1.0 and the Importer/Exporter v1.6.0

Participants in development

Name Institution Email

Thomas H. Kolbe

Zhihang Yao

Faculty of Civil, Geo and Environmental

Engineering, Technische Universität München

[email protected]

[email protected]

Javier Herreruela Institute for Geodesy and Geoinformation Science,

Technische Universität Berlin

[email protected]

Claus Nagel

Felix Kunde

virtualcitySYSTEMS GmbH, Berlin [email protected]

[email protected]

Philipp Willkomm

György Hudra

M.O.S.S. Computer Grafik Systeme GmbH,

Taufkirchen, Germany

[email protected]

[email protected]

Documentation of the 3D City Database v2.1.0 and the Importer/Exporter v1.6.0 3

Content

1 DISCLAIMER ..................................................................................................... 5

2 OVERVIEW ........................................................................................................ 7

3 CHANGES IN 3D CITY DATABASE CONTENTS ............................................ 9

3.1 ENVELOPE in CITYOBJECT Table ....................................................................... 9

4 NEW FEATURES ............................................................................................ 11

4.1 Graphical Bounding Box Choice Window ............................................................ 11

4.2 Plugin API ............................................................................................................. 18

4.3 KML/COLLADA Export ........................................................................................ 20

4.3.1 Main parameters of the KML/COLLADA export ..................................... 23

4.3.2 Preferences ................................................................................................. 28

4.3.2.1 General Preferences ..................................................................... 28

4.3.2.2 Rendering Preferences ................................................................. 31

4.3.2.3 Information Balloon Preferences ................................................. 35

4.3.2.4 Altitude/Terrain Preferences ....................................................... 43

4.3.3 Batch mode ................................................................................................ 48

4.3.4 Loading exported models in Google Earth ................................................ 48

4.3.5 General setting recommendations ............................................................. 49

4.4 Support for Coordinate Reference Systems (CRS) ................................................ 51

4.4.1 General information ................................................................................... 51

4.4.2 Definition of the CRS for a 3D City Database instance ............................ 51

4.4.3 Management of user-defined CRSs ........................................................... 52

4.4.4 Usage of user-defined CRSs ...................................................................... 55

4.4.5 Support for 3D CRS .................................................................................. 57

4.4.6 Support for Point and Line Geometries of GenericCityObjects ................ 59

4.5 CityGML Import Enhancements ............................................................................ 61

4.5.1 Address storage.......................................................................................... 61

4.5.2 Affine Coordinate Transformation ............................................................ 63

4.5.3 Indexes ....................................................................................................... 66

4.5.4 XML Validation ........................................................................................ 66

4.6 CityGML Export Enhancements ............................................................................ 68

4.6.1 Coordinate Transformation ........................................................................ 68

4.6.2 CityGML version ....................................................................................... 70

4.6.3 Address data reconstruction ....................................................................... 70

4.6.4 Unique texture filenames ........................................................................... 73

4.6.5 Tiling ......................................................................................................... 74


4.7 Rework and Redesign of the Matching/Merging Tool ........................................... 77

4.8 Extensions to the Database tab and preferences ................................................... 80

4.9 Proxy support in preferences ................................................................................ 86

4.10 New PL/SQL functionality ..................................................................................... 88

4.10.1 PL/SQL package GEODB_DELETE ........................................................ 88

4.10.2 Creating Read-Only Users ......................................................................... 91

4.11 Test data and template files ................................................................................... 93

5 REQUIREMENTS ............................................................................................ 94

6 UPGRADE FROM PREVIOUS VERSIONS OF THE 3D CITY DATABASE ... 96

7 CHANGELOG ................................................................................................ 102

7.1 Changelog for the 3D City Database .................................................................. 102

7.2 Changelog for the Importer/Exporter ................................................................. 103

8 REFERENCES ............................................................................................... 107


1 Disclaimer

The 3D City Database and the Importer/Exporter developed by the Institute for Geodesy and

Geoinformation Science (IGG) at the Technische Universität Berlin is free software under the

GNU Lesser General Public License Version 3.0. See the file LICENSE shipped together with

the software for more details. For a copy of the GNU Lesser General Public License see the

files COPYING and COPYING.LESSER or visit http://www.gnu.org/licenses/.

THE SOFTWARE IS PROVIDED BY IGG "AS IS" AND "WITH ALL FAULTS." IGG

MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND CONCERNING

THE QUALITY, SAFETY OR SUITABILITY OF THE SOFTWARE, EITHER EXPRESSED

OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED WARRANTIES OF

MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-

INFRINGEMENT.

IGG MAKES NO REPRESENTATIONS OR WARRANTIES AS TO THE TRUTH,

ACCURACY OR COMPLETENESS OF ANY STATEMENTS, INFORMATION OR

MATERIALS CONCERNING THE SOFTWARE THAT IS CONTAINED ON AND

WITHIN ANY OF THE WEBSITES OWNED AND OPERATED BY IGG.

IN NO EVENT WILL IGG BE LIABLE FOR ANY INDIRECT, PUNITIVE, SPECIAL,

INCIDENTAL OR CONSEQUENTIAL DAMAGES HOWEVER THEY MAY ARISE AND

EVEN IF IGG HAVE BEEN PREVIOUSLY ADVISED OF THE POSSIBILITY OF SUCH

DAMAGES.


2 Overview

Welcome to the release of the 3D City Database version 2.1.0 and the Importer/Exporter

version 1.6.0. This document is an addendum to the previous documentation of the 3D City

Database version 2.0.1 (cf. [1]) and replaces all previous addenda of the Importer/Exporter.

Corrections and enhancements documented for those releases are also included in this guide

and are explicitly labeled by markers on the left margin stating the version they were introduced

with. The most recent changes brought by this release 1.6.0 are extra highlighted with a light

blue background. For a full overview of the 3D City Database and the Importer/Exporter please

also refer to the version 2.0.1 documentation (shipped with the distribution package of this

release as well). This is a minor release of the 3D City Database and the Importer/Exporter.

The next major release offering full support of the OGC CityGML 2.0.0 standard is scheduled

for the end of 2013.

Version 2.1.0 of the 3D City Database complements the GEODB_DELETE package with low-

level database procedures allowing for the deletion of all city objects as well as their geometries

and appearances. Previous releases were restricted to the removal of building features and their

components only. Version 1.6.0 of the Importer/Exporter provides performance improvements

and bug fixes.

The 3D City Database version 2.1.0 is not a mandatory dependency of the Importer/Exporter

version 1.6.0 which thus can still be used together with the previous version 2.0.6 of the

database. Nevertheless, existing 3D City Database instances of version 2.0.5 or below have

to be upgraded to version 2.0.6 / 2.1.0 in order to make use of the new features and

improvements. An upgrade script is shipped with this release. Please refer to chapter 6 for the

documentation of the upgrade procedure. If the 3D City Database instance is already running

version 2.0.6, an upgrade to version 2.1.0 is only required to benefit from the new DELETE

procedures.

Since release 1.4.0 (3D City Database 2.0.6) both the Importer/Exporter and the 3DCityDB are

no longer constrained to an Oracle Spatial installation but can alternatively work on top of a

PostgreSQL/PostGIS database. This is realized in the form of two separate software packages,

each of them specifically adapted for the database type they are intended to work with

(3DCityDB and Importer/Exporter for Oracle or 3DCityDB and Importer/Exporter for

PostgreSQL/PostGIS). The contents of these packages are not interchangeable, that is, the

3DCityDB scripts for Oracle must be executed on Oracle Spatial, the 3DCityDB scripts for

PostgreSQL/PostGIS on a PostgreSQL/PostGIS instance; the same applies for the

Importer/Exporter versions. Plugins (see 4.2) must also adhere to this principle. A unified

version of the Importer/Exporter supporting both spatial database systems will be addressed in

the next major release of the Importer/Exporter (scheduled for the end of 2013).

The functionality of both 3DCityDB and Importer/Exporter versions (Oracle or

PostgreSQL/PostGIS) is almost identical (the main exception being the history/workspace

management only supported by Oracle so far). This addendum and the version 2.0.1

documentation are therefore valid for both of them. PostgreSQL/PostGIS specific details as


well as some information about the software-porting process itself are collected and explained

in the extra documentation delivered with the PostgreSQL/PostGIS distribution package.

Further information, software downloads, ready-to-use demos, links to the source code

repository, and much more can be found at the official website of the 3D City Database at

http://www.3dcitydb.net.

Development efforts of the Importer/Exporter tool have been partially funded by the project

Digitaler Gestaltplan Potsdam carried out in 2010/2011 within the European Regional

Development Fund (ERDF) framework. Partners in this project were the City of Potsdam

(Germany) as well as the company virtualcitySYSTEMS GmbH (Berlin, Germany) who also

financially supported the development of the 3D City Database and the Importer/Exporter tool

beyond this project. Previous releases were additionally supported by the Berlin Partner GmbH

(Berlin, Germany) and the Berliner Senatsverwaltung für Wirtschaft, Technologie und Frauen

(Berlin, Germany). In 2013, the company M.O.S.S. Computer Grafik Systeme GmbH

(Taufkirchen, Germany) joined the 3D City Database project as active partner in development.

We thank all our partners for their kind support and for their provision of demonstration

datasets.

http://www.3dcitydb./


3 Changes in 3D City Database contents

3.1 ENVELOPE in CITYOBJECT Table

Due to compatibility issues with Oracle 11g versions, a small but significant adaption was made

on the contents of the table CITYOBJECT. It affects how the BoundingBox (column

ENVELOPE) is stored. The BoundingBox is realized by an Oracle data type

SDO_GEOMETRY, but from version 2.0.6 on this is no longer specified as a rectangle type

(SDO_INTERPRETATION = 3) using two opposite points, but as a simple 3D polygon

(SDO_GTYPE = 3003, SDO_ETYPE = 1003, SDO_INTERPRETATION = 1) using five

points, that join the minimum and maximum x, y and z coordinates of the BoundingBox and

define it completely. For backwards compatibility reasons (to Oracle 10g) the envelope cannot

be stored as a volume.

This means, with a practical example, the envelope of an object in version 2.0.5 of the 3D City

Database was stored as follows:

MDSYS.SDO_GEOMETRY(3003,32632,NULL,MDSYS.SDO_ELEM_INFO_ARRAY(1,1003,

3),MDSYS.SDO_ORDINATE_ARRAY(602158.6484,6102435.8133,14.22618,602167

.1064,6102442.3621,18.63145))

Since version 2.0.6, the envelope of the same object will be stored as:

MDSYS.SDO_GEOMETRY(3003,32632,NULL,MDSYS.SDO_ELEM_INFO_ARRAY(1,1003,

1),MDSYS.SDO_ORDINATE_ARRAY(602158.6484,6102435.8133,14.22618,602167

.1064,6102435.8133,14.22618,602167.1064,6102442.3621,18.63145,602158

.6484,6102442.3621,18.63145,602158.6484,6102435.8133,14.22618))

Please note that the maximum and minimum coordinate values remain unchanged, but now the

connection between them has become explicit. This is a consequence of changing the

SDO_INTERPRETATION value from 3 to 1.


Fig. 1: CityObject envelope storage in 2.0.5 (left: as a 3D rectangle specified by the two black points with

minimum and maximum coordinate values respectively) and in 2.0.6 (right: black polygon)

This new definition of how CityObject envelopes must be stored replaces the old one in 2.3.2.1

Core Model from the documentation of the 3D City Database Version 2.0.1 (cf. [1]).

This change is required to guarantee a flawless working of spatial queries under Oracle 11g,

like for CityGML or KML/COLLADA exports when applying a spatial BoundingBox filter.

Using the 3D City Database 2.0.5 package on Oracle 11g installations is strongly discouraged

since this can lead to repeated spatial query failures (with the Importer/Exporter or other tools).

The reason why the envelope is not simply stored as a volume results from the intended

backwards compatibility to Oracle 10g, which does not support 3D volumetric geometries (only

3D polygons).

The upgrade script to version 2.1.0 includes the adaption of all CityObject envelope values in

all workspaces automatically without requiring any interaction from the user on this topic.


4 New Features

4.1 Graphical Bounding Box Choice Window

A GUI component allowing for a better overview of the chosen BoundingBox (at the time of

choosing and afterwards) was added in release 1.4.0. The enhanced BoundingBox component

is present at the three main tabs: Import, Export, and KML/COLLADA Export and works

identically at all three.

Fig. 2: Enhanced BoundingBox component

The first noticeable difference to previous Importer/Exporter releases are the new icon buttons

on the top left corner whose functionality (also explained by a tooltip when the mouse is

hovering over) is from left to right: open map window to select a bounding box, copy bounding

box to clipboard and paste bounding box from clipboard.

When clicking on the open map window to select a bounding box icon button a new window

pops up showing a map of the selected bounding box in case the Xmin, Xmax, Ymin, Ymax

entries contain valid values or a world map with no selected area in case these entries are empty.

All map contents are provided by the OpenStreetMap service (no usage limits, internet

connection / network proxies, see chapter 4.9, must be properly configured).

The map window can also be opened from the main menu under the View element. In that case

the map window will show the area and values that were last used and will lack of the Apply

button on the upper right corner. Copying and pasting from and to the clipboard will continue

working though.


Fig. 3: Selected bounding box displayed graphically; coordinates are automatically calculated and transformed.

Regardless of the reference system used in the original bounding box, coordinates in the map

window will always be shown in WGS84. This is required by the OpenStreetMap service. In

case the given bounding box is not defined in this reference system a conversion must take

place. A connection to a database supporting the given reference system must be established in

order to convert the coordinates. If this is not yet the case a pop-up dialog will ask you for

permission.


Fig. 4: Asking for permission before connecting to a DB for coordinate conversion

Coordinates can be retrieved and set any time by means of the copy and paste graphic buttons

available on the map window and in the BoundingBox component present at the three main

tabs: Import, Export and KML/COLLADA Export. Exchange of these values always happens

through the clipboard.

The Apply button on the upper right corner of the map window is a shortcut for copying the

coordinate values to the clipboard and pasting them in the bounding box fields of the calling

tab. Furthermore, coordinate values can now be easily copied from one tab to another by simply

clicking on the Copy button in one of them, say Import tab, with filled bounding box values,

changing to another, say KML/COLLADA Export tab and clicking on the Paste button there.

Previously existing values in the bounding box fields of the KML/COLLADA Export tab (if any)

will be overwritten.


Fig. 5: World map is shown when no bounding box coordinate values are set

In case no bounding box is selected you can navigate to the area of interest or, more

comfortably, make use of the of the geocoding service included in the map window. Simply

type any address in the top left field and click on the Go button, you will be automatically

redirected to the first matching area containing this address.

The geocoding service, based on a Google API, is limited to 2500 requests per day and IP

address.

The currently shown map extent can also be opened in Google Maps for further inspection or

comparison by clicking on the Show in Google Maps button. This will open a new web browser

window showing the corresponding map view in Google Maps.


Fig. 6: Usage of the geocoding service

Once you are near the area of interest you can slide with the mouse (by holding the left button

down) to the exact position you are interested in. The mouse wheel is used for zooming in and

out of the map. A comprehensive list of usage hints is shown (and hidden) by clicking on the

link at the upper right map corner. These hints are:

Select bounding box: hold alt key and left mouse button to select bounding box. By

dragging the mouse while holding down the alt key and left mouse button the bounding

box is interactively displayed in a light magenta color over the map contents. Once the

left mouse button is released, the coordinates of the bounding box are automatically

filled in the fields left of the map. The procedure can be repeated any number of times

until the desired bounding box is selected. By clicking on the Apply button on the upper

right corner of the window, which has now become active, the window will be closed

and the bounding box values transferred to the clipboard and to the calling tab in the

main Importer/Exporter tool window.

Lookup address: click right mouse button to open popup menu. When the right mouse

button is clicked on a point of the map surface a context menu appears offering several

options. The last of them being Lookup address here. If this option is chosen, the point

will be highlighted by a green arrow and its address will be displayed on the column left

of the map (see Fig. 7). This information is supplied by a reverse geocoding service,

also based on a Google API and also limited to 2500 requests per day and IP address.


Zoom in/out: use mouse wheel.

Zoom into selected area: hold shift key and left mouse button to select area. Similarly

to Select bounding box, by dragging the mouse while holding down the shift key and

left mouse button a bounding box is interactively displayed in a light grey color over

the map contents. Once the left mouse button is released, the selected area will be zoom

in and fill the map window completely. This feature can be used to recursively come

closer to a zone whose coordinates are not precisely known but its topological properties

are. When the maximum zoom level is reached this action has no further effect.

Fig. 7: Reverse geocoding in the graphical bounding box choice window

Move map: hold left mouse button to move the map.

Center map and zoom in: double click left mouse button to center map. Double

clicking on any point of the map surface will increase the current zoom level one step

and set the exact clicked on point to be the center of the newly displayed area. When

the maximum zoom level is reached only the new centering will take place.

Use popup menu for further actions: click right mouse button to open popup menu.

The context menu triggered by a right mouse click offers additional access to some

functions, like Zoom in, Zoom out and Center map here for the case the mouse has no

wheel or does not support double clicking. Plus the options Get map bounds, equivalent

to selecting all visible content in the map window as a bounding box, which will be


accordingly shown in light magenta color and have its coordinates automatically

transferred to the fields left of the map, and Lookup address here, that was previously

explained.


4.2 Plugin API

Functionalities in the Importer/Exporter can be extended in a modular way with the installation

of plugins that add specific abilities for interacting with the 3D City Database or external data.

A plugin may provide a new tab or a new menu bar extension possibly accompanied by a

preferences extension and/or a project configuration file extension. Plugins are self-contained

and each of them can be added separately to the main program. No interdependence among

plugins can exist (plugins cannot extend the functionality of other plugins).

The plugin API can be added to the Importer/Exporter path at installation time if the user

decides to do so (not selected by default). It will be copied to its own plugin-api subfolder

containing the 3dcitydb-impexp-plugin-api.jar file itself, a readme file, license information and

javadoc documentation. A more extensive plugin API guide will be offered on the

www.3dcitydb.net site in the near future.

Currently, two plugins are already available: Matching/Merging (formerly integral part of the

Importer/Exporter up to version 1.3.0) and Spreadsheet Generator (a new development that

allows general purpose exports of 3D City Database contents in table/spreadsheet suitable form,

either to a local .csv file with variable formatting or directly to an online spreadsheet hosted in

the Google Docs cloud). The source code of both plugins is freely available to be reviewed and

studied as a sample for the realization of future plugins.

Plugin installation is simple. Just download the plugin .zip file, unzip it and add the plugin

folder as is into the plugins subfolder of the Importer/Exporter installation path. Start the

Importer/Exporter again. Plugins will be automatically detected and started with the

application.

Note: Since release 1.4.0 (3D City Database 2.0.6) the Importer/Exporter and the

3DCityDB can alternatively work on top of a PostgreSQL/PostGIS database. This is

realized in the form of two separate software packages, each of them specifically

adapted for the database type they connect to. Plugins are also coded differently

depending on the database vendor system they are intended to work with. A Plugin

written for the Oracle version of the Importer/Exporter will not run when added to

PostgreSQL/PostGIS version and vice versa.

http://www.3dcitydb.net/


Fig. 8: Importer/Exporter started with the Spreadsheet Generator plugin installed


4.3 KML/COLLADA Export

One of the most outstanding features introduced with release 1.3.0 of the Importer/Export was

the KML/COLLADA export capability. 3D City Database contents can be directly exported

in KML and COLLADA formats for presentation, viewing, and visual inspection in a broad

range of applications such as earth browsers like Google Earth, ArcGIS and ArcGIS Explorer.

Built-in support for object highlighting and generic creation of KML information balloons

facilitate the interactive exploration of your 3D city models. Since release 1.5.0, the export

works for all CityGML top-level feature types like vegetation, transportation complex, etc.

Note: Starting with version 7 (and at least up to version 7.1.1.1888) Google Earth has

changed the way transparent or semi-transparent surfaces are rendered. This is

especially relevant for visualizations containing highlighting surfaces (explained in

chapter 4.3.1). When viewing KML/COLLADA export results in Google Earth it is

strongly recommended to use an older Google Earth 6 version or, from Google Earth

7 upwards switch to the OpenGL graphic mode for an optimal viewing experience.

Changing the Graphic Mode can be achieved by clicking on Tools, Options entry, 3D

View Tab.

Fig. 9: Setting the Graphics Mode in Google Earth


Fig. 10: KML/COLLADA export rendered with DirectX, highlighting surface borders are noticeable everywhere

Fig. 11: The same scene rendered in OpenGL modus


The KML/COLLADA Export tab shown in Fig. 12 collects all parameters required for the export

in a similar fashion as for a CityGML export. On the preferences tab a menu node called

KML/COLLADA Export containing four subnodes – General, Rendering, Balloon, and

Altitude/Terrain – makes customization of these exports possible.

Fig. 12: The KML/COLLADA Export tab allowing for exporting KML/COLLADA models from the

3DCityDB.

Note: KML/COLLADA formatted exports come straight from the 3D City Database. No

direct file transformation CityGML KML/COLLADA is provided. If a CityGML

file shall be converted to KML/COLLADA, the CityGML content must be imported

into the database first and then exported into the KML/COLLADA format.


4.3.1 Main parameters of the KML/COLLADA export

The input data fields on the KML/COLLADA Export tab are from the top down:

Output file selection

Type the filename directly into the text field or activate the file dialog provided by the operating

system after pushing the Browse button.

Versioning

The Workspace Manager provided by Oracle is a comprehensive tool for version and history

management. If the workspace management is activated, it works widely transparent for

applications connected to the database. Workspace name and timestamp can be entered here in

order to use a certain planning alternative and/or a given point in time as the basis for the

KML/COLLADA exports.

If version management is disabled or the current state of the database should be exported, the

default workspace name LIVE must be entered and the timestamp field must remain empty.

Export contents

These fields allow for specifying/selecting the objects of interest for the export. These can be

single objects or whole areas delimited by a bounding box.

Single object: Enter the GML IDs of the object(s) of interest. Multiple IDs have to be

separated by commas.

Bounding Box: Enter the coordinates of a bounding box defining the area of interest.

Objects are exported if they are fully covered by the specified bounding box or if they

intersect with its left or bottom borders. This strategy also applies to tiled exports

(objects in a tile are only exported when fully covered by the tile's bounding box or

intersecting with the tile's left or bottom borders). This is done in order to avoid

exporting the same object twice when the object lies at the same time on more than one

tile. The reference system used for defining the bounding box can be the same as the

one used in the database or any other one supported by Oracle. With release 1.4.0, the

possibility to add further user-defined reference systems was introduced (cf. chapter 4.4

for more details). New reference systems can be added to the Import/Export tool

(preferences tab, node Database, subnode Reference systems) as long as they are

supported by the Oracle DB server.


Tiling only applies to exports of areas defined by a bounding box. Tiled exports are used in

order to load and unload parts of the exported model depending on their current visibility when

viewed, for example, in Google Earth. Since the Earth Browser's responsiveness decreases

greatly with single files larger than 10 Mb, tiled exports (with tile file sizes usually a lot smaller

than that) are highly recommended. As mentioned above, only objects fully covered by the tile's

bounding box or intersecting with the tile's left or bottom borders will be exported.

There are three tiling modes available for a KML/COLLADA export:

no tiling: as the name implies, no tiling takes place. Just a single file is exported. This

is only advisable when the resulting file is at most 10 Mb in size.

automatic: the area enclosed by the bounding box will be exported in tiles having

roughly the side length set on the preferences tab under the node KML/COLLADA

Export, subnode Rendering (default value is 125m.). The amount of exported rows and

columns will be calculated by dividing the length and width (in unit of meters) of the

delimiting bounding box by the preferred tile side length and rounding up the result. For

example: if the user wants to export a 1000m x 1100m bounding box with a preferred

tile side length of 300m, 4x4 tiles will be generated since 1000/300 = 3.333 and

1100/300 = 3.666. This also implies: in case of automatic tiling it cannot be guaranteed

that tiles will be perfectly square, but they will tend to.

manual: the number of rows and columns can be freely set by the user. The area will be

divided in equally spaced portions horizontally and vertically and the resulting tile sizes

and forms will adapt to the values specified.

All these tiling modes can be combined with the (Preferences -> General) option “Each

CityObject in an own region”, which for each object exported defines a region limited by its

envelope coordinates. The single object regions may have different visibility settings to those

of the tiles containing them, so it can be possible that while a tile as a whole is visible some

objects inside are not because their own region visibility conditions are not yet matched.

Untiled exports (no tiling) and tiled exports of type automatic or manual will contain one main

kml file, so-called master file, pointing to all export contents. In case of tiled exports each tile

filename will be enhanced with the tile's row and column number as a suffix.

Export from level of detail

The Level of Detail as defined by the CityGML specification [2] which should be used as basis

information for the KML/COLLADA export. For the same city object higher levels of detail

usually contain many more geometries and these geometries are more complex than in lower

levels. For instance, a building made of 40 polygons in LoD2 may consist of 3000 polygons in

LoD3. This means LoD3 based exports are a lot more detailed than LoD2 based exports, but

they also take longer to generate, are bigger in size and therefore load more slowly in the Earth

browser.

A single constant LoD can be used as basis for all exports or it can be left to the

importer/exporter tool to automatically determine which the highest LoD available for each

cityobject is and then use it as the basis for the KML/COLLADA exports.


Display as

Determines what will be shown when visualizing the exported dataset in Google Earth.

Footprint: objects are represented by their ground surface projected onto the earth

surface. This is a pure KML export.

Extruded: objects are represented as blocks models by extruding their footprint to their

measured height (thematic CityGML attribute), which must be filled with a proper value

in m. Pure KML export.

Geometry: shows the detailed geometry of ground, wall, and roof surfaces of buildings

and appearance information. It shows the different thematic surfaces by means of

coloring them (textures are not supported by KML) according to the settings in the

preferences tab, KML/COLLADA Export node, Rendering subnode. If not explicitly

modeled, thematic surfaces will be inferred for LoD1 or LoD2 based exports following

a trivial logic (surfaces touching the ground –that is, having a lowest z-coordinate- will

be considered wall surfaces, all other will be considered roof surfaces), in LoD3 or

LoD4 based exports surfaces not thematically modeled will be colored as wall surfaces.

Pure KML export.

COLLADA: shows the detailed geometry including support for textures. The

Appearance/Theme combo box below allows choosing from all possible appearance

themes (as defined in the CityGML specification [2]) available in the currently

connected 3DCityDB. The list is workspace- and timestamp sensitive and will be filled

on demand when clicking on the fetch button. Default value is none, which renders no

textures at all and colors all surfaces in a neutral gray tone. Export consists of KML and

COLLADA parts.

Depending on the level of detail chosen as basis some display form checkboxes will become

enabled or disabled, depending on whether the level of detail offers enough information for this

display form or not. Footprint can be exported from any CityGML LoD (0 to 4), whereas

Extruded, Geometry, and COLLADA exports are possible from LoD1 upwards. In previous

releases, the generation of COLLADA required at least LoD2. Exports will have their filename

enhanced with a suffix specifying the selected display form. This applies for both tiled and

untiled exports.

Since 1.6.0


Fig. 13: The same building displayed as (top down and left to right) footprint, extruded, geometry, COLLADA.

With the visibility field next to each display form the user can control the KML element

<minLodPixels>, see [3]: measurement in screen pixels that represents the minimum limit

of the visibility range for a given <Region>. A <Region> is in the generated tiled exports

equivalent to a tile. The <maxLodPixels> value is identical to the <minLodPixels> of

the next visible display form, so that display forms are seamlessly switched when the viewer

zooms in or out. The last visible display form has a <maxLodPixels> value of -1, that is,

visible to infinite size. Visibility ranges can start at a value of 0 (they do not have to, though).

Please note that the region size in pixels depends on the chosen tile size. Thus, if the tile size is

reduced also the visibility ranges should be reduced. Increases in steps of a third of the tile side

length are recommended. An example of a good combination for a tile size of about 250m x

250m could be: Footprint, visible from 50 pixels, Geometry, visible from 125 pixels,

COLLADA, visible from 200 pixels. Some display forms, like Extruded in this example, can be

skipped.

The visibility field only becomes enabled for bounding box exports; single building exports are

always visible.


Feature Classes

Similar to CityGML imports and exports it is possible to select what top-level feature types

shall be displayed in a KML/COLLADA export. Prior to version 1.5.0, this choice was

exclusively limited to Buildings. With the newly introduced selection tree it is possible to pick

each category individually and also leave single categories out, i.e.: export CityFurniture and

WaterBodies only, or export everything but Buildings and so on. Between LoD1 and LoD4 all

feature types are available. For LoD0 only those top-level feature types offering LoD0 geometry

in the CityGML 1.0 schema (Waterbody, LandUse, Transportation and GenericCityObject) are

selectable, whereas the rest of the feature class checkboxes will become automatically disabled.

Each of the top-level feature categories has its own Rendering and Balloon settings under

Preferences. The most complex Rendering and Balloon settings for Buildings, will be explained

as an example in the following sections. Settings for all other top-level features are either

identical or simpler.

Note: Support for Relief features in KML/COLLADA exports is currently limited to the type

TIN_RELIEF. Other Relief types are not rendered currently. Also, due to the usually

wide-streched area of Relief features and the non-clipping nature of the BoundingBox

filter it is recommended to export Relief features in a single step making use of the no

tiling option and using an extensive enough BoundingBox.

As an alternative, the digital terrain model data can be divided in smaller

ReliefComponents tailored to match the tiling settings of the desired export (their area

contained in or equal to the resulting tiles). This requires altering the original data

nevertheless and, as such, it must be done before the CityGML contents are imported

into the database at all.


4.3.2 Preferences

4.3.2.1 General Preferences

Some common features of the exported files, especially those related to tiling options, can be

set under the preferences tab, node KML/COLLADA Export, subnode General.

Fig. 14: General settings for the KML/COLLADA export.

Export in kmz format

Determines in which format single files and tiled exports should be written: kmz when selected,

kml when not. Whatever format is chosen, the main file (so called master file, pointing to all

others) will always be a kml file, all other files will comply with this setting.

Tests have shown shorter loading times (in Google Earth) for the kml format (as opposed to

kmz) when loading from the local hard disk. The Earth Browser's stability also seems to

improve when using the uncompressed format. On the other hand, when loading files from a

server kmz reduces the amount of requests considerably, thus increasing performance. Kmz is

also recommended for a better overview since kml exports may lead to a large number of

directories and files.


Show bounding box borders

When exporting a region of interest via the bounding box option in the KML/COLLADA Export

tab, this checkbox specifies whether the borders of the whole bounding box will be shown or

not. The frame of the bounding box is four times thicker than the borders of any single tile in a

tiled export.

Show tile borders

Specifies whether the borders of the single tiles in a tiled export will be shown or not.

Tile side length for automatic tiling

Applies only to automatically tiled exports and sets the approximate square size of the tiles.

Since the Bounding Box settings in the KML/COLLADA Export tab are the determining factor

for the area to be exported and have priority over this setting, the resulting tiles may not be

perfectly square or have exactly the side length fed into this field.

Each CityObject in an own region

The visibility of the objects exported can be further fine-tuned by this option. While the

visibility settings on the main KML/COLLADA Export tab apply to the whole area (no tiling)

or to each tile (automatic, manual) being exported, this checkbox allows to individually define

a KML <Region> for every single city object. The limits of the object’s region are those of the

object’s CityGML Envelope.

Following the KML Specification [3], each KML <Region> is defined inside a KML

<NetworkLink> and has an associated KML<Link> pointing to a file. This implies when this

option is chosen a subfolder is created for each object exported, identified by the object’s gmlId.

The object’s subfolder will contain any KML/COLLADA files needed for the visualization of

the object in the Earth browser. This folder structure (which can contain a large number of

subfolders) is required for the KML <Region> visibility mechanism to work.

When active, the parameters affecting the visibility of the object’s KML <Region> can be set

through the following related fields.

The field visible from determines from which size on screen the object’s KML <Region>

becomes visible, regardless of the visibility value of the containing tile, if any. Since this value

is the same for every single object and they have all different envelope sizes a good average

value should be chosen.

The field view refresh mode specifies how the KML <Link> corresponding to the KML

<Region> is refreshed when the geographic view changes. May be one of the following:

never - ignore changes in the geographic view.

onRequest - refresh the content of the KML <Region> only when the user explicitly

requests it.

onStop - refresh the content of the KML <Region> n seconds after movement stops, where

n is specified in the field view refresh time.

onRegion - refresh the content of the KML <Region> when it becomes active.


As stated above, the field view refresh time specifies how many seconds after movement stops

the content of the KML <Region> must be refreshed. This field is only active and its value is

only applied when view refresh mode is onStop.

Write JSON file

After exporting some cityobjects in KML/COLLADA you may need to include them into

websites or somehow embed them into HTML. When working with tiled exports referring to a

specific object inside the KML/COLLADA files can become a hard task if the contents are

loaded dynamically into the page. It is impossible to tell beforehand which tile contains which

object. This problem can be solved by using a JSON file that is automatically generated when

this checkbox is selected.

In the resulting JSON file each exported object is listed, identified by its gmlId acting as a key

and some additional information is provided: the envelope coordinates in CRS WGS84 and the

tile, identified by row and column, the object belongs to. For untiled exports the tile’s row and

column values are constantly 0.

This JSON file has the same name as the so-called master file and is located in the same folder.

Its contents can be used for indexed search of any object in the whole KML/COLLADA export.

JSON file example: {

"BLDG_0003000b0013fe1f": {

"envelope": [13.411962, 52.51966, 13.41277, 52.520091],

"tile": [1, 1]},

[…]

"BLDG_00030009007f8007": {

"envelope": [13.406815, 52.51559, 13.40714, 52.51578],

"tile": [0, 0]}

}

Since version 1.5.0, the JSON file can automatically be turned into JSONP (JSON with

padding) by means of adding a function call around the JSON contents. JSONP provides a

method to request data from a server in a different domain, something typically forbidden by

web browsers since it is considered a cross-site-scripting attack (XSS). Thanks to this minimal

addition the JSON file contents can be more easily embedded into webpages or interpreted by

web kits without breaking any rules. The function call name to be added to the original JSON

contents is arbitrary and must only be entered in the callback method name field.


4.3.2.2 Rendering Preferences

Most aspects regarding the look of the KML/COLLADA exports when visualized in Google

Earth can be customized under the preferences tab, node KML/COLLADA Export, subnode

Rendering, sub-subnode Feature Class. For the sake of clarity only the Building Rendering

settings (that happen to be the most complex) will be explained here. The content of the

rendering preferences for all other CityGML top-level features is either identical or simpler.

Fig. 15: Rendering settings for the KML/COLLADA Building export.


All settings in this menu are grouped according to the display form they relate to.

Footprint and extruded display options

In this section the fill and line colors can be selected. Additionally, it can be chosen whether

the displayed objects should be highlighted when being run over with the mouse or not.

Highlighting colors can only be set when the highlighting option is enabled. The alpha value

affects the transparency of all colors equally: 0 results in transparent (invisible) colors, 255 in

completely opaque ones. A click on any color box opens a color choice dialog.

Geometry display options

This parameter section distinguishes between roof and wall surfaces and allows the user to color

them independently. The alpha value affects the transparency of all roof and wall surface colors

in the same manner as in the footprint and extruded cases: 0 results in transparent (invisible)

colors, 255 in completely opaque ones. A click on any color box opens a color choice dialog.

As previously stated: when not explicitly modeled, thematic surfaces will be inferred for LoD1

or LoD2 based exports following a trivial logic (surfaces touching the ground –that is, having

a lowest z-coordinate- will be considered wall surfaces, all other will be considered roof

surfaces), in LoD3 or LoD4 based exports surfaces not thematically modeled will be colored as

wall surfaces.

The highlighting effect when running with the mouse over the exported objects can also be

switched on and off. Since the highlighting mechanism relies internally on a switch of the alpha

values on the highlighting surfaces, the alpha value set in this section does not apply to the

highlighted style of geometry exports, only to their normal style. For a detailed explanation of

the highlighting mechanism see the following section.

COLLADA display options

These parameters control the export of textured models. The first option addresses the fact that

sometimes objects may contain wrongly oriented surfaces (points ordered clockwise instead of

counter-clockwise) as a result of errors in some previous data gathering or conversion process.

When rendered, wrongly oriented surfaces will only be textured on the inside and become

transparent when viewed from the outside. Ignore surface orientation informs the viewer to

disable back-face culling and render all polygons even if some are technically pointing away

from the camera.

Note: This will result in lowered rendering performance. Correcting the surface orientation

data is the recommended solution. This option only provides a quick fix for

visualization purposes.

Surface textures can be stored in an image file each, or grouped into large canvases containing

all images clustered together, so called texture atlases, that significantly increase loading speed.

Grouping images in an atlas or not and the algorithm selected for the texture atlas construction

(differing in generation speed and canvas efficiency) can be set here. Depending on the

algorithm and size of the original textures an object can have one or more atlases, but atlases

are not shared between separate objects.


The texture atlas algorithms address the problem of two dimensional image packing, also

known as 'knapsack problem', in different ways (see [8] and [12]):

BASIC: the most elementary one. Images are sorted according to decreasing height.

Their total width when put next to each other is computed and the square root of this

value is taken as the atlas width limit. Texture images are then added left to right

following their decreasing heights. When the atlas width limit is reached a new row of

images is started within the atlas.

SLEA: Sleater's algorithm (see [11]). Consists of four steps: (1) all items of width greater

than 1/2 are packed on top of one another in the bottom of the strip. Suppose h0 is the

height of the resulting packing All subsequent packing will occur above h0. (2)

Remaining items are ordered by non-increasing height. A level of items are packed (in

non-increasing height order) from left to right along the line of height h0. (3) A vertical

line is then drawn in the middle to cut the strip into two equal halves (note this line may

cut an item that is packed partially in the right half). Draw two horizontal line segments

of length one half, one across the left half (called the left baseline) and one across the

right half (called the right baseline) as low as possible such that the two lines do not

cross any item. (4) Choose the left or right baseline which is of a lower height and pack

a level of items into the corresponding half of the strip until the next item is too wide.

A new baseline is formed and Step (4) is repeated on the lower baseline until all items

are packed.

TPIM: touching perimeter (see [9] and [10]). Sorts images according to non-increasing

area and orients them horizontally. One item is packed at a time. The first item packed

is always placed in the bottom-left corner. Each following item is packed with its lower

edge touching either the bottom of the atlas or the top edge of another item, and with its

left edge touching either the left edge of the atlas or the right edge of another item. The

choice of the packing position is done by evaluating a score, defined as the percentage

of the item perimeter which touches the atlas borders and other items already packed.

For each new item, the score is evaluated twice, for the two item orientations, and the

highest value is selected.

TPIM_WO_R: touching perimeter without rotation. Same as TPIM, but not allowing for

rotation of the original images when packing. Score is evaluated only once since only

one orientation is possible.

From all these algorithms BASIC is the fastest (shortest generation time), TPIM the most

efficient (highest used area/total atlas size ratio).

Scaling texture images is another means of reducing file size and increasing loading speed. A

scale factor of 0.2 to 0.5 often still offers a fairly good image quality while it has a major positive

effect on these both issues. Default value is 1.0 (no scaling). This setting is independent from

the atlas setting and both can be combined together. It is possible to generate atlases and then

scale them to a smaller size for yet shorter loading times in Google Earth.

Buildings can be put together in groups into a single model/placemark. This can also speed up

loading, however it can lead to conflicts with the digital terrain model (DTM) of the Earth

browser, since buildings grouped together have coordinates relative to the first building on the


group (taken as the origin), not to the Earth browser's DTM. Only the first building of the group

is guaranteed to be correctly placed and grounded in the Earth browser. If the objects being

grouped are too far apart this can result in buildings hovering over or sinking into the ground

or cracks appearing between buildings that should go smoothly together.

Up to Google Earth 7, no highlighting of model placemarks loaded from a location other than

Google Earth's own servers is supported natively (glowing blue on mouse over). Therefore a

highlighting mechanism of its own was implemented in the KML/COLLADA exporter:

highlighting is achieved by displaying a somewhat "exploded" version of the city object being

highlighted around the original object itself. "Exploded" means all surfaces belonging to the

object are moved outwards, displaced by a certain distance orthogonally to the original surface.

This "exploded" highlighting surface is always present, but not always visible: when the mouse

is not placed on any building (or rather, on the highlighting surface surrounding it closely) this

"exploded" highlighting surface has a normal style with an alpha value of 1, invisible to the

human eye. When the mouse is place on it, the style changes to highlighted, with an alpha value

of 140 (hard-coded), becoming instantly visible, creating this model placemark highlighted feel.

The displacement distance for the exploded highlighting surfaces can be set here. Default value

is 0.75m.

This highlighting mechanism has an important side effect: the model's polygons will be loaded

and displayed twice (once for the representation itself, once for the highlighting), having a

negative impact in the viewing performance of the Earth browser. The more complex the

models are, the higher the impact is. This becomes particularly noticeable for models exported

from a LoD3 basis upwards. The highlighting and grouping options are mutually exclusive.


Fig. 16: Object exported in the COLLADA display form being highlighted on mouseOver.

4.3.2.3 Information Balloon Preferences

KML offers the possibility of enriching its placemark elements with information bubbles, so-

called balloons, which pop up when the placemark is clicked on. This is supported by the

Import/Export tool regardless of the display form the object is exported in.

Note: When exporting in the COLLADA display form it is recommended to enable the

"highlighting on mouseOver" option, since model placemarks not coming from

Google Earth servers are not directly clickable, but only through the sidebar.

Highlighting geometries are, on the contrary, directly clickable wherever they are

loaded from.

The contents of the balloon can be taken from a generic attribute called Balloon_Content

associated individually to each city object in the 3DCityDB. They can also be uniform for all

objects in an export by using an external HTML file as a template, or a combination of both:

individually and uniformly set, the Balloon_Content attribute (individually) having priority

over the external HTML template file (uniform). A few Balloon HTML template files can be

found after software installation in the subfolder templates/balloons of the installation

directory.


The balloons can be included in the doc.kml file generated at export, or they can be put into

individual files (one for each object) written together into a "balloon" directory. This makes

later adaption work easier if some post-processing (manual or not) is required. When balloon

contents are put into a separate file for each exported object, access to local files and personal

data must be granted in Google Earth (Tools Options General) for the balloons to show.

Balloon preferences can be set independently for each CityGML top-level feature type. That

means every object can have its own individual template file (so that for instance, WaterBody

balloons display a different background image as Vegetation balloons), and it is perfectly

possible to have information bubbles for some object types while some others have none. The

following example is set around Building balloons but it applies exactly the same for all feature

classes.

Fig. 17: Building Balloon settings.

The balloon contents do not need to be static. They can contain references to the data belonging

to the city object they relate to. These references will be dynamically resolved (i.e.: the actual

value for the current object will be put in their place) at export time in a way similar to how

Active Server Pages (ASP) [5] work. Placeholders embedded in the HTML template, beginning

with <3DCityDB> and ending with </3DCityDB> tags, will be replaced in the resulting

balloon with the dynamically determined value(s). The HTML balloon templates can also

include JavaScript code.


For all concerns, including dynamic content generation, it makes no difference whether the

template is taken from the Balloon_Content generic attribute or from an external file.Balloon

template format

As previously stated, a balloon template consists of ordinary HTML, which may or may not

contain JavaScript code and <3DCityDB> placeholders for object-specific content. These

placeholders follow several elementary rules:

Rules for simple expressions

expressions begin with <3DCityDB> and end with </3DCityDB>. Expressions are

not case-sensitive.

expressions are coded in the form "TABLE/[AGGREGATION FUNCTION] COLUMN

[CONDITION]". Aggregation function and condition are optional. When present they

must be written in square brackets (they belong to the syntax). These expressions

represent an alternative coding of a SQL select statement: SELECT [AGGREGATION

FUNCTION] COLUMN FROM TABLE [WHERE condition]. Tables refer to the

underlying 3DCityDB table structure (see [1] for details).

Each expression will only return those entries relevant to the city object being currently

exported. That means an implicit condition clause somewhat like

"TABLE.CITYOBJECT_ID = CITYOBJECT.ID" is always considered and does

not need to be explicitly written.

Results will be interpreted and printed in HTML as lists separated by commas. Lists

with only one element are the most likely, but not exclusively possible, outcome. When

only interested in the first result of a list the aggregation function FIRST should be

used. Other possible aggregation functions are LAST, MAX, MIN, AVG, SUM and

COUNT.

Conditions can be defined by a simple number (meaning which element from the result

list must be taken) or a column name (that must exist in underlying 3DCityDB table

structure) a comparison operator and a value. For instance: [2] or [NAME =

'abc'].

Invalid results will be silently discarded. Valid results will be delivered exactly as stored

in the 3DCityDB tables. Later changes on the returned results - like substring() functions

- can be achieved by using JavaScript.

All elements in the result list are always of the same type (the type of the corresponding

table column in the underlying 3DCityDB). If different result types must be placed next

to each other, then different <3DCityDB> expressions must be placed next to each

other.


Special keywords in simple expressions

Starting from the Importer/Exporter version 1.5.0 balloon template files have been

enhanced with new additional placeholders for object-specific content, called

SPECIAL_KEYWORDS. They refer to data that is not retrieved “as is” in a single step

from a table in the 3DCityDB but has to undergo some processing steps (not achievable

by simple JavaScript means) in order to calculate the final value before being exported

to the balloon. A typical processing step is the transformation of some coordinate list

into a CRS different from the one the 3DCityDB is originally set in. The coordinates in

the new CRS cannot be included in the balloon with their original values as read from

the database (which was the case with all other expression values so far), but must be

transformed prior to their addition to the balloon contents.

Expressions for special keywords are not case-sensitive. Their syntax is similar to

ordinary simple expressions, start and end are marked by <3DCityDB> and

</3DCityDB> tags, the table name must be SPECIAL_KEYWORDS (a non-existing

table in the 3DCityDB), and the column name must be one of the following:

CENTROID_WGS84 (coordinates of the object’s centroid in WGS84 in the following

order: longitude, latitude, altitude)

CENTROID_WGS84_LAT (latitude of the object’s centroid in WGS84)

CENTROID_WGS84_LON (longitude of the object’s centroid in WGS84)

BBOX_WGS84_LAT_MIN (minimum latitude value of the object’s envelope in

WGS84)

BBOX_WGS84_LAT_MAX (maximum latitude value of the object’s envelope in

WGS84)

BBOX_WGS84_LON_MIN (minimum longitude value of the object’s envelope in

WGS84)

BBOX_WGS84_LON_MAX (maximum longitude value of the object’s envelope in

WGS84)

BBOX_WGS84_HEIGHT_MIN (minimum height value of the object’s envelope in

WGS84)

BBOX_WGS84_HEIGHT_MAX (maximum height value of the object’s envelope in

WGS84)

BBOX_WGS84_LAT_LON (all four latitude and longitude values of the object’s

envelope in WGS84)

BBOX_WGS84_LON_LAT (all four longitude and latitude values of the object’s

envelope in WGS84)

No aggregation functions or conditions are allowed for SPECIAL_KEYWORDS. If

present they will be interpreted as part of the keyword and therefore not recognized.

The SPECIAL_KEYWORDS list is also visible and available in its current state in the

updated version of the Spreadsheet Generator Plugin. The list can be extended in further

Importer/Exporter releases.


Examples for simple expressions:

<3DCityDB>ADDRESS/STREET</3DCityDB>

returns the content of the STREET column on the ADDRESS table for this city object.

<3DCityDB>BUILDING/NAME</3DCityDB>

returns the content of the NAME column on the BUILDING table for this city object.

<3DCityDB>CITYOBJECT_GENERICATTRIB/ATTRNAME</3DCityDB>

returns the names of all existing generic attributes for this city object. The names will

be separated by commas.

<3DCityDB>CITYOBJECT_GENERICATTRIB/REALVAL

[ATTRNAME = 'H_Trauf_Min']</3DCityDB>

returns the value (of the REALVAL column) of the generic attribute with attrname

H_Trauf_Min for this city object.

<3DCityDB>APPEARANCE/[COUNT]THEME</3DCityDB>

returns the number of appearance themes for this city object.

<3DCityDB>APPEARANCE/THEME[0]</3DCityDB>

returns the first appearance for this city object.

<3DCityDB>SPECIAL_KEYWORDS/CENTROID_WGS84_LON</3DCityDB>

returns the longitude value of this city object’s centroid longitude in WGS84.

<3DCityDB> simple expressions can be used not only for generating text in the balloons, but

any valid HTML content, like clickable hyperlinks:

<a href="<3DCityDB>EXTERNAL_REFERENCE/URI</3DCityDB>">

click here for more information</a>

returns a hyperlink to the object's external reference,

or embedded images:

<img src= "<3DCityDB>CITYOBJECT_GENERICATTRIB/URIVAL

[ATTRNAME='Illustration']</3DCityDB>" width=400>

This last example produces, for instance, in the case of the Pergamon Museum in Berlin:

<img src="http://upload.wikimedia.org/wikipedia/commons/d/

d1/FrisoaltarPergamo.jpg" width=400>

http://upload.wikimedia.org/wikipedia/commons/d/d1/FrisoaltarPergamo.jpg

http://upload.wikimedia.org/wikipedia/commons/d/d1/FrisoaltarPergamo.jpg


Fig. 18: Dynamically generated balloon containing an embedded image (image taken from Wikimedia).

Simple expressions are sufficient for most use cases, when only a single value or a list of values

from a single column is needed. However, sometimes the user will need to access more than

one column at the same time with an unknown amount of results. For these situations (listing

of all generic attributes along with their values is one of them) iterative expressions were

conceived.


Rules for iterative expressions

Iterative expressions will adopt the form:

<3DCityDB>FOREACH

TABLE/COLUMN[,COLUMN][,COLUMN][...][,COLUMN][CONDITION]

</3DCityDB>

[...]

HTML and JavaScript code (column content will be referred to as %1, %2, etc. and

follow the columns order in the FOREACH line. %0 is reserved for displaying the

current row number)

[...]

<3DCityDB>END FOREACH</3DCityDB>

No aggregation functions are allowed for iterative expressions. The amount of columns

is free, but they must belong to the same table. Condition is optional. Implicit condition

(data must be related to the current city object) applies as for simple expressions.

FOREACH means truly "for each". No skipping is possible. If skipping at display time

is needed it must be achieved by JavaScript means.

The generated HTML will have as many repetitions of the HTML code between the

FOREACH and END FOREACH tags as lines the query result has.

No inclusion of simple expressions or SPECIAL_KEYWORDS between FOREACH and

END FOREACH tags is allowed.

No nesting of FOREACH statements is allowed.

Examples for iterative expressions:

Listing of generic attributes and their values:

<script type="text/javascript">

function ga_value_as_tooltip(attrname, datatype, strval,

intval, realval)

{

document.write("<span title=\"");

switch (datatype) {

case "1": document.write(strval);

break;

case "2": document.write(intval);

break;

case "3": document.write(realval);

break;

default: document.write("unknown");

};

document.write("\">" + attrname + "</span>");


}

<3DCityDB>FOREACH

CITYOBJECT_GENERICATTRIB/ATTRNAME,DATATYPE,STRVAL,

INTVAL,REALVAL</3DCityDB>

ga_value_as_tooltip("%1", "%2", "%3", "%4", "%5");

<3DCityDB>END FOREACH</3DCityDB>

</script>

Fig. 19: Model placemark with dynamic balloon contents showing the list of generic attributes.


4.3.2.4 Altitude/Terrain Preferences

With reference systems other than WGS84 (the reference system used in Google Earth) in the

underlying 3DCityDB, some adjustments on the z coordinate for the exported datasets may be

necessary for a perfect display in the Earth browser.

Fig. 20: Altitude/Terrain settings.

Use original z-Coordinates without transformation

Depending on the Oracle version (10g or 11g) of the database used, the transformation of the

original coordinates to WGS84 will include transformation of the z-coordinates (11g) or not

(10g). To make sure only the planimetric (x,y) and not the z-coordinates are transformed this

checkbox must be selected. This is useful when the used terrain model is different from Google

Earth’s and the z-coordinates are known to fit perfectly in that terrain model.

Another positive side-effect of this option is that GE_LoDn_zOffset attribute values (explained

in the following section) calculated for Oracle 10g keep being valid when imported into Oracle

11g. Otherwise, when switching database versions and not making use of this option,

GE_LoDn_zOffset values must be recalculated again.

GE_LoDn_zOffset attribute values calculated for Oracle 10g are consistent for all

KML/COLLADA exports from Oracle 10g. The same applies to Oracle 11g. Only cross-usage


(calculation in one version, export from the other) creates inconsistencies that can be solved by

turning z-coordinate transformation off.

This setting affects the resulting GE_LoDn_zOffset if used when a cityobject has none such

value yet and is exported in KML/COLLADA for the first time, so it is recommended to

remember its status (z-coordinate transformation on or off) for all future exports.

Altitude mode

Allows the user to choose between relative (to the ground), interpreting the altitude as a value

in meters above the terrain, or absolute, interpreting the altitude as an absolute height value in

meters according to the vertical reference system (EGM96 geoid in KML).

This means, when relative altitude mode is chosen, the z-coordinates of the exports represent

the vertical distance from the digital terrain model (DTM) of the Earth browser, which should

be 0 for those points on the ground (the building's footprint) and higher for the rest (roof

surfaces, for instance). However, z-coordinate values of the city objects stored in a 3DCityDB

usually have values bigger than 0, so choosing this altitude mode will result most times in

exports hovering over the ground.

Fig. 21: Possible export result with relative altitude mode.

When absolute altitude mode is chosen, the z-coordinates of the exports represent the vertical

distance from the vertical datum - the ellipsoid or geoid which most closely approximates the

Earth curvature, for Google Earth this is the WGS84 EGM96 Geoid, see KML documentation

[3] -, regardless of the DTM at that point. This implies, choosing this altitude mode may result


in buildings sinking into the ground wherever the DTM indicates there is a hill or hovering over

the ground wherever the DTM indicates a dent.

For a proper grounding, a positive or negative offset value can be applied to all z-coordinates

of the exports, moving the city objects up and down along the z-axis until they match the

ground.

Altitude offset

A value, positive or negative, can be added to the z coordinates of all geometries in one export

in order to place them higher or lower over the earth surface. This offset can be 0 for all exported

objects (no offset), it can be constant for all (constant), or it can have an individual value for

each object stored in the object's generic attribute GE_LoDn_zOffset (where n stands for the

corresponding level of detail in CityGML sense).

The first two options, no offset and constant, are appropriate for exports of a single city object,

allowing some fine tuning of its position along the z-axis. When exporting regions - via

bounding box settings -, the Use generic attribute "GE_LoDn_zOffset" option is recommended.

Whenever possible (restrictions explained below) settings should be as displayed in Fig. 20,

including absolute altitude mode. The GE_LoDn_zOffset generic attribute value can be

automatically calculated by the KML/COLLADA exporter if not available. This calculation

uses data returned by Google's Elevation API [4]. After calculation the value will be stored in

the CITYOBJECT_GENERICATTRIB table of the 3DCityDB for future use.

Since city objects may have different geometries for different LoDs, the anchoring points and

their elevation values may also differ for each LoD. This explains the need for having

GE_LoD1_zOffset, GE_LoD2_zOffset, etc. generic attributes for one single object.

The algorithm used to calculate the individual zOffset for an object iterates over the points with

the lowest z-coordinate in the object, calling Google's elevation API in order to get their

elevation. The point with the lowest elevation value will be chosen for anchoring the object to

the ground. The zOffset value results from subtracting the point's z-coordinate from the point's

elevation value.

When calling Google's elevation API for calculating the zOffset of an object a message is

shown: "Getting zOffset from Google's elevation service for BLDG_0003000e008c4dc4".

Google's elevation API imposes strong usage restrictions: non-premium users can issue a

maximum of 2,500 requests per day. This limit may be reached fast when exporting areas where

no city objects have GE_LoDn_zOffset values assigned. When the daily usage limit is reached

a warning message is shown: "Elevation service returned OVER_QUERY_LIMIT". The usage

limit is bound to the caller's IP address. It is advisable to use several different computers (or IP

addresses) when filling the 3DCityDB with GE_LoDn_zOffset values (or become a premium

user).

A second usage restriction allows for no more than 10 requests per second. The Import/Export

tool takes care of not exceeding this limit by pausing between requests when required. That will

slow down KML/COLLADA exports when done for the first time. Subsequent exports will be


faster since the GE_LoDn_zOffset attribute value is already in the 3DCityDB and does not have

to be calculated again.

Saving the building's height offset in the form of a generic attribute ensures this information

will be present in every export in CityGML format (and therefore at every re-import) and can

thus be transported across databases. Please note, that not the DTM height value of Google

Earth will be stored but the difference of the individual building’s minimum z value and the

value reported by the Google Elevation Service. Following this approach further usage

restrictions of the Google Elevation Service are avoided.

In some unusual cases, even after automatic calculation of the GE_LoDn_zOffset value the

object may still not be perfectly grounded to the Earth surface for a number of reasons; e.g.

wrong height data of the model, or low resolution of the DTM at that area. In those cases a

manual adjustment of the value in the 3DCityDB is needed. After the content of

GE_LoDn_zOffset has been fine tuned to a proper value it should be persistently stored in the

database.

Fig. 22: Points sent to Google's Elevation API for calculation of the zOffset.


Fig. 23: Export with absolute altitude mode and no offset.

Fig. 24: Export with absolute altitude mode and use of GE_LoDn_zOffset.


4.3.3 Batch mode

Analog to the CityGML imports and exports, KML/COLLADA exports can also be executed

from the shell without opening a graphical user interface. The command line syntax is:

java [options] -jar impexp.jar -shell –kmlExport

<export_filename> -config <config_filename>

[options] refers to all possible settings in the Java Virtual Machine (JVM) itself. One

recommended option is –Xmx1024m, which sets the maximum heap size to 1GB. The user can

adapt this value according to his/her hardware for optimal performance. Bigger heap sizes mean

less often garbage collections and therefore improved performance. For a comprehensive list of

all JVM options see [7].

-shell tells the Import/Export tool to execute in a shell environment without graphical

user interface.

<export_filename> indicates the target file for the resulting exports.

<config_filename> points to a configuration file containing the project settings.

Configuration files can be explicitly created and stored by the Importer/Exporter tool

by clicking on the menu "Project", "Save Project As...". Configuration files are written

in .xml format and can be adapted with any text editor.

4.3.4 Loading exported models in Google Earth

Usage of the most up-to-date Google Earth version is highly recommended. Some of the

features described in this documentation, like highlighting, require version 6.0.1 to work

flawlessly (they do work in older versions, but not as smooth).

Displaying a file in Google Earth can be achieved by opening it through the menu ("File",

"Open") or double-clicking on any kml or kmz file if these extension are associated with the

program (default option at Google Earth's installation time).

Loaded files can be refreshed when generated again after loading (if for example the balloon

template file was changed) by choosing the "Revert" option in the context menu on the sidebar.

There is no need to delete and load them again or shutdown or restart the Earth browser.

For best performance, cache options ("Tools", "Options", "Cache") should be set to their

maximum values, 1024MB for memory cache size, 2000MB for disk cache. Actual maximums

may be lower depending on the computer's hardware.

Recommended graphics mode ("Tools", "Options", "3D View") on Windows platforms is

DirectX.

Show Terrain ("Tools", "Options", "3D View") should be enabled, quality set at around 1/3.

Disable it only in the case exports cannot be seen although shown as loaded in Google Earth's

sidebar: they are probably buried into the ground (see chapter 4.3.2.4), and remember to enable

showing of the terrain again when loading the next unrelated exports.

When exporting balloons into individual files (one for each object) written together into a

balloon directory access to local files and personal data must be allowed ("Tools", "Options",


"General"). Google Earth will issue a security warning that must be accepted, otherwise the

contents of the balloons (when in individual files and not as a part of the doc.kml file) will not

be displayed.

It is also possible to upload the generated KML/COLLADA files to a web server and access

them from there as a Network Link in Google Earth or via internet browser with installed Google

Earth Plugin. In this case, as stated in chapter 4.3.2.1, export in kmz format is recommended

and balloon content must be part of the doc.kml file. Due to security risks, the Plugin has no

option for allowing access to local files and personal data.

4.3.5 General setting recommendations When the original data are defined in a 3D reference system the Importer/Exporter will detect

this before exporting to KML/COLLADA and automatically choose the target system with the

same dimensionality (WGS84 for 2D, WGS84 3D for 3D) that must be applied for the

coordinate transformation.

Depending on the quality and complexity of the 3DCityDB data, export results may vary greatly

in aesthetic and loading performance. Experimenting will be required in most cases for a fine

tuning of the export parameters. However, some rules apply for almost all cases:

kmz format use is recommended when the files will be accessed over a network. Kml

format seems to have a positive effect on the stability of the Earth browser.

Visibility values for the different display forms should be increased in steps of around

one third of the tile side length.

Visibility from 0 pixels (always visible) should be avoided, especially for large or

complex exports, because otherwise the Earth browser will immediately load all data at

once since it all must be visible.

Tile side length (whether tiling is automatic or manual) should be chosen so that the

resulting tile files are smaller than 10MB. When single files are bigger than that Google

Earth gets unresponsive. For densely urbanized areas, where many placemarks are

crimped together a tile side length value between 50 and 100m should be used.

When not exporting in the COLLADA display form, files will seldom reach this 10MB

size, but Google Earth will also become unresponsive if the file loaded contains a lot of

polygons, so do not use too large tiles for footprint, extruded or geometry exports even

if the resulting files are comparatively small.

Do not choose too small tile sizes, many of them may become visible at the same time

and render the tiling advantage useless.

Using texture atlas generation when producing COLLADA display form exports always

results in faster model loading times.

From all texture atlas generating algorithms, BASIC is the fastest (shortest generation

time), TPIM the most efficient (highest used area/total atlas size ratio).

Texture images can often be scaled down to 0.2 - 0.5 without noticeable quality loss.

This depends, of course, on the quality of the original textures.

Highlighting puts the same polygons twice in the resulting export files, one for the

buildings themselves, one for their highlighting. This has a negative impact on the


viewing performance. The more complex the buildings are the worse the impact. When

highlighting is enabled for exports based on a CityGML LoD3 or higher Google Earth

may become quite slow.

Balloon generation is slightly more efficient when a single template file is applied for

all exported objects.

Optimal altitude/terrain settings for a proper grounding of the exports are as shown in

Fig. 20: absolute altitude mode, use of generic attribute GE_LoDn_zOffset and call

Google's elevation API when no data is available.

When the Google's elevation API daily quota limit is reached you can continue the

export on another computer, or you can change your IP address (or become a Google

premium user). Repetitive running of the KML/COLLADA export may be required

over several days until error message "OVER_QUERY_LIMIT" no longer appears.


4.4 Support for Coordinate Reference Systems (CRS)

4.4.1 General information

When setting up a new instance of the 3D City Database, a Coordinate Reference System (CRS)

has to be provided as mandatory setup parameter. This CRS is used as default reference system

for all spatial objects which are created and stored in the database instance as well as for

building spatial indexes and performing spatial functions.

Oracle provides comprehensive support for different types CRSs. Both Oracle 10g and 11g

support 2D coordinate systems which are classified into two types: Geographic2D and

Projected. The first type of coordinate system specifies the longitude and latitude on the earth

surface approximated by a reference ellipsoid and is also referred to as Geodetic coordinate

system. Projected types of 2D coordinate systems specify how to project longitude and latitude

values on a reference Geographic2D system to a two-dimensional Euclidean coordinate system.

Starting from Oracle 11g, support for 3D coordinate systems has been added which are

classified into the following three types: Geographic3D (Geographic2D plus ellipsoidal

height), Geocentric (specifies x,y,z values with reference to the center of the earth), and

Compound (combines either Geographic2D or Projected (2D) with a vertical coordinate system

specifying height based on gravity, above mean sea level, etc.).

The 3D City Database and the Importer/Exporter are designed to support both Oracle 10g (R2)

and Oracle 11g (R1 and R2). When using Oracle 11g, both 2D and 3D reference systems are

supported. Exports to CRS different from the original (see 4.6.1) require the dimensionality of

the target and source system to be identical. That means, 2D reference systems must be

transformed into 2D reference systems, 3D reference systems into 3D reference systems. Cross-

dimensionality transformation (2D to 3D or 3D to 2D) is not supported. Oracle 11g comes with

a few predefined 3D CRS. Their coverage is limited, so a manual definition of a new 3D CRS

is usually required for most areas. An Importer/Exporter plugin is currently being developed

especially for this purpose (definition of 3D CRS).

Regardless of the CRS associated with a spatial object, the spatial data types offered by both

Oracle 10g and 11g fully support three-dimensional coordinate values. This is important with

respect to the storage of geometries in the 3D City Database: Since the 3D City Database is

meant to store and manage virtual 3D city models based on CityGML, and CityGML is a true

3D standard, all geometries are stored with three-dimensional coordinate values in the 3D

City Database. There are only very few exceptions to this rule, where geometries with two-

dimensional coordinate values are allowed in CityGML (please refer to the CityGML

specification [2] for details).

Note: Transformation of stored three-dimensional coordinates which refer to a 2D CRS can

result in some small degree of inaccuracy affecting not only the output height of a

transformation, but also possibly the longitude and latitude, see [15] for details.

4.4.2 Definition of the CRS for a 3D City Database instance The definition of the CRS for setting up a new instance of the 3D City Database consists of two

components: 1) a valid Oracle Spatial Reference Identifier (SRID) and 2) an OGC GML


conformant definition identifier for the CRS. Both components are stored in the table

DATABASE_SRS. The CRS definition is fixed and shall not be changed at any later point in

time (please refer to the chapter 3.2 of the previous 3D City Database 2.0.1 documentation [1]

for more information about the setup procedure).

The SRID is an integer value key pointing to spatial reference information within Oracle’s

MDSYS.CS_SRS table. Oracle is shipped with a large number of predefined spatial reference

systems. At setup time, the SRID chosen as default value for the 3D City Database instance

must already exist in MDSYS.CS_SRS.

The GML conformant CRS definition identifier is used as value for the gml:srsName

attribute on GML geometry elements when exporting database contents to CityGML instance

documents. It should follow the OGC recommendation for the Universal Resource Name

(URN) encoding of CRSs given in the OGC Best Practice Paper Definition identifier URNs in

OGC namespace [13]. At setup time, please make sure to provide a URN value which

corresponds to the spatial reference system identified by the default SRID of the database

instance. Since CityGML is a 3D standard, the URN encoding shall always represent a three-

dimensional CRS which, for example, can be denoted as compound coordinate reference

systems [13]. The general syntax of a URN encoding for a compound reference system is as

follows:

urn:ogc:def:crs,crs:authority:version:code,crs:authority:

version:code

Authority, version, and code depend on the information authority providing the CRS

definition (e.g. EPSG or OGC). The following example shows a possible combination of an

SRID (here referring to a 2D CRS) and CRS URN encoding (3D) to set up an instance of the

3D City Database:

SRID: 31466

URN: urn:ogc:def:crs,crs:EPSG:7.7:31466,crs:EPSG:7.7:5783

The example SRID is referencing a Projected CRS defined by EPSG (DHDN / 3-degree Gauss-

Krüger zone 2; used in the western part of Germany; EPSG-Code: 31466). The URN encodes

a compound coordinate reference system which adds a Vertical CRS as height reference

(DHHN92 height, EPSG-Code: 5783).

4.4.3 Management of user-defined CRSs Version 1.2.2 of the Importer/Exporter already introduced the possibility to pass coordinate

values given in a different CRS than the internal database CRS as input values for a spatial

bounding box filter when importing/exporting CityGML documents. However, the support for

further CRSs was still preliminary in such that a user could only choose from a predefined and

fixed number of CRSs.

Release 1.4.0 of the Importer/Exporter brought full support for user-defined CRSs. Similar to

the CRS information that has to be provided at setup time of a new 3D City Database instance,

a user-defined CRS consists of both an Oracle SRID and a GML conformant URN encoding of


the CRS. For the management of user-defined CRSs, a new user dialog was added to the

Preferences tab as shown in the Fig. 25.

Fig. 25: Support for user-defined CRSs in the Preferences tab.

The management of user-defined CRSs can be found in the Reference systems subnode of the

Database preferences node (the latter one is also introduced with release 1.4.0, cf. chapter 4.8).

On top of the preferences page, a combo allows for choosing a CRS for display and editing

from the list of user-defined CRSs. The list contains at minimum one predefined entry called

Same as in database which represents the internal CRS of the 3D City Database instance. This

entry will always show the SRID and CRS URN encoding of the currently connected database

instance. Since the internal CRS shall not be changed after database setup, the fields of the

Same as in database entry cannot be edited (cf. Fig. 25.).


A new user-defined CRS can be added to this list after clicking the New button. Please provide

an Oracle SRID in the corresponding SRID input field of the user dialog and pass a

corresponding URN encoding to the gml:srsName input field (optional). A short, meaningful

textual description of the CRS has to be given in the Description field. This description is used

as key value for the list of user-defined CRSs displayed in the combo box on top (and also in

similar combo boxes on further tabs of the Importer/Exporter). The new CRS is added to the

list of user-defined CRSs by clicking on the Apply button. The following screenshot provides

an example.

Fig. 26: Adding a new CRS to the list of user-defined CRSs.

The Copy button allows for adding a further CRS by copying and editing the information of an

already existing user-defined CRS. The currently selected CRS is deleted from the list by

clicking the Delete button. The Check button next to the SRID input field facilitates to verify

whether the provided SRID is supported by the currently connected 3D City Database instance.

After a successful check the non-editable fields Database name and SRS type will be filled with

the corresponding information collected from the currently connected 3D City Database


instance. If the Importer/Exporter is not connected to a database instance, the Check button is

disabled.

The result of the SRID verification may vary between different 3D City Database instances due

to the fact that a) the list of predefined spatial reference systems differs between different

versions of Oracle Spatial (e.g., between 10g R2 and 11g R2) and b) the fact, that Oracle also

supports the definition of user-defined spatial reference systems (please check the Oracle

Spatial documentation for further guidance on how to create spatial reference systems in

Oracle). In order to add a user-defined CRS to the Importer/Exporter which is not supported by

the underlying Oracle Spatial database by default, this CRS has first to be registered with the

internal Oracle tables. As soon as the CRS is announced to Oracle, it can be added to the list of

user-defined CRSs in the Importer/Exporter.

The list of user-defined CRSs is automatically stored in the project settings of the

Importer/Exporter and loaded upon application start. It can additionally be exported into an

extra file without the remaining project settings. This allows for easily sharing user-defined

CRSs between different Importer/Exporter installations. Please provide a valid filename in the

corresponding input field Filename (clicking on the Browse button opens a dialog which allows

for choosing a file) and click on Save. There are two options for importing such an external list

of CRSs: 1) the CRSs listed in the external file can be added to the current list of CRSs (Add

button) or 2) the external list can be used to replace the current list (Replace with button).

The Importer/Exporter is shipped with a number of predefined CRSs organized in subfolders

of templates/CoordinateReferenceSystems within the installation folder of the

Importer/Exporter. Each CRS definition is stored in its own file and, thus, can be easily

imported and added to the list of user-defined CRSs. The URN encoding of the predefined

CRSs generally lacks a height reference system which has to be added before using this CRS

as target reference system for CityGML exports (cf. chapter 4.6.1 for more details).

4.4.4 Usage of user-defined CRSs User-defined CRSs can be used at the following locations within the Importer/Exporter:

1. Defining the CRS for the bounding box filter on the CityGML Import tab,

2. Defining the CRS for the bounding box filter on the CityGML Export tab,

3. Defining the CRS for the bounding box filter on the KML/COLLADA Export tab (cf.

chapter 4.3), and

4. Defining the target CRS for a coordinate transformation during CityGML exports on

the Export tab (cf. chapter 4.6.1).

The following Fig. 27 shows an example usage of the CRS which has been added to the list of

user-defined CRSs in the previous chapter. The CRS is applied to the spatial bounding box filter

on the CityGML Import tab by choosing the corresponding value from the combo box. The

Importer/Exporter will use this CRS information for the interpretation of the coordinate values

passed to the Xmin, Xmax, Ymin and Ymax input fields and automatically transform them to the

internal CRS of the 3D City Database instance in order to apply the spatial filter.


Often the bounding box used as a spatial filter for a CityGML import/export or

KML/COLLADA export is derived from querying a public web-based map service such as

Google Maps, Microsoft Bing Maps, or OpenStreetMap. Usually, points on these maps have

latitude and longitude values according to the WGS84 ellipsoid and datum. If you want to

directly make use of the map coordinate values in the spatial bounding box filters of the

Importer/Exporter, you first have to add a user-defined CRS for WGS84 and choose this as

reference system for the corresponding filter. The Importer/Exporter is shipped with a

predefined CRS definition for WGS84. This can be loaded from an external file which is located

in the subfolder templates/CoordinateReferenceSystems within the installation

folder of the Importer/Exporter.

Fig. 27: Example usage of a user-defined CRS for specifying the reference system of the spatial bounding box

filter applied to a CityGML import.

Since not every user-defined CRS is necessarily supported by the Oracle Spatial database, the

Importer/Exporter verifies all CRSs upon every database connection. If a user-defined CRS is

not supported by the Oracle Spatial database underlying the 3D City Database, a corresponding

warning message is logged in the console window. The CRS combo boxes on the CityGML

Import/Export tab and KML/COLLADA Export tab are smart in such they only offer a subset of

CRSs which is supported by the currently connected database.


4.4.5 Support for 3D CRS

Support for 3D CRS was improved with release 1.4.0. The 3D City Database can be set up on

a compound or geographic 3D system and the Importer/Exporter shall support all data

operations including import, export and KML/COLLADA export the same as for all 2D CRS

so far. Consequently, 3D CRS are managed through the same Preferences tab, Database node,

Reference systems subnode as their 2D counterparts.

A geographic 3D CRS consists of a geographic 2D CRS plus ellipsoidal height, with longitude,

latitude, and height based on the same ellipsoid and datum. A compound CRS consists of either

a geographic 2D CRS plus gravity-related height or of a projected 2D plus gravity-related

height.

When a CRS belonging to one of these two types is met it can be immediately recognized by

the contents of the SRS type field, see Fig. 28.


Fig. 28: A compound 3D CRS

When exporting 3D City Database contents into CityGML format the choice list Reference

Systems on the Export tab will be automatically adapted to only show suitable 3D CRS the

original data can be transformed into plus Same as in database (no transformation). Exporting

to a 2D CRS when the original data comes from a 3D CRS will not be possible.

When exporting 3D City Database contents into KML/COLLADA format the

Importer/Exporter will automatically identify whether the original data were defined in a 2D or

in a 3D CRS and choose the target system WGS84 2D or WGS84 3D accordingly.


4.4.6 Support for Point and Line Geometries of GenericCityObjects

The feature type GenericCityObject as defined within CityGML’s Generics module (see [2])

allows for modeling and exchanging of 3D city objects which are not covered by any other

thematic module of the CityGML data model. In every LOD, the spatial characteristics of a

GenericCityObject can be described by an arbitrary 3D geometry object being a subtype of

gml:_Geometry (the root of the GML geometry hierarchy). Thus, a GenericCityObject may be

geometrically represented by one or more points, lines, surfaces, or volume objects per LOD.

As for example, GenericCityObjects can be used to model network structures such as water or

power supply networks (which are not predefined by the current CityGML specification) with

every GenericCityObject representing either a junction or an edge of the network. In LOD1,

this network might be spatially embedded using point and line geometries. However, until

release 1.5.0 of the Importer/Exporter, only surface-based and volumetric representations of

generic city objects were supported and kept in the SURFACE_GEOMETRY table. The

exemplified network structure would hence be lost during the database import.

This limitation has been resolved in 1.5.0 which additionally enables the storage of point and

line geometries. In order to keep the 3DCityDB database model unchanged for this minor

release, non-surface-based representations of generic city objects are saved in the table

CITYOBJECT_GENERICATTRIB according to the following scheme:

1. The ATTRNAME column follows the pattern “LODn_Geometry”, where n stands

for the LOD of the GenericCityObject which is captured by the geometry object

(i.e., LOD0_Geometry, LOD1_Geometry, etc.).

2. The geometry itself is mapped onto an instance of SDO_GEOMETRY and stored

in the GEOMVAL column. The SDO_TYPE field of the SDO_GEOMETRY object

is restricted to 3001 for point geometries and to 3002 respectively 3006 for line

strings (whose vertices are required to be connected by straight line segments).

3. The DATATYPE field takes the value “6” which encodes a geometry attribute.

When exporting a GenericCityObject, first the SURFACE_GEOMETRY table is scanned

whether it holds a geometry representation of the feature for a given LOD. If no surface-based

geometry is found, the CITYOBJECT_GENERICATTRIB table is searched for a point or line

geometry associated with the feature by looking for a tuple whose ATTRNAME agrees with

the pattern “LODn_Geometry” and matches this LOD. If such a tuple exists, its GEOMVAL

value is used to populate the respective “lodnGeometry” property of the GenericCityObject

being exported.

Note: According to the CityGML specification, a GenericCityObject feature may have at

most one gml:_Geometry representation in each LOD. Correspondingly, per LOD, a

tuple in GENERIC_CITYOBJECT may either reference a surface-based geometry

stored in SURFACE_GEOMETRY or a single point respectively line geometry from

CITYOBJECT_GENERICATTRIB but not both.

Note: The spatial representation of a GenericCityObject can be given as complex geometry

using a gml:GeometricComplex which is allowed to contain geometric elements from

different dimensions (e.g., a heterogeneous collection of points, lines, and surface-


based geometries). Although Oracle Spatial generally supports storing heterogeneous

collections of geometric elements in a single SDO_GEOMETRY object, very few of

its spatial functions can be applied to such collections. For this reason, only

homogeneous elements of the complex are considered when importing. First, the

complex is checked whether it merely contains points or lines, in which case the point

respectively line geometry is stored in CITYOBJECT_GENERICATTRIB as

explained above. If this check fails, surface-based primitives contained in the complex

are saved in the SURFACE_GEOMETRY table while silently discarding all non-

surface-based primitives. The latter conforms to the behavior of previous releases.

4.5 CityGML Import Enhancements

4.5.1 Address storage

CityGML relies upon the OASIS Extensible Address Language (xAL) standard for the

representation and exchange of address information. xAL provides a flexible and generic

framework for encoding address data according to arbitrary address schemes. The columns of

the ADDRESS table of the 3DCityDB however only map the most common fields in address

records. Moreover, the Importer/Exporter currently does not support arbitrary xAL fragments

but is tailored to the parsing of two xAL templates which are documented in [2] and presented

below.

<bldg:Building>

…

<bldg:address>

<Address>

<xalAddress>



<xAL:AddressDetails>

<xAL:Country>

<xAL:CountryName>Germany</xAL:CountryName>

<xAL:Locality Type="City">

<xAL:LocalityName>Weingarten</xAL:LocalityName>

<xAL:Thoroughfare Type="Street">

<xAL:ThoroughfareNumber>7</xAL:ThoroughfareNumber>

<xAL:ThoroughfareName>Bussardweg</xAL:ThoroughfareName>

</xAL:Thoroughfare>

<xAL:PostalCode>

<xAL:PostalCodeNumber>76356</xAL:PostalCodeNumber>

</xAL:PostalCode>

</xAL:Locality>

</xAL:Country>

</xAL:AddressDetails>

</xalAddress>

</Address>

</bldg:address>

</bldg:Building>

<bldg:Building>

…

<bldg:address>

<Address>

<xalAddress>






<xAL:Country>

<xAL:CountryName>United Kingdom</xAL:CountryName>


<xAL:LocalityName>LONDON</xAL:LocalityName>

<xAL:DependentLocality Type="District">

<xAL:DependentLocalityName>Battersea

</xAL:DependentLocalityName>

<xAL:Thoroughfare>


<xAL:ThoroughfareName>Brynmaer Road

</xAL:ThoroughfareName>


</xAL:Thoroughfare>

</xAL:DependentLocality>

<xAL:PostalCode>

<xAL:PostalCodeNumber>SW11 4EW</xAL:PostalCodeNumber>

</xAL:PostalCode>

</xAL:Locality>

</xAL:Country>


</xalAddress>

</Address>

</bldg:address>

</bldg:Building>

Fig. 29: xAL fragments currently supported by the Importer/Exporter

When xAL address information in a CityGML instance document does not comply with any of

the two supported xAL templates (because they contain additional or completely different

entries) the address information will only be partially stored in the database if it can be stored

at all. In order to save any given address information and be able to recover it without

information loss the whole <xal:AddressDetail> XML fragment can be imported ‘as is’ from

the original CityGML file and stored in the XAL_SOURCE column of the ADDRESS table in

the 3DCityDB. Simply select the Import original <xal:AddressDetail> XML checkbox under

the Preferences tab, Import node, Address subnode. This option is switched on by default. Note

that the import of the xAL fragment does not affect the filling of the remaining columns in the

ADDRESS table (STREET, HOUSE_NUMBER, etc).

The symmetrical setting for CityGML exports (recovering the XML fragment from

XAL_SOURCE) is explained in section 4.6.3


Fig. 30: Import the original city object's address as XML fragment

4.5.2 Affine Coordinate Transformation With release 1.4.0 of the Importer/Exporter, affine coordinate transformation was added to the

CityGML import functionality: This feature is located under the Preferences tab, Import node,

Geometry subnode. An affine transformation is any transformation that preserves collinearity

(i.e., points lying on a line initially still lie on a line after transformation) and ratios of distances

(e.g., the midpoint of a line segment remains the midpoint after transformation) [14]. It will

move lines into lines, polylines into polylines and polygons into polygons while preserving all

their intersection properties. Geometric contraction, expansion, dilation, reflection, rotation,

skewing, similarity transformations, spiral similarities, and translation are all affine

transformations, as are their combinations [14].

Affine transformations are applied at the very moment of the import, before the new (and

transformed) data is written and committed into the 3D City Database.

http://mathworld.wolfram.com/Transformation.html

http://mathworld.wolfram.com/Collinear.html

http://mathworld.wolfram.com/Line.html

http://mathworld.wolfram.com/Line.html

http://mathworld.wolfram.com/Transformation.html


Fig. 31: Location of the new affine coordinate transformation feature

The affine transformation is defined as the result of the multiplication of the original coordinate

vectors by a matrix plus the addition of a translation vector.

�⃗�′ = 𝐴 ∙ �⃗� + �⃗⃗�

In matrix form using homogenous coordinates:

[𝑥′

𝑦′

𝑧′] = [

𝑚11 𝑚12 𝑚13 𝑚14

𝑚21 𝑚22 𝑚23 𝑚24

𝑚31 𝑚32 𝑚33 𝑚34

] ∙ [

𝑥𝑦𝑧1

]

The coefficients of this matrix and translation vector can be entered as seen in Fig. 31. The first

three columns define any linear transformation; the fourth column contains the translation

vector. The affine transformation does not affect the dimensionality or the CRS system of the

original model, just the object coordinate values are changed. It is applied the same to all

coordinates in all objects in the original CityGML file. This includes all matrix structures

present in CityGML like the 2x2 matrixes of GeoreferencedTextures, the 3x4 transformation

matrixes of TexCoordGen elements used for texture mapping and the 4x4 transformation

matrixes for ImplicitGeometries.


An affine transformation cannot be undone or reversed either in the 3D City Database itself or

at export time. Data that had an affine transformation applied upon import is handled as original.

Two elementary affine transformations are predefined and immediately ready for use. Identity

matrix (leave all geometry coordinates unchanged), which serves as an explanatory example of

how values in the matrix should be set, and swap x/y, which exchanges the values of x and y

coordinates in all geometries (and thus performs a 90 degree rotation around the z axis) and is

very useful for correcting CityGML datasets in which e.g. Northing and Easting values are in

wrong order.

Example: for an ordinary translation of all city objects 100 meters to the east and 50 meters to

the north (assuming all coordinate units are given in meters) the identity matrix must be applied

together with the original translation values set as coefficients in the translation vector:

𝑝′ = [1 0 0 1000 1 0 500 0 1 0

] ∙ �⃗�


4.5.3 Indexes

The Indexes preferences settings menu has been slightly simplified. Buttons for manual

activation or deactivation of spatial or normal indexes can now be found on the database tab

(see 4.8).

Fig. 32: Simplified import indexes preference settings

4.5.4 XML Validation The XML Validation preference settings have not changed their location under the Import node,

but they have also been simplified. The options Perform XML validation during database

import and Just report one error per top-level feature remain, but the choice of the XML schema

documents to be used for validation is suppressed. The internal functionality behind the latter

option was kept, but the choice is now hard-wired and made easier for the user: validation of

an element is dependent on its namespace:

If the element’s namespace is part of the official CityGML 1.0.0 or CityGML 0.4.0

standard, it will be validated against the official CityGML 1.0.0 or CityGML 0.4.0

schema, which are both available locally (no internet access needed).


If the element’s namespace is unknown the element will be validated against the schema

pointed to by the xsi:schemaLocation value on the root element. This last validation step

is necessary when, for instance, the input document contains XML content from a

CityGML Application Domain Extension (ADE) and it requires a properly configured

connection to the internet (see 4.9).

If the element’s namespace is unknown and the xsi:schemaLocation value (provided

either on the root node or the element itself) is empty validation will fail with a hint to

the invalid element and the missing schema document.

Fig. 33: Simplified (but functionally unchanged) XML validation preference settings.


4.6 CityGML Export Enhancements

With the release 1.3.0 of the Importer/Exporter, two new features were added to the CityGML

export functionality: 1) performing a coordinate transformation to an arbitrary user-defined

CRS, and 2) exporting the database content into tiles.

4.6.1 Coordinate Transformation As discussed in the previous chapter 4.4, the geometry of city objects stored in the 3D City

Database is internally associated with a fixed Coordinate Reference System (CRS) that has to

be defined at database setup and shall not be changed afterwards.

Previous versions of the Importer/Exporter could only export data in that same CRS. Since

release 1.3.0 the Importer/Exporter allows applying a coordinate transformation into another

CRS during CityGML exports. A user-defined CRS must be provided as target reference system

(cf. chapter 4.4 for guidance on the management of user-defined CRSs).

Using the CRS combo box at the top of the CityGML Export tab, simply choose the target

reference system from the list of CRSs as seen in Fig. 34. The combo box will be automatically

adapted to only show CRS having the same dimensionality as the original data plus Same as in

database (no transformation). Exporting to a 3D CRS from original data in a 2D CRS or the

other way around will not be possible.

Fig. 34: Choosing a user-defined CRS as target reference system for a coordinate transformation applied during

the CityGML export.


Note: For CityGML imports there is currently no automatic or user-definable coordinate

transformation into the internal CRS of the 3D City Database instance available. Please

make sure that the spatial reference system specified in the CityGML instance

document matches the CRS of the 3D City Database instance prior to importing data.

If the CRS of the CityGML instance document to be imported does not match, the

following workaround procedure can be applied:

1) Set up a second (temporary) instance of the 3D City Database with an

internal CRS matching the CRS of the CityGML instance document.

2) Import the dataset into this second 3D City Database instance.

3) Export the data from this second instance into the target CRS by applying a

coordinate transformation during the export as explained above.

4) The exported CityGML document now matches the CRS of the target 3D

City Database instance and can be imported into that database.

Support for coordinate transformations during CityGML imports will be added in future

versions of the Importer/Exporter.


4.6.2 CityGML version

The previously called CityGML modules panel under the Export preferences has been renamed

to CityGML version since release 1.4.0 and the contents were rearranged to be more user-

friendly. Now the CityGML format version of the output document is constant through all

elements (Core, Appearance, Building, etc.). The CityGML format version can be chosen to be

v1.0.0 (OGC Encoding Standard), which is the default, or v0.4.0 (for compatibility in older

environments). It is no longer possible to switch versions among the features from different

CityGML modules within the same instance document.

Support for the new CityGML 2.0.0 standard will be included with the next major release

scheduled for the first half of 2013.

Fig. 35: Greatly simplified CityGML version choice for the output document

4.6.3 Address data reconstruction

As a counterpart to the enhancement regarding address storage for the CityGML import (see

chapter 4.5.1), the address export capabilities have been consistently extended with release

1.5.0 of the Importer/Exporter.

Before this extension the address information exported to a CityGML file was composed

exclusively from the data contained in the separate columns of the ADDRESS table in the


3DCityDB. As discussed in 4.5.1, these entries may not contain all data present in the original

file or they may even contain no data at all when the address information differs too much from

the two supported xAL templates shown in Fig. 29. In such cases, using the original

<xal:AddressDetail> XML fragment previously saved in the XAL_SOURCE column is the only

means to achieve a lossless reconstruction of the initial address data.

Fig. 36: Extended address export capabilities

Since the storage of the original <xal:AddressDetail> XML fragment at import time does not

exclude the filling of the rest of the columns in the ADDRESS table (STREET,

HOUSE_NUMBER, etc.) there are two possible ways to build up the address contents when

exporting from the 3DCityDB: 1) the conventional mode, reading every single column entry

and putting each value at its corresponding place on the xAL tree (according to the first template

shown in Fig. 29); and 2) the lossless one, that simply takes the whole xAL fragment exactly

as it was imported into the XAL_SOURCE column and inserts it literally as subelement of the

<core:xalAddress> node of the city object being exported. These two methods are mutually

exclusive but one can be used as a fallback alternative to the other if the first chosen renders no

results. By default the first method will be chosen with no fallback alternative.

<bldg:Building>

…

<bldg:address>

<Address>

<xalAddress>





<xAL:Country>




<xAL:DependentLocality Type="District">

<xAL:DependentLocalityName>Battersea

</xAL:DependentLocalityName>

<xAL:Thoroughfare>




</xAL:Thoroughfare>

</xAL:DependentLocality>

<xAL:PostalCode>


</xAL:PostalCode>

</xAL:Locality>

</xAL:Country>


</xalAddress>

</Address>

</bldg:address>

</bldg:Building>

<bldg:Building>

…

<bldg:address>

<Address>

<xalAddress>




<xAL:Country>




<xAL:Thoroughfare>




</xAL:Thoroughfare>

<xAL:PostalCode>


</xAL:PostalCode>

</xAL:Locality>

</xAL:Country>


</xalAddress>

</Address>

</bldg:address>

</bldg:Building>

Fig. 37: Address build-up at export. First with the lossless method, recovering the whole <xal:AddressDetail>

XML fragment, then with the conventional one. Notice the loss of the DependentLocality District

Battersea information in the second case.


4.6.4 Unique texture filenames

For practical reasons, texture filenames in 3D models tend to be repetitive. They are often made

up of a default prefix (e.g. ”tex”) and a number incremented by 1 for each new image. Such

naming schemes are especially likely when texture names are assigned automatically. It is not

an unusual case that texture names are repeated for two or more city objects within the same or

different instance documents. This is not a problem for the storage in the 3D City Database,

since the contents and names of the images are kept in separate records. But when exporting

the CityGML model all texture files will be saved into the same subfolder (per tile), meaning

that depending on the Overwrite settings in the Preferences (node Export, subnode Appearance)

only the first or the last texture with that repeated name will be included in the model. This can

lead to false visualizations when texture contents are applied to the wrong surfaces simply

because their texture filenames happen to be identical to the texture filenames for some other

unrelated surfaces. Further processing of the model (like importing in another 3D City

Database) is discouraged since information got lost in the export process and the visualization

errors will propagate.

Fig. 38: Appearance preference option to generate unique texture filenames


There is a possibility to easily avoid that situation since version 1.4.0 of the Importer/Exporter

Tool. Selecting the Generate unique texture filenames checkbox will ensure that all exported

texture filenames in one export are different and no visualization conflict can arise. Since this

is solved by replacing the original texture filenames with a combination of “tex” (constant) and

the ID of the corresponding SURFACE_DATA entry in the 3DCityDB (which must be unique

due to database constraints), the uniqueness of the resulting texture filenames is guaranteed not

only for each export at a time but also among different exports of one and the same 3D City

Database.

This feature is not required for KML/COLLADA exports. Exports in this format (regardless of

the chosen kml/kmz extension) are divided into subfolders for each city object where texture

filenames are necessarily unique.

4.6.5 Tiling

When exporting the entire 3D city model stored in the 3D City Database into a single CityGML

instance document, the resulting file easily becomes very large. Although the Importer/Exporter

supports writing files of arbitrary size (only limited by the file system of the operating system),

such files may be too large to open in other applications. Furthermore, if the 3D city model is

fully textured then the number of texture files exported into the same subfolder may become

very high. This, in turn, may adversely affect the file access time.

Starting from its first release, the Importer/Exporter allows for applying a spatial bounding box

filter to CityGML exports which helps in reducing the number of exported features and thus of

the resulting file size. If however the area of interest is still comparatively large the user has to

manually divide the area into smaller areas.

Starting from release 1.3.0, the Importer/Exporter provides the possibility to automatically tile

the area specified by a bounding box filter. A corresponding user dialog has been added to the

Preferences tab. It is available as subnode of the Export preferences node as shown in the

following Fig. 39.


Fig. 39: Tiled export options under the Preferences Export tab.

Tiled exports are only available with the bounding box filter being enabled on the CityGML

Export tab (further filters can of course additionally be used). To make use of the new tiling

feature, please check the Tile bounding box option. If this option is unchecked, the only

available settings for the bounding box filter are shown in the section Feature selection using

bounding boxes on top of the user dialog. These settings have already been introduced in the

first release of the Importer/Exporter and are used to indicate whether only objects fully covered

by the bounding box will be exported or also those partially covered by it.

When tiling is selected, the Feature selection using bounding boxes section becomes inactive

and all other options of this preferences tab are available. First, the number of rows and columns

of the (resulting gridded) export must be specified. Space is distributed evenly among them, so

that all rows have the same height and all columns the same width. To decide whether a feature


has to be exported within a specific tile, the center of its envelope (column ENVELOPE of the

table CITYOBJECT) has to be either inside or on the left or top border of the tile.

When exporting, a subdirectory will be created for each tile. These subdirectories are located

beneath the main export directory specified on the CityGML Export tab. They all share a

common freely choosable name part and a tile specific suffix. The suffix may contain the row

and column number of the tile exported or a combination of the tile's minimum / maximum

coordinates. If a coordinate suffix is chosen, the coordinates will be given in the reference

system specified for the CityGML export (cf. chapter 4.6.1, default value is the internal SRS of

the 3D City Database instance), even if the coordinates of the bounding box filter are given in

another user-defined SRS. Thus it will be easier to track which object belongs to which tile,

since the coordinates of the objects contained in the tile are exported in the same reference

system. The file name of the CityGML instance document created per tile may also receive a

tile specific suffix. If the corresponding option is selected, the suffix will be the same as for the

tile directory.

For further traceability it is possible to attach a CityGML generic attribute called TILE to each

exported feature, indicating which tile it belongs to. The options for identifying the tile (the

value of this generic attribute) are the same as for the tile directory suffix.

Note: If the entire 3D city model stored in the 3D City Database instance shall be exported

with the new tiling feature enabled, a bounding box spanning the overall area of the

model has to be provided. This bounding box can be easily calculated using a new

database operation introduced in release 1.4.0 which is available on the Database tab

(cf. chapter 4.8).

Note: Using the center of an object’s envelope as topographical criterion for a tiled export

leads to a side-effect when tiling is combined with the feature count filter on the

CityGML Export tab: the number of objects being exported can no longer be exactly

determined since the calculation of the object's envelope center must be done at a later

point in time. Therefore, the feature count filter only sets a possible maximum value

in this filter combination. For instance: when set to export cityObjectMember /

appearanceMember / featureMember from #1 to #500, only #493 may be reached

without the 3D City Database Importer/Exporter reporting any errors, since the

missing 7 objects were discarded after being queried due to their envelope center not

being within the tile.


4.7 Rework and Redesign of the Matching/Merging Tool

The Matching/Merging tool was substantially reworked in release 1.3.0 of the 3D City Database

and the Importer/Exporter. In release 1.4.0 it was even separated from the core to become an

optional plugin. First, identified bugs were fixed in the underlying PL/SQL database

procedures. Second, the user interface was redesigned in order to improve usability. The goals

of the Matching/Merging tool as well as its mode of operation and process workflow have not

been changed in this release. Thus, the general description of the tool given in chapter 5 of the

previous 3D City Database 2.0.1 documentation [1] still holds for this release. This section only

presents additions to the former documentation.

User interface changes

The following Fig. 40 sketches the changes on the main tab Matching of the Importer/Exporter.

Most of the changes result from rearranging GUI elements without modifying their original

meaning. Settings related to candidate and master buildings have been grouped together to

better grasp the input and output parameters for the matching/merging process.

The left hand side of Fig. 40 shows the previous design of the Matching/Merging tool as

contained in version 1.2.2 of the Importer/Exporter. The redesigned layout shipped with version

1.4.0 is shown on the right. User input fields have been numbered. Input fields with identical

meaning share the same number (shown in red). Green numbers are used to mark new input

fields which were introduced with release 1.4.0.

Fig. 40: Redesigned user interface of the matching/merging tool (left: the previous user interface as contained in

version 1.2.2 of the Import/Export tool, right: the current user interface as contained in version 1.4.0 of the

Import/Export tool). Corresponding input fields share the same numbering.

1 2

1 2 3

3 4

4

5

5

6

6

7

7

8

8

9 9

10 11

13

12


The Matching/Merging tool has been augmented with the following input fields and

functionalities:

Support for version-enabled databases

Similar to other tabs of the Import/Export tool, the input group Versioning has been

added on top of the Matching tab. The two new fields Workspace (10) and Timestamp

(11) allow for specifying an Oracle workspace on which the matching/merging process

shall be executed (default is LIVE).

Tolerance value for geometry operations

The tolerance input field (12) allows for defining a tolerance value which is passed to

Oracle’s spatial functions used in the matching/merging process. Tolerance is used to

associate a level of precision with spatial data and reflects the distance that two points

can be apart and still be considered the same (for example, to accommodate rounding

errors; please check the Oracle Spatial User's Guide and Reference for further

information). The tolerance value is a number of the units that are associated with the

internal CRS of the 3D City Database. For example, if the unit of measurements is

meter, a tolerance value of 0.005 indicates a tolerance of 0.005 meter (that is, 1/200

meter), and a tolerance value of 2 indicates a tolerance of 2 meters. Please make sure to

pick a reasonable value that fits your data.

Adapt minimum overlap

Whether a candidate building and a master building are considered a match depends on

the user-defined minimum overlap values for their projected 2D geometries (fields 4

and 5; cf. chapter 5.3 of the 3D City Database 2.0.1 documentation [1]). In the former

1.2.2 release, changing these values for a given set of candidates and masters required

the restart of the entire matching procedure. The new button “Adapt minimum overlap”

(13) allows for quickly influencing the matching result based on new minimum overlap

values.

There are also minor changes to the Preferences section of the matching/merging tool as shown

in Fig. 41.

Fig. 41: Reworked preferences section of the matching/merging tool (left: the previous user interface as

contained in version 1.2.2 of the Import/Export tool, right: the current user interface since version 1.4.0 of the

Import/Export tool). Corresponding input fields share the same numbering.

1 2 1

2


The preferences node “gml:name” has been renamed to “Master“ since its settings only affect

the master buildings in the merging process. For the same reason, “Data cleanup” has been

renamed to “Candidate”. The contents of both preferences nodes remain the same as in the

previous 1.2.2 release. Finally, “Matching table” has been entirely removed from the

preferences section.

Bug fixes

The underlying PL/SQL procedures of the matching/merging tool were completely reworked

for release 1.4.0 to fix identified bugs:

Support for both Oracle 11g and 10g

The former version of the Matching/Merging tool was only designed for Oracle 10g R2.

The matching/merging process will abort with errors on Oracle 11g R1 and Oracle 11g

R2 when 3D coordinate reference systems are used for spatial objects. These bugs were

fixed and the PL/SQL procedures now bring full support for Oracle 11g.

Support for version-enabled databases

Older versions of the Matching/Merging tool did not correctly work on databases with

version-enabled tables. This bug was fixed with release 1.4.0.

Issues with moving appearances from candidates to master buildings

In some rare situations, appearances were not correctly moved from the candidate

building to the matched master building. The processing of appearances was reworked

to fix this bug.

The new PL/SQL procedures of the matching/merging tool are contained in the 2.0.6

distribution package of the 3D City Database (check files MATCH.sql and MERGE.sql in

the subfolder ./oracle_spatial/PL_SQL/GEODB_PKG/MATCHING).


4.8 Extensions to the Database tab and preferences

The Database tab of the Importer/Exporter was augmented in release 1.3.0 with a Database

operations section marked in red in the following Fig. 42. This part was further refined in

release 1.4.0.

Fig. 42: Additions to the Database tab of the Importer/Exporter.

The new section contains three tabs enabling execution of the following operations after

successfully connecting to a database:


Generate database report

This functionality is already included since the 1.2.2 release of the Importer/Exporter

and has not been changed with this release. The output is a list of all tables and the

number of contained data rows printed to the console window.

Calculate maximum bounding box

This operation allows for the calculation of the maximum bounding box of all city

objects within the database. The resulting 2D coordinates of the bounding box (given as

lower left corner and upper right corner) are filled in the fields Xmin, Ymin, Xmax, Ymax

respectively and automatically copied to the clipboard. They can be used, for example,

as input for the bounding box filters offered by the CityGML import and export as well

as the KML/COLLADA export (you will need to paste the values).

The input city objects for the calculation of the bounding box can be restricted to a

specific CityGML top-level feature type (e.g., Building, WaterBody, etc.). Furthermore,

the resulting bounding box coordinates may be transformed to a different coordinate

reference system (cf. chapter 4.4 for a description of the new support for user-defined

CRS introduced with release 1.4.0).

The following Fig. 43 shows an example for the calculation of a maximum bounding

box of a 3D City Database instance. The resulting bounding box is additionally

transformed to the WGS84 reference system. For this purpose, a corresponding user-

defined CRS (WGS84) was created.


Fig. 43: Calculate maximum bounding box of a database workspace under the Database tab.

The whole maximum bounding box of all city objects of any type within the database

can be now visualized by clicking on the Open Map Window button included in the

Bounding box tab. A Copy to Clipboard button is included as well.


Fig. 44: Area covered by the Berlin 3D City Database. Notice the BoundingBox coordinates on the left side

Activate and deactivate Indexes manually

Spatial and normal indexes in the currently connected database can be activated or

deactivated manually. Their status can also be checked. Results will be shown in the

console window. Clicking on the Activate or Deactivate buttons will only trigger the

activation or deactivation process, the process itself can take a long time depending on

the database fill level and it cannot be aborted by the user since this could lead to an

inconsistent database state.


Fig. 45: Manual activation and deactivation of any index type

The user can define an Oracle workspace on which all three operations shall be executed

(default is LIVE). Similar to other tabs of the Importer/Exporter, the two input fields Workspace

and Timestamp are used to specify the target Oracle workspace.

In addition, a new Database preferences node has been introduced on the Preferences tab of

the Importer/Exporter as shown in the Fig. 46. The Reference systems subnode facilitates the

support and management of user-defined coordinate reference systems. Please refer to chapter

4.4 of these release notes for more information.


Fig. 46: New Database preferences node on the Preferences tab of the Importer/Exporter.


4.9 Proxy support in preferences

Some of the functionalities implemented in the Importer/Exporter require Internet access. This

applies, for instance, to the XML validation when looking for the official xsd document or to

web services called by the map window for the graphical selection of bounding boxes

(OpenStreetMap service), or to web service called for the automated calculation of generic

attribute GE_LoDn_zOffset in order to properly placing KML/COLLADA models onto the

ground (Google elevation service), as explained in 4.3.2.4.

Most computers in corporate environments have no direct internet access but must use a proxy.

The Importer/Exporter tool offers support for this configuration through the newly added

Network proxies panel under Preferences - General.

Fig. 47: New HTTP proxy preferences menu under the General node


Several proxy types can be configured separately. The Importer/Exporter Tool supports Web

(HTTP), Secure web (HTTPS) and SOCKS proxies. Usually, configuring a Web proxy is enough

for most tasks, like those mentioned above. However, more sophisticated use cases, like

uploading cloud documents via an Importer/Exporter extension plugin (available since release

1.4.0) may require Secure web proxy (HTTPS) support. SOCKS proxy support should currently

only be needed when the Importer/Exporter Tool and the 3D City Database it connects to reside

in different networks.

Whenever one of the protocols to be handled by a proxy is selected the corresponding settings

are filled in the fields below: Server, Port, and if the proxy requires login credentials Username

and Password. It is recommended to keep the preset default Port values for each protocol

(HTTP: 80; HTTPS: 443; SOCKS: 1080).

It is possible to set one single proxy for all protocols by simply selecting the checkbox under

the protocol list. Just make sure the proxy supports all of them and they can all be routed through

the given Port.

Proxies will only be used when the checkbox next to the protocol type is selected. Otherwise

the proxy configuration data will be stored but remain inactive. When the proxy for a given

protocol is actively used every outgoing connection by the Importer/Exporter which relies on

this protocol will be routed through this proxy.

In case the computer running the Importer/Exporter is directly connected to the internet none

of these settings are needed.


4.10 New PL/SQL functionality

4.10.1 PL/SQL package GEODB_DELETE

Starting from its first release, the 3D City Database has been shipped with a set of PL/SQL

packages which are automatically installed during the setup procedure of the 3D City Database.

These packages are required by the Importer/Exporter. The PL/SQL packages shipped with the

version 2.0.6 of the 3D City Database are a mandatory dependency of the Importer/Exporter

version 1.4.0 to 1.6.0. Version 2.1.0 provides additional but optional extensions to the PL/SQL

packages.

The PL/SQL packages and their provided functionality can also be used to build third-party

applications besides the Importer/Exporter on top of the 3D City Database. The following table

enumerates the available PL/SQL packages together with a short description. All package

names share the common prefix GEODB.

Package name Description

GEODB_IDX Provides functions to create, drop, and check both spatial and

non-spatial indexes on tables of the 3D City Database.

GEODB_MATCH and

GEODB_MERGE

GEODB_MATCH implements the required functions and

procedures to facilitate the matching of candidate and master

buildings in the database. Based on the matching results, the

GEODB_MERGE package allows for merging identified

buildings.

Please check chapter 5 of the previous 3D City Database 2.0.1

documentation [1] as well as chapter 4.7 of this document for

more information.

GEODB_STAT Creates a report on the number of entities currently stored in all

tables of the 3D City Database.

GEODB_UTIL Contains utility functions.

GEODB_DELETE_BY_LINEAGE Deletes all buildings sharing a common LINEAGE attribute (see

table CITYOBJECT). Associated features and geometries will

also be deleted.

With the 2.0.6 release of the 3D City Database, a new PL/SQL package called

GEODB_DELETE was added to this list. It provides procedures that facilitate the deletion of

single city objects in the database. Whilst the initial release of this package was restricted to the

deletion of buildings, version 2.1.0 of the 3D City Database now complements the package with

delete procedures for all CityGML feature types.

The DELETE procedures do automatically take care of the many associations and dependencies

between the city objects stored in the database. For example, when deleting an entry from the

BUILDING table, also its associated boundary surfaces stored in THEMATIC_SURFACE as

Since 2.1.0


well as its addresses stored in ADDRESS are automatically removed. And, of course, also its

geometry representations in all LoDs are deleted from SURFACE_GEOMETRY which again

triggers the deletion of appearance information attached to these geometries. Thus, the entire

building will be cleanly removed from the database.

The following overview lists the available delete procedures:

delete_surface_geometry(pid number, clean_apps int := 0)

delete_implicit_geometry(pid number)

delete_external_reference(pid number)

delete_citymodel(pid number)

delete_appearance(pid number)

delete_surface_data(pid number)

delete_cityobjectgroup(pid number)

(Note: this will only delete the CityObjectGroup entry itself but not its members)

delete_thematic_surface(pid number)

delete_opening(pid number)

delete_address(pid number)

delete_building_installation(pid number)

delete_room(pid number)

delete_building_furniture(pid number)

delete_building(pid number)

delete_city_furniture(pid number)

delete_generic_cityobject(pid number)

delete_land_use(pid number)

delete_plant_cover(pid number)

delete_solitary_veg_obj(pid number)

delete_transport_complex(pid number)

delete_traffic_area(pid number)

delete_waterbnd_surface(pid number)

delete_waterbody(pid number)

delete_relief_feature(pid number)

delete_relief_component(pid number)

delete_tin_relief(pid number)

delete_masspoint_relief(pid number)

delete_breakline_relief(pid number)

delete_raster_relief(pid number)

cleanup_appearances(only_global int :=1)

cleanup_cityobjectgroups

cleanup_citymodels

cleanup_implicitgeometries

delete_cityobject(pid number)

Most of the procedures take the primary key id value (PID) of the entry to be deleted as input

parameter. For delete_surface_geometry an optional second parameter CLEAN_APPS can

Since 2.1.0


be provided. CLEAN_APPS acts as a flag taking two values 0 (false) and 1 (true) in order to

indicate whether appearance information associated with the geometry to be deleted should also

be removed (default is false). The procedure cleanup_appearances removes all

appearance entities that lack an associated geometry element. It also takes a flag called

ONLY_GLOBAL as optional input parameter. If ONLY_GLOBAL is set to true (which is the

default value), only global appearance information will be deleted. Please refer to the CityGML

1.0 specification document [2] for a comprehensive description of global and local appearance

information in CityGML. The cleanup procedures cleanup_cityobjectgroups and

cleanup_citymodels remove those groups and city models that do not contain members.

Likewise, cleanup_implicitgeometries deletes all tuples from IMPLICILT_GEOMETRY

that are not referenced by any city object any more.

Finally, delete_cityobject is a convenience procedure that can be called without having

to worry about the feature type of the city object to be deleted. The delete_cityobject

procedure will delegate the call to the correct delete procedure (e.g., delete_building in

case a building tuple is stored at the passed PID value).

Note: The deletion of raster terrain models (RasterRelief) or associated orthophotos is not

implemented since these elements will no longer be supported in the future.

The GEODB_DELETE package is meant as low-level API for the deletion of single city objects.

More complex delete operations (such as “Delete only a specific LoD from a given building”,

or “Delete all buildings within a given address range”) can be built on top of these low-level

operations. The GEODB_DELETE_BY_LINEAGE package exemplifies this for the deletion of

buildings sharing a common value in the LINEAGE column of the CITYOBJECT table. As for

version 2.1.0 of the 3D City Database, also the GEODB_DELETE_BY_LINEAGE package has

been complemented with procedures for all CityGML feature types besides buildings.

In future releases, the GEODB_DELETE package will be accompanied by further low-level

APIs to create and modify single objects. This will facilitate to build complex applications

based on a straightforward API for the 3D City Database.

Since 2.1.0


4.10.2 Creating Read-Only Users

In order to protect your data from unauthorized or accidental modification it can be convenient

to define users having read-only access to the 3DCityDB. These users will be allowed to

connect to the database and export data in both CityGML and KML/COLLADA formats, but

they will be able to neither import new data into the 3DCityDB nor alter the data already stored

in the tables in any way.

A dedicated script for the purpose of creating a user with read-only access to the 3DCityDB is

included within the 3D City Database 2.1.0 SQL package in case the installation of this package

was chosen during the setup process.

Step by step guide through the create read-only user procedure

1. Open a console window.

2. Change the working directory to the folder where the contents of the 3D City Database

distribution package are located. In that folder, change to the UTIL/RO_USER

subfolder. There is a single file in this subfolder called CREATE_RO_USER.sql.

3. Open a SQLPlus connection to the database and login as admin. Any SQLPlus client

software may be used.

4. Execute the script CREATE_RO_USER.sql by typing

"@CREATE_RO_USER;" at the SQLPlus prompt.

Note: Make sure to change to the UTIL/RO_USER folder before running SQLPlus

and executing this command.

Fig. 48: Entering the data for a new read-only user.


5. You will be asked to enter the name of the new read-only user to be created. This user

must not exist in the database yet. Then you will be asked to enter the name of the

owner of the schema (the user actually holding the city model data) to which this user

shall have read-only access to. The owner of the schema must exist in the database prior

to executing this script.

6. The read-only user will be created and the script will exit informing you of whether it

finished successfully or not.

Fig. 49: Read-only user was successfully created.

7. The newly created read-only user will have a default expired password "berlin3d"

(without quotes). You must log in at least once with this password and change it to a

new valid one for this user to be able to do some work on the 3DCityDB.

8. You can now start the Import/Export Tool, define a database connection on the

Database tab with this user's data, and start working (CityGML and KML/COLLADA

exports only).

Note: Read-only users created with older versions of the 3DCityDB (2.0.3 or 2.0.5) will not

work on Oracle databases upgraded to 2.1.0. Old read-only users must be dropped (no

data will be lost in the process since read-only users hold none) and created again with

the 2.1.0 version of the CREATE_RO_USER script.


4.11 Test data and template files

The Importer/Exporter is shipped with a set of sample data comprising:

CityGML instance documents

Included are several CityGML instance documents which facilitate the testing of the

CityGML import and export functionality as well as the newly introduced

KML/COLLADA export capabilities.

KML/COLLADA models

Sample KML/COLLADA models are provided which were created using the

KML/COLLADA export feature. The models demonstrate many of the possibilities

offered by this tool. They are ready for use and exploration in any viewer application

supporting the KML and COLLADA formats, but have especially been tested for use

with the earth browser Google Earth.

KML balloon template files

One feature of the KML/COLLADA exporter is the creation of KML information

balloons which are associated with the exported building objects. User-defined template

files determining the layout and contents of the balloons can be fed to the

Importer/Exporter. Simplified query expressions allow for filling the balloon templates

with object-related information at export time. The Importer/Exporter is shipped with

several example balloon templates demonstrating this feature including the recent

addition of SPECIAL_KEYWORDS as explained in chapter 4.3.2.3.

Coordinate Reference System template files

A small set of CRS templates which are provided in separate files and, thus, can be

easily imported and added to the list of user-defined CRSs in the Importer/Exporter.

The URN encoding of these predefined CRSs generally lacks a height reference system

which has to be added before using this CRS as target reference system for CityGML

exports (cf. chapter 4.4 for more information).

The contained CityGML and KML/COLLADA datasets can be found in the subfolders

samples/CityGML respectively samples/KML_COLLADA within the installation folder

of the Importer/Exporter. The datasets are optional and will only be copied to this location if

the corresponding option is selected in the setup wizard of the Importer/Exporter during the

installation procedure (by default, the sample datasets will be installed). The datasets require

approx. 100MB of additional hard disk space.

The KML balloon template files are located in the subfolder templates/balloons of the

installation folder. They will always be available after installation of the Importer/Exporter and

may serve as a starting point for attaching information bubbles to your KML/COLLADA

models. Finally, the CRS template files are organized in subfolders beneath the

templates/CoordinateReferenceSystems folder located in the installation folder.

Further information and descriptions of the sample test data as well as the KML balloon

template files are provided in additional README files.


5 Requirements

This chapter provides an overview of the minimum requirements for the 3D City Database and

the Importer/Exporter tool. Please carefully review these requirements. Additional information

can be found in the previous documentation of the 3D City Database version 2.0.1 (cf. [1]).

3D City Database

Since release 1.4.0 (3D City Database 2.0.6) both the Importer/Exporter and the 3DCityDB are

no longer constrained to an Oracle Spatial installation, but can alternatively work on top of a

PostgreSQL/PostGIS database. This is achieved by means of two separate software packages

specifically coded for the database vendor they are intended to work with.

The version for Oracle of the 3D City Database requires access to a working installation of one

of the following DBMSs:

Oracle Spatial 10g R2,

Oracle Spatial 11g R1, or

Oracle Spatial 11g R2.

Installation of all available patches from Oracle is highly recommended for optimal stability

and performance. For Oracle 10g R2, at least patch set 10.2.0.4.0 is required for using the

Matching/Merging tool or the newly introduced KML/COLLADA export capabilities.

The version for PostgreSQL/PostGIS requires access to a working installation of:

PostGIS version 2.0 or higher. PostGIS 2.0 itself requires PostgreSQL 8.4 or higher,

For 64-bit Windows only PostgreSQL 9.0 or higher can be used.

Make sure to execute the SQL scripts v2.1.0 shipped with this release for setting up a new

instance of the 3D City Database on top of your DBMS. In case an existing 3D City Database

instance of previous version 2.0.5 or lower shall be upgraded, please stick to the upgrade

guidelines given in chapter 6.

Importer/Exporter Tool

The Importer/Exporter tool can run on any platform providing support for Java 6. It has been

successfully tested on (but is not limited to) the following operating systems: Microsoft

Windows XP, Vista, 7; Apple Mac OS X 10.6; Ubuntu Linux 9, 10, 11.

Prior to the setup of the Importer/Exporter tool, the Java 6 Runtime Environment (JRE version

1.6.0_05 or higher) or Java 7 Runtime Environment (JRE version 1.7.0_03 or higher) must be

installed on your system. The necessary installation package can be obtained from

http://www.java.com/de/download.

The Importer/Exporter tool is shipped with a universal installer that will guide you through the

steps of the setup process. A full installation of the Importer/Exporter including documentation

and example CityGML files requires approx. 110 MB of hard disk space. Installing only the

http://www.java.com/de/download


mandatory application files will use approx. 16 MB of hard disk space. Installation packages

can be chosen during the setup process.

The Importer/Exporter and requires at least 256 MB of main memory. For the import and export

of large CityGML respectively KML/COLLADA files, a minimum of 1 GB of main memory

is recommended.

Please note that Importer/Exporter v1.4.0 and v1.5.0 have a mandatory dependency on the 3D

City Database v2.0.6. The Importer/Exporter v1.6.0 can be used with databases of either version

v2.0.6 and v2.1.0. Read more about this in the database upgrade guidelines given in the

following chapter 6.


6 Upgrade from previous versions of the 3D City

Database

Older versions of the 3D City Database (version 2.0.0 to 2.0.5) must be upgraded to version

2.0.6 / 2.1.0 in order to include the latest bug fixes and make use of the new features of the

Importer/Exporter tool from release 1.4.0 upwards. The new 1.6.0 release of the

Importer/Exporter can be used with both versions 2.0.6 and 2.1.0 of the 3D City Database.

Thus, in case a 3D City Database instance is already running version 2.0.6, no action needs to

be taken and the Importer/Exporter 1.6.0 can be used right away. In order to benefit from the

latest changes to the GEODB_DELETE package, an upgrade of the 3D City Database to version

2.1.0 is required though.

Note: Versions prior to 1.5.0 of the Importer/Exporter tool will still be able to connect to the

current 3D City Database 2.1.0. However, this is strongly discouraged since

inconsistent values would be written in the ENVELOPE column of the CITYOBJECT

table (see 3.1) at import time, and exports could also fail due to the differences in 3D

CRS support offered between versions. Further unexpected behavior leading to severe

database errors may also occur.

The 3D City Database 2.1.0 SQL package includes an upgrade script which will automatically

perform the database upgrade. Upgrades to 2.1.0 can be carried out from any older version 2.0.0

to 2.0.6 (2.0.4 was an internal build only and has not been released for the public). No

intermediate upgrades between lower versions are necessary.

Note: Upgrading does not change the existing table structure but it might affect data stored

in the table CITYOBJECT. The upgrade procedure can be applied to a running

database instance. However, it is recommended to first apply the upgrade in a testing

environment before upgrading a production system. Furthermore, a database backup

is recommended to secure all data. The latter can be easily done using the

Importer/Exporter tool or by tools provided in the Oracle DBMS package.

Changes carried out in the upgrade procedure

1. Uninstallation of the previous version of the GEODB PL/SQL package

The GEODB PL/SQL package is part of each release of the 3D City Database. It contains

several subpackages offering a range of functionality for use with the 3D City Database.

The Importer/Exporter relies on these packages and they can also be used by third-party

applications. With release 1.4.0, some of these packages were reworked and new

packages were added. The upgrade script will thus cleanly remove any previous version

of the GEODB package.

2. Installation of the GEODB PL/SQL package version 2.1.0

Since the GEODB PL/SQL package is a mandatory dependency of the

Importer/Exporter version 1.4.0 and upwards, the upgrade script will install the latest


version of this script in a second step.

3. Renaming of indexes and constraints

Oracle allows a maximum of 30 characters for index and constraint names on tables. If

these tables are version-enabled, one has to make sure that the names do not exceed a

maximum of 26 characters since Oracle internally appends suffixes required for the

version management. However, some of the index and constraint names of previous

versions of the 3D City Database are longer than 26 characters. This causes errors in

some functions of Oracle’s Workspace Manager if versioning support is enabled. To

overcome this problem, the affected names are shortened in the third step of the upgrade

procedure.

4. Creation of additional indexes

With the release of version 2.0.2 of the 3D City Database, two additional indexes were

introduced on the table APPEAR_TO_SURFACE_DATA which help to improve

performance when exporting fully textured models from the database. The upgrade

script makes sure to add these two indexes in a last step if they are missing.

5. Update of CITYOBJECT.ENVELOPE contents

As explained in 3.1, due to compatibility issues with Oracle 11g versions, a small but

significant adaption was made on the contents of the table CITYOBJECT. It affects

how the BoundingBox (column ENVELOPE) is stored. The type must be switched

(from rectangle to simple 3D polygon) and the amount of coordinates increases

accordingly from 6 to 15. The update script makes all these changes automatically. If

the geometry stored in ENVELOPE already satisfies the new storage requirements, it

will not be changed by the script.

Step by step guide through the upgrade procedure

The distribution package of the 3D City Database version 2.1.0 contains all SQL scripts

required for setting up a new instance of the 3D City Database or for upgrading from previous

versions. The package can be downloaded as ZIP archive from the 3D City Database website

at http://www.3dcitydb.net. Alternatively, the setup wizard of the Importer/Exporter offers the

possibility to copy the contents of this distribution package to the installation folder of the

Importer/Exporter (simply choose the corresponding installation package in the setup

procedure). In the latter case, the scripts are located in the subfolder 3dcitydb.

1. Open a console window.

2. Change the working directory to the folder where the contents of the 3D City Database

distribution package are located. In that folder, change to the UPGRADES/2.1.0

subfolder. There is a single file in this subfolder called

UPGRADE_DB_TO_2_1_0.sql. This is the main SQL script controlling the upgrade

procedure. Besides this script, a further subfolder called SCRIPTS is located here.

The SCRIPTS folder contains additional SQL scripts which perform single steps of

the upgrade procedure and are automatically executed in the background.

http://www.3dcitydb.net/


Fig. 50: Preparing for DB upgrade.

3. Open an SQLPlus connection to the account of the 3D City Database which shall be

upgraded. Any SQLPlus client software may be used.

4. Execute the script UPGRADE_DB_TO_2_1_0.sql by typing

"@UPGRADE_DB_TO_2_1_0;" at the SQLPlus prompt. The upgrade will

immediately start and automatically execute the above described upgrading steps. An

upgrade protocol is printed onto the screen (see below).

Note: Make sure to change to the UPGRADES/2.1.0 folder before running SQLPlus

and executing this command.

5. You will be informed about conclusion of the upgrading progress by the message

"DB upgrade complete!" and the returning of the prompt.

IMPORTANT: please note that the last step in the upgrade process is a lengthy one.

Altering the internal storage of the envelopes of all city objects in a large and/or versioned

database may take hours. Depending on their initial state, spatial indexes may be disabled

and re-enabled in the process, adding to the duration as a whole. This process MUST NOT

be interrupted since it could lead to an inconsistent state. Please be patient and remember

that backing up all of your data before starting any database upgrade is the commonly

recommended practice.


Fig. 51: Launching the upgrade script.

SQL> @UPGRADE_DB_TO_2_1_0;

MESSAGE

----------------------

Starting DB upgrade...

Starting GEODB package deletion...

Type STRARRAY deleted

Type INDEX_OBJ deleted

Type DB_INFO_TABLE deleted

Type DB_INFO_OBJ deleted

Package geodb_util deleted

Package geodb_idx deleted

Package geodb_stat deleted

Package geodb_match deleted

Package geodb_delete_by_lineage deleted

Package geodb_delete deleted

Package geodb_merge deleted

Table match_tmp_building truncated

Table match_tmp_building deleted

Table match_overlap_all deleted

Table match_overlap_relevant deleted

Table match_master_projected deleted

Table match_cand_projected deleted

Table match_collect_geom deleted

Table merge_collect_geom deleted

Table merge_container_ids truncated

Table merge_container_ids deleted

GEODB package deletion complete!

PL/SQL procedure successfully completed.


MESSAGE

---------------------------

Installing GEODB package...

Package created.

Package body created.

Package created.

Package body created.

MESSAGE

------------------------

GEODB package installed.

APPEARANCE_TO_SURFACEDAT_PK does not exist - no action required.

RELIEF_FEATURE_TO_RELIEF__PK does not exist - no action required.

CITYOBJECT_GENERICATTRIB_PK does not exist - no action required.

SOLITARY_VEGETATION_OBJEC_PK does not exist - no action required.

CITYOBJECT_GENERICATTRIB_FKX does not exist - no action required.

CITYOBJECT_GENERICATTRIB_FKX1 does not exist - no action required.

SOLITARY_VEGETAT_OBJECT_FKX1 does not exist - no action required.








TRANSPORTATION_COMPLEX_FKX1 does not exist - no action required.




BUILDING_FURN_LOD4REFPNT_SPX does not exist - no action required.

SOL_VEGETAT_OBJ_LOD1REFPNT_SPX does not exist - no action required.




rename_objects.sql successfully finished.

MESSAGE

-------------------------------------------------------------------------------

Creating additional indexes on APPEAR_TO_SURFACE_DATA. This may take a while...

Index APP_TO_SURF_DATA_FKX already exists.

Index APP_TO_SURF_DATA_FKX1 already exists.

MESSAGE

----------------------------------------


Updating CITYOBJECT.ENVELOPE contents...

MESSAGE

--------------------------------------------------------------------------------

Spatial indexes will be disabled and re-enabled after update. This make take a l

ong time and SHALL NOT be interrupted. Please be patient...

Disabling envelope spatial index...

updating envelope contents for all cityobjects in workspace LIVE ...

processed cityobjects in workspace LIVE = 79717; committing...

total processed cityobjects = 79717

Enabling envelope spatial index. This can take long time...

update_cityobject_envelope.sql finished successfully.

MESSAGE

-------------------------------------

CITYOBJECT.ENVELOPE contents updated.

MESSAGE

--------------------

DB upgrade complete!


7 Changelog

The most notable changes and bug fixes from the previous versions of both the 3D City

Database and the Import/Export tool are listed in the following sections. The tables comprise

the revision number and a brief description of the change or bug fix.

The software development progress can be followed at any time at http://opportunity.bv.tu-

berlin.de/software. This website also provides change logs for previous releases of the 3D City

Database and the Importer/Exporter tool.

7.1 Changelog for the 3D City Database

Please visit http://opportunity.bv.tu-berlin.de/software/projects/3dcitydb/repository for a

complete revision overview of the 3D City Database development and access to the source

code.

Notable changes between 2.0.3 to 2.1.0

Revision Description

r117 Complemented DELETE procedures for all CityGML feature types

r103 Improved performance of DELETE procedures

r97 Added script for updating cityobject envelopes in order to avoid ORA-21780 when

doing spatial queries in Oracle 11g.

r90 modified UTIL.sql to allow Importer/Exporter v1.3.x to connect to 2.0.6

databases

r78 Reworked script for creating read-only users to properly work with version 2.0.5.

r74 Added upgrade scripts allowing for upgrading from any previous version of the 3D

City Database (2.0.3 or lower) to version 2.0.5.

r43, r62, r66 Major rework of the matching/merging functionality; matching/merging now

supports both Oracle 10g and 11g.

r39 Added first version of GEODB_DELETE package which allows for the deletion of

single objects in the database.

r33, r34 Reworked GEODB_IDX package (providing helper procedures for spatial and non-

spatial index handling) to correctly work with version-enabled tables.

Bug fixes from version 2.0.3 to 2.1.0

Revision Description

r72 Fixed PlanningManager compilation errors during database creation.

r38 Fixed bugs in DELETE_BY_LINEAGE.sql which prevented the script from

working on versioning enabled tables.

r37 Fixed index/constraint names having more than 26 characters which cause problems

on version-enabled tables.

http://opportunity.bv.tu-berlin.de/software

http://opportunity.bv.tu-berlin.de/software

http://opportunity.bv.tu-berlin.de/software/projects/3dcitydb/repository

http://opportunity.bv.tu-berlin.de/software/projects/3dcitydb/repository/revisions/117


















r35 Fixed bug in database report generator script (GEODB_STAT package).

7.2 Changelog for the Importer/Exporter

Please visit http://opportunity.bv.tu-berlin.de/software/projects/3dcitydb-imp-exp/repository

for a complete revision overview of the 3D City Database Importer/Exporter development and

access to the source code. Due to a server crash, the version control system had to be

reinitialized on 2011-03-07. Changes and bug fixes before that date are not listed in the current

version control system anymore, and thus are given with their date in the following tables.

Notable changes between 1.2.2 to 1.6.0

Revision /

Date Description

r851 KML/COLLADA: COLLADA display form exports extended to LoD1 objects.

r690 KML/COLLADA: LoD0 support added for the corresponding top-level features

r678 KML/COLLADA: export of Relief (currently only TIN_RELIEF)

r672 KML/COLLADA: export of Transportation

r659 KML/COLLADA: export of LandUse

r656 KML/COLLADA: export of WaterBody

r653 KML/COLLADA: export of CityFurniture

r646 KML/COLLADA: export of GenericCityObjects

r623 KML/COLLADA: SPECIAL_KEYWORDS/CENTROID_WGS84_LAT,

SPECIAL_KEYWORDS/CENTROID_WGS84_LON added to balloon handling

r613 added support for importing/exporting xAL fragment

r597 KML/COLLADA: intermediate commit for KML/COLLADA export of vegetation

objects

r518 KML/COLLADA: Added export of CityObjectGroups including own rendering and

balloon settings

r427 CityGML export: optionally generate unique texture filenames

r422 Updated to citygml4j 1.0.1

r412 Improved CityGML export of global appearances

r411 Network proxy implementation supporting different protocols and transparent to

plugin developers

r402 KML/COLLADA: generating texture atlases with side lengths being a power of 2.

r369 update to Oracle 11g JDBC driver version 11.2.0.3

r350 Map dialog for bbox selection

r319 KML/COLLADA: short summary written to the console after each export.

r313 Optional JSON file generation. KML/COLLADA rendering preferences split into

general and rendering.

r306 Substantially improved performance for resolving of geometry XLinks.


http://opportunity.bv.tu-berlin.de/software/projects/3dcitydb-imp-exp/repository

http://opportunity.bv.tu-berlin.de/software/projects/3dcitydb-imp-exp/repository/revisions/851



























r285 New KML/COLLADA export option: each CityObject in a separate file.

r267 Added Plugin API and moved to citygml4j version 1.0

r157 Added standard editing popup menu for cut/copy/paste actions to input fields.

r11 Introduced information about cooperation partners into GUI.

2011-03-04 First integration of 3DCityDB scripts version 2.0.5.

2011-02-26 Major rework of matching/merging PL/SQL functionality.

2010-12-14 Added coordinate transformation to user-defined CRS for CityGML exports.

2010-11-09 Support for the generation of texture atlases during KML/COLLADA exports (out-

sourced in library textureAtlas.jar).

2010-10-15 Added support and management of user-defined CRS.

2010-07-01 Inaccessible options are automatically disabled in the GUI.

2010-06-28 Calculation of bounding boxes for different CityGML feature types and different

coordinate reference systems.

2010-06-04 Tiling can now be applied to CityGML exports.

2010-05-20 First integration of KML/COLLADA export functionality.

Bug fixes from version 1.2.2 to 1.6.0

Revision /

Date Description

r877 better URL handling for import of library objects

r874 KML/COLLADA: better fix for r859 (queries refined in order to avoid redundant

geometry exports).

r867 avoid importing of duplicate target rings of texture coordinates

r859 KML/COLLADA: queries refined in order to avoid redundant geometry exports.

r842 minor bugfixes for duplicate appearance targets and rgba texture images

r827 enhanced method convertGeoPositionToPoint() to also accept an arbitrary zoom

level as parameter

r825 fixed bug with exporting boundary surfaces of buildings and rooms if the SELECT

statements returns the surfaces in mixed order

r824 avoid exporting of generic attributes with NULL value

r823 fixed minor bug with importing/exporting of library objects associated with an

ImplicitGeometry

r822 improved stability of xAL address import when xAL fragment cannot be correctly

interpreted

r818 Bugfix for wrongly mirrored textures in TPIM algorithm.

r815 minor fix in DBThematicSurface when exporting boundary surfaces of rooms

r802 KML/COLLADA: fix for <heading> values in COLLADA placemarks.

r744 KML/COLLADA: bugfix for buildings consisting of building parts modeled

in different LoDs





















r684 KML/COLLADA: internal use of cityobject.id as key instead of cityobject.gmlid

r630 KML/COLLADA: new textureAtlas library including transparency and atlas-

naming fixes

r600 KML/COLLADA: added <unknown> as theme for KML/COLLADA exports when

no theme is present

r546 KML/COLLADA: added BalloonStyle to prevent placemark names from appearing

at the top of the balloons

r524 fix for CityGML export of global appearances being associated to a surface

geometry that is reused through XLinks

r523 fix for texture coordinate strings being longer than 4000 characters

r402 Filtering of CityGML feature types during import is now performed by citygml4j

(faster)

r400 Fixed bug when importing groups

r382 Improved query performance on Oracle 11g

r376 ENVELOPE now stored as planar rectangular 3D surface with 4 corner points to

overcome issues with optimized 3D rectangles on Oracle 11g

r352 Removed bug with default reference system in CLI mode

r336 KML/COLLADA: fix for aggregating geometries for footprint or extruded when no

GroundSurface is modeled. Tolerance values identical to those of matching tool.

r289 Substantially improved performance for resolving of geometry xlinks

r205 Fixed problems with wrong coordinate values of interior rings of polygons which

are referenced by an XLink and which have to be reversed due to an

OrientableSurface at the same time.

r193 Fixed bug when importing/exporting OrientableSurface elements having textures:

The order of texture coordinates was not consistent with the order of coordinate

tuples in case the orientation of the surface had to be flipped.

r154 Texture image URIs containing backslashes as path separator were not correctly

interpreted on UNIX/LINUX machines.

r130, r153 Fixed bug when importing 0 byte texture files.

r114 Changed suffix for artificial gml:ids on gml:LinearRing elements in order to create

unambiguous IDs.

r45 Added batch counter to all CityGML importer classes in order to not exceed Oracle’s

predefined maximum size for batch updates.

2011-03-01 Adapted some SQL queries for faster execution on Oracle 11g

2011-02-18 Fixed missing support for gml:CompositeSolid geometries when exporting

Building, Room, and WaterBody features.

2011-02-08 Minor fixes for import of deprecated CityGML TexturedSurface elements.

2011-01-07 Database connection pool did not correctly handle failed database connections.

2011-01-07,

r42 Fixed Oracle deadlock exceptions caused by update statements in batch mode

(especially when resolving XLinks).

2010-12-14,

r26 Fixed UTF8 issues in GUI and log console.

























2010-12-06 Solid geometries of rooms (lod4Solid property) now reference shared

_BoundarySurface geometries - and not vice versa.

2010-10-21 Fixed bugs with importing ImplicitGeometry instances.

2010-09-30 Fixed bug when exporting appearances with different themes for the same city

object.

2010-07-06 Fixed NPE in DBExporterManager.java.

2010-07-05 Improved memory consumption when importing large CityGML top-level features.

2010-07-01 Added support for <pointMembers> in MassPointRelief.

2010-06-29 Added workspace dialog to matching/merging panel.


8 References

[1] Kolbe, T. H.; König, G.; Nagel, C.; Stadler, A. (2009): 3D-Geo-Database for CityGML,

Version 2.0.1, Documentation, April 24th.

http://opportunity.bv.tu-berlin.de/software/attachments/606/3DCityDB-

Documentation-v2_0.pdf

[2] Gröger G., Kolbe, T. H., Czerwinski, A., Nagel C. (2008): OpenGIS® City Geography

Markup Language (CityGML) Encoding Standard, Version 1.0.0. Open Geospatial

Consortium, Doc. No. 08-007r1, August 20th.

http://portal.opengeospatial.org/files/?artifact_id=28802

[3] Wilson, T. (2008): OGC® KML, OGC® Standard Version 2.2.0. Open Geospatial

Consortium, Doc. No. 07-147r2, April 14th.


[4] The Google Elevation API, Weblink (accessed May 2011):

http://code.google.com/intl/en/apis/maps/documentation/elevation/

[5] Active Server Pages Reference, Weblink (accessed May 2011):

http://msdn.microsoft.com/en-us/library/ms526064.aspx

[6] Barners, M., Finch, E. L. (2008): COLLADA - Digital Asset Schema Release 1.5.0. The

Khronos Group Inc., Sony Computer Entertainment Inc, April 2008.

http://www.khronos.org/files/collada_spec_1_5.pdf

[7] java - the Java application launcher, Weblink (accessed May 2011):

http://download.oracle.com/javase/6/docs/technotes/tools/windows/java.html

[8] British German Academic Research Collaboration Programme on Efficient Algorithms

for 2-D Rectangle packing. Weblink (accessed May 2011):

http://www.csc.liv.ac.uk/~epa/surveyhtml.html

[9] Lodi A., Martello S., Vigo D. (1999): The Touching Perimeter Algorithm: Heuristic and

Metaheuristic Approaches for a Class of Two-Dimensional Bin Packing Problems. In:

INFORMS J on Computing: pp. 345-357.

[10] Lodi A., Martello S., Monaci M., (2002): Two-dimensional packing problems: A survey.

In: European Journal of Operational Research, 141, issue 2, pp. 241-252.

[11] D. Sleator (1980): A 2.5 times optimal algorithm for packing in two dimensions. In:

Information Processing Letters, Volume 10, Number 1, pp. 37–40.

[12] E.G. Coffman Jr., M.R. Garey, D.S. Johnson, R.E. Tarjan (1980): Performance bounds

for level-oriented two-dimensional packing algorithms. In: SIAM Journal on

Computing 9 (1980), pp. 801–826.

http://opportunity.bv.tu-berlin.de/software/attachments/606/3DCityDB-Documentation-v2_0.pdf

http://opportunity.bv.tu-berlin.de/software/attachments/606/3DCityDB-Documentation-v2_0.pdf



http://code.google.com/intl/en/apis/maps/documentation/elevation/

http://msdn.microsoft.com/en-us/library/ms526064.aspx

http://www.khronos.org/files/collada_spec_1_5.pdf

http://download.oracle.com/javase/6/docs/technotes/tools/windows/java.html

http://www.csc.liv.ac.uk/~epa/surveyhtml.html


[13] Whiteside, A. (2009): Definition identifier URNs in OGC namespace, Version 1.3. Open

Geospatial Consortium, OGC® Best Practices, Doc. No. 07-092r3, January 15th.


[14] Wolfram MathWorld, Weblink (accessed March 2012):

http://mathworld.wolfram.com/AffineTransformation.html

[15] Murray, C. et al. (2010): Oracle ® Spatial Developer’s Guide 11g Release 2 (11.2),

E11830-06, March 2010.

http://docs.oracle.com/cd/E18283_01/appdev.112/e11830.pdf


http://mathworld.wolfram.com/AffineTransformation.html

http://docs.oracle.com/cd/E18283_01/appdev.112/e11830.pdf

3d city database for citygml · 3d city database for citygml 3d city database version 2.0.2 to...

Documents