citygml-change-detection

📣 Version 0.2.0 with support for Docker released!

🎁 INTRODUCTION

citygml-change-detection is a high-performance graph-based tool developed for automatic change detection in arbitrarily large CityGML datasets. The tool is implemented in Java and employs the graph database Neo4j as a central storage for the graph representations of CityGML datasets.

Note: The current version supports only the building module in CityGML. Support for other types of top-level features (such as bridges, tunnels, etc.) will be published in the future releases.

🐋 HOW TO RUN USING DOCKER

This tool is available as a Docker Image. The following example shows how this can be applied in most simple use cases:

1. Create a working directory, such as <WORKING_DIR>. This shall be the default project directory in the following steps.

   mkdir <WORKING_DIR>

2. Create a configuration file:

   mkdir <WORKING_DIR>/config
   touch <WORKING_DIR>/config/config.txt

   The instructions and examples of such configuration files are given here.

3. Create a directory to store input CityGML datasets:

   mkdir <WORKING_DIR>/input

   Then copy the files that need to be matched inside this directory.

4. Pull the latest docker image:

   docker pull sonnguyentum/citygml-change-detection[:Tag]

   where [:Tag] is the version of the Docker image. The list of all tags is available here.

5. Run the Docker container based on the pulled image:

   docker run --rm --name citygml-change-detection -it \
     -v <WORKING_DIR_ABS_PATH>/config:/citygml-change-detection/config \
     -v <WORKING_DIR_ABS_PATH>/input:/citygml-change-detection/input \
     -v <WORKING_DIR_ABS_PATH>/output:/citygml-change-detection/output \
     sonnguyentum/citygml-change-detection[:Tag] \
     "-SETTINGS=<WORKING_DIR>/config/config.txt"

   The argument --rm means that the Docker container is temporary and shall be automatically removed afterwards.

   Note: <WORKDING_DIR> should be an absolute path to the working directory so that it can be recognized by Docker.

   Note: If the neo4j DB instance should also be saved, add the following parameter to the command above:

   # Create a directory for the DB
   mkdir <WORKING_DIR>/neo4jDB
   
   # Run Docker container 
   ...
   -v <WORKING_DIR_ABS_PATH>/neo4jDB:/citygml-change-detection/neo4jDB \
   ...

6. The change detection results are now stored in the directories <WORKING_DIR>/output.

🌊 HOW TO BUILD AND PUBLISH IN DOCKER

The Dockerfile used to build the Docker image mentioned above is also included. To build the image, change to the project directory and execute the following command:

docker build -t citygml-change-detection .

OR include a tag to publish in DockerHub:

docker build -t <username>/<repository>[:Tag] .
docker push <username>/<repository>[:Tag]

---

💻 SYSTEM REQUIREMENTS

The application employs the graph database Neo4j as a means to store and process CityGML datasets. To be able to run the program in Java in the following sections, the system must thus meet the minimum requirements listed in Neo4j Operations Manual.

IMPORTANT: Java 8 is required!

⚡ HOW TO RUN IN JAVA

1. Download the JAR file and its dependencies in the release section.

2. Create a configuration file (instructions and examples are given here).

3. Run the downloaded JAR file in the Command Line Interface (CLI):

   java -jar citygml-change-detection.jar -SETTINGS="path/to/config.txt"

🔨 CONFIGURE JAVA VM

Some configurations for the local Java VM can also be applied while running the JAR file:

• -Xms<N>: specifies the initial amount of main memory (heap space) available
• -Xmx<N>: specifies the maximum amount of main memory (heap space) available
• -XX:+UseG1G: employs the concurrent garbage collector G1GC.

Note that to save memory, the JVM employs the Compressed Ordinary Object Pointer (OOP) feature that compresses object references. This feature is enabled by default in latest versions of JDK. The compressed OOPs is activated in 64-bit JVM if the value of flag -Xmx is undefined or smaller than 32 GB. Therefore, a maximum heap space size value of 32 GB and beyond shall deactivate the compressed OOP and thus might cause marginal or negative gains in performance, unless the increase in size is significant (64GB or above) as stated in Neo4j Operations Manual.

An example of such parameters:

java -Xms2048m -Xmx8G -XX:+UseG1GC -jar citygml-change-detection.jar -SETTINGS="path/to/config.txt"

🚀 HOW TO BUILD

1. Clone the project:

   git clone https://github.com/tum-gis/citygml-change-detection

2. Go to the downloaded folder:

   cd citygml-change-detection

3. Build the project using Gradle:

   gradle build

   OR use the following command to remove old dependencies:

   gradle build --refresh-dependencies --info

