vcdb-tool verwenden

Diese Anleitung bietet eine kurze Einführung in den Import und Export von CityGML- oder CityJSON-Daten in die VCDB mit Hilfe von vcdb-tool. Sie soll die wesentlichen Grundlagen vermitteln, während die vollständige Dokumentation von vcdb-tool hier verfügbar ist. vcdb-tool ist der Standard-Kommandozeilen-Client für die VCDB v5 und ermöglicht den Import und Export von Stadtmodelldaten sowie die Ausführung verschiedener Datenbankoperationen.

Voraussetzungen

Um dieser Kurzanleitung folgen zu können, müssen die folgenden Voraussetzungen erfüllt sein:

Eine einsatzbereite VCDB v5 Instanz (siehe VCDB Setup-Anleitung).
Ein passendes Release-Paket von vcdb-tool.
Ein Computer, der die Anforderungen für die Ausführung von vcdb-tool erfüllt.
Ein CityGML-Datensatz für den Import.

Schritt 1: Einrichtung von vcdb-tool

vcdb-tool wird als ZIP-Paket bereitgestellt und erfordert keinen spezifischen Installationsprozess. Das ZIP-Paket muss einfach nur in ein Verzeichnis Ihrer Wahl extrahiert werden. Innerhalb dieses Verzeichnis befindet sich dann das vcdb Startskript zur Ausführung der Software. Es werden zwei Versionen des Startskripts mitgeliefert:

vcdb für UNIX/Linux/macOS-Systeme; und
vcdb.bat für Windows-Systeme.

vcdb-tool ist ein Kommandozeilen-Werkzeug, das mehrere Befehle zur Interaktion mit der VCDB anbietet. Jeder Befehl kommt mit seinem eigenen Satz an Kommandozeilen-Parametern und Optionen, was die Ausführung in einer Shell-Umgebung empfiehlt. Um schnell zu überprüfen, ob die Software korrekt auf Ihrem Computer funktioniert, öffnen Sie eine Shell-Umgebung, navigieren zum Installationsverzeichnis von vcdb-tool und führen dort den nachfolgenden Befehl aus. Der Befehl gibt Versionsinformationen zu vcdb-tool auf der Konsole aus. Auf UNIX/Linux-Systemen müssen möglicherweise zunächst die entsprechenden Dateiberechtigungen gesetzt werden, um das Skript ausführbar zu machen.

Linux
Windows CMD

chmod u+x citydb
./vcdb --version

vcdb --version    # Die Dateierweiterung .bat kann weggelassen werden

vcdb --help listet alle verfügbaren Befehle von vcdb-tool auf. Beachtet werden sollte, dass einige Befehle weitere Unterbefehle haben können. Um die Hilfe für einen bestimmten (Unter-)Befehl anzuzeigen, kann einfach vcdb COMMAND [SUBCOMMAND…] --help verwendet werden.

Schritt 2: Import von CityGML-Daten

Nachdem sichergestellt wurde, dass das vcdb-tool korrekt funktioniert, kann mit dem Import von CityGML-Daten in die VCDB-Instanz fortgefahren werden. Hierfür werden die Verbindungsdetails zur Datenbank benötigt. Im Zweifel sollte der Datenbank-Administrator kontaktiert werden.

Falls kein CityGML-Datensatz für diesen Schritt verfügbar ist, kann einer der Beispiel- Datensätze verwendet werden, die von vcdb-tool im Unterordner samples/datasets bereitgestellt werden.

Linux
Windows CMD

./vcdb import citygml \
    -H the.host.de \
    -d theDBName \
    -u theUsername \
    -p theSecretPass \
    /path/to/citygml.gml

vcdb import citygml ^
    -H the.host.de ^
    -d theDBName ^
    -u theUsername ^
    -p theSecretPass ^
    C:\path\to\citygml.gml

Die in diesem einfachen Beispiel verwendeten Parameter sind:

-H: Der Hostname des Datenbankservers (z.B. localhost oder the.host.de).
-d: Der Name der VCDB-Instanz, in welche die CityGML-Daten importiert werden.
-u: Der Datenbankbenutzername mit ausreichenden Berechtigungen für den Import.
-p: Das Passwort für den angegebenen Datenbankbenutzernamen (Leer lassen, um zur Eingabe aufgefordert zu werden!).
/path/to/citygml.gml: Der Pfad zur CityGML-Datei, die importiert werden soll.

Während des Importvorgangs werden Log-Nachrichten auf der Konsole ausgegeben, die über den Fortschritt der Operation informieren. Wenn der Import erfolgreich abgeschlossen wird, wird eine Zusammenfassung der importierten Stadtobjekte angezeigt. Bei Fehlern wird der Import abgebrochen und eine Fehlermeldung mit Details zur Fehlerursache ausgegeben. Für ausführlichere Log-Meldungen und zusätzliche Details im Fehlerfall kann der Parameter --log-level debug zum Import-Befehl hinzugefügt werden.

Figure 1. Beispiel für die Konsolenausgabe einer vcdb-tool Import-Operation.

Um stattdessen einen CityJSON-Datensatz zu importieren, muss einfach der Befehl import cityjson verwendet und eine CityJSON-Datei angegeben werden.

Schritt 3: Export von CityGML-Daten

Der Export von Daten aus der VCDB als CityGML-Datei ist genauso einfach:

Linux
Windows CMD

./vcdb export citygml \
    -H the.host.de \
    -d theDBName \
    -u theUsername \
    -p theSecretPass \
    -o /path/to/target/citygml.gml

vcdb export citygml ^
    -H the.host.de ^
    -d theDBName ^
    -u theUsername ^
    -p theSecretPass ^
    -o C:\path\to\target\citygml.gml

Der Pfad und Dateiname der Ausgabedatei muss mit dem Parameter -o angegeben werden. Alle anderen Parameter in diesem Beispiel entsprechen denen der Import-Operation. Auch der Export-Prozess protokolliert den Fortschritt und eventuelle Fehlermeldungen auf der Konsole. Die Option --log-level debug kann abermals für eine detaillierte Ausgabe verwendet werden. Die gewünschte CityGML-Version kann mit dem Parameter -v angegeben werden, der die Werte 3.0, 2.0 oder 1.0 akzeptiert.

Sobald der Export erfolgreich abgeschlossen wurde, wird eine Zusammenfassung der exportierten Stadtobjekte angezeigt.

Figure 2. Beispiel für die Konsolenausgabe einer vcdb-tool Export-Operation.

Um die Daten im CityJSON-Format zu exportieren, wird einfach der Befehl export cityjson verwendet. Dies funktioniert auch wenn eine CityGML-Datei importiert wurde, da vcdb-tool zwischen beiden Formaten on-the-fly konvertieren kann.