4. The main function is located in controller/CityGMLChangeDetection.java. This basically calls the constructor:

   CityGMLChangeDetection cityGMLChangeDetection = new CityGMLChangeDetection("path/to/config.txt");

   where path/to/config.txt is the path to the configuration file required. Instructions and examples are given here.

5. (Optional) This steps explains how to publish the built project to JFrog Artifactory.

   1. Enter the registered repository URL, username and password (or API key) for the JFrog Artifactory API in gradle.properties:

      artifactory_contextUrl=https://example.jfrog.io/artifactory
      artifactory_user=john.doe@example.com
      artifactory_password=password_or_api_key
      

   2. Run the following command to publish to JFrog Artifactory:

      gradle artifactoryPublish

---

💡 HOW TO READ RESULTS

The tool stores the change detection results by default in the directory output. Please refer to the descriptions inside the directory and each of its sub-directories for more details.

🔎 REPOSITORY STRUCTURE

This repository contains the following directories:

Directory	Description
input	Location of input CityGML datasets.
output	Location of output files and directories generated while executing the change detection process, this includes detected changes in CSV files, log files, RTree footprints of imported top-level features and statistics report.
config	Location of example settings that can be applied for the change detection process, especially the default settings.
src	Location of the source codes.

---

📚 PUBLICATIONS

This project is a part of the on-going PhD research of Son H. Nguyen at the Chair of Geoinformatics, Department of Aerospace and Geodesy, Technical University of Munich. For more information on the research, please refer to the following published studies:

• Son H. Nguyen, Thomas H. Kolbe. "A MULTI-PERSPECTIVE APPROACH TO INTERPRETING SPATIO-SEMANTIC CHANGES OF LARGE 3D CITY MODELS IN CITYGML USING A GRAPH DATABASE", ISPRS Ann. Photogramm. Remote Sens. Spatial Inf. Sci., VI-4/W1-2020, 143–150, https://doi.org/10.5194/isprs-annals-VI-4-W1-2020-143-2020, 2020.

• Son H. Nguyen, Zhihang Yao, Thomas H. Kolbe. "SPATIO-SEMANTIC COMPARISON OF LARGE 3D CITY MODELS IN CITYGML USING A GRAPH DATABASE". gis.Science (3/2018), 2018, 85-100.

• Son H. Nguyen, Zhihang Yao, Thomas H. Kolbe. "SPATIO-SEMANTIC COMPARISON OF LARGE 3D CITY MODELS IN CITYGML USING A GRAPH DATABASE", ISPRS Ann. Photogramm. Remote Sens. Spatial Inf. Sci., IV-4/W5, 99-106, https://doi.org/10.5194/isprs-annals-IV-4-W5-99-2017, 2017.

• Son H. Nguyen. "SPATIO-SEMANTIC COMPARISON OF 3D CITY MODELS IN CITYGML USING A GRAPH DATABASE". Master's Thesis. Department of Informatics, Technical University of Munich (TUM).

We acknowledge the company CADFEM, Virtual City Systems and the Leonhard Obermeyer Center (LOC) of the Technical University of Munich (TUM) for supporting this work. We also would like to thank the Bavarian Agency for Digitisation, High-Speed Internet and Surveying (LDBV) and the state government of North Rhine-Westphalia for providing the input datasets.

🍪 BACKGROUND

A city may have multiple CityGML documents recorded at different times or surveyed by different users. To analyse the city’s evolution over a given period of time, as well as to update or edit the city model without negating modifications made by other users, it is of utmost importance to first compare, detect and locate spatio-semantic changes between CityGML datasets. This is however difficult due to the fact that CityGML elements belong to a complex hierarchical structure containing multi-level deep associations, which can basically be considered as a graph. Moreover, CityGML allows multiple syntactic ways to define an object leading to syntactic ambiguities in the exchange format. Furthermore, CityGML is capable of including not only 3D urban objects’ graphical appearances but also their semantic properties. Since to date, no known algorithm is capable of detecting spatio-semantic changes in CityGML documents, a frequent approach is to replace the older models completely with the newer ones, which not only costs computational resources, but also loses track of collaborative and chronological changes. Thus, this research proposes an approach capable of comparing two arbitrarily large-sized CityGML documents on both semantic and geometric level. Detected deviations are then attached to their respective sources and can easily be retrieved on demand. As a result, updating a 3D city model using this approach is much more efficient as only real changes are committed. To achieve this, the research employs a graph database as the main data structure for storing and processing CityGML datasets in three major steps: mapping, matching and updating. The mapping process transforms input CityGML documents into respective graph representations. The matching process compares these graphs and attaches edit operations on the fly. Found changes can then be executed using the Web Feature Service (WFS), the standard interface for updating geographical features across the web.

The (ongoing) implementation of this research is stored and maintained in this repository.

📂 License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for more details.