Import-Befehl

Der import Befehl importiert Stadtmodelldaten in einem unterstützten Format in die VCDB v5. Für jedes Format gibt es einen eigenen Unterbefehl mit formatspezifischen Optionen.

Synopsis

vcdb import [OPTIONS] COMMAND

Optionen

Der import Befehl erbt globale Optionen vom Hauptbefehl vcdb. Zusätzlich definiert er allgemeine Import-, Metadaten- und Filteroptionen, die auch für alle Unterbefehle gelten.

Globale Optionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`[@<filename>…]`	Eine oder mehrere Argumentdateien mit Optionen.
`-h`, `--help`	Hilfenachricht anzeigen und beenden.
`-V`, `--version`	Versionsinformationen ausgeben und beenden.
`--config-file=<file>`	Konfiguration aus dieser Datei laden.
`-L`, `--log-level=<level>`	Log-Level: `fatal`, `error`, `warn`, `info`, `debug`, `trace`.	`info`
`--log-file=<file>`	Log-Nachrichten in diese Datei schreiben.
`--quiet`	Deaktiviert Log-Nachrichten auf der Konsole.
`--pid-file=<file>`	Datei mit der Prozess-ID erstellen.
`--plugins=<dir>`	Plugins aus diesem Verzeichnis laden.
`--use-plugin=<plugin[=true\|false]> [,<plugin[=true\|false]>…]`	Plugins mit passendem vollqualifiziertem Klassennamen aktivieren oder deaktivieren.	`true`

[@<filename>…]

Eine oder mehrere Argumentdateien mit Optionen.

-h, --help

Hilfenachricht anzeigen und beenden.

-V, --version

Versionsinformationen ausgeben und beenden.

--config-file=<file>

Konfiguration aus dieser Datei laden.

-L, --log-level=<level>

Log-Level: fatal, error, warn, info, debug, trace.

info

--log-file=<file>

Log-Nachrichten in diese Datei schreiben.

--quiet

Deaktiviert Log-Nachrichten auf der Konsole.

--pid-file=<file>

Datei mit der Prozess-ID erstellen.

--plugins=<dir>

Plugins aus diesem Verzeichnis laden.

--use-plugin=<plugin[=true|false]> [,<plugin[=true|false]>…]

Plugins mit passendem vollqualifiziertem Klassennamen aktivieren oder deaktivieren.

true

Weitere Informationen zu den globalen Optionen und Nutzungshinweise siehe hier.

Allgemeine Importoptionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`<file>…`	Eine oder mehrere Dateien oder Verzeichnisse zur Verarbeitung (Glob-Patterns erlaubt).
`--input-encoding=<encoding>`	Kodierung der Eingabedatei(en).
`--fail-fast`	Bei Fehlern sofort beenden.
`--temp-dir=<dir>`	Temporäre Dateien in diesem Verzeichnis speichern.
`-m`, `--import-mode=<mode>`	Importmodus: `import_all`, `skip`, `delete`, `terminate`.	`import_all`
`--threads=<threads>`	Anzahl der Threads für die parallele Verarbeitung.
`--preview`	Im Vorschau-Modus ausführen. Features werden nicht importiert.
`--index-mode=<mode>`	Indexmodus: `keep`, `drop`, `drop_create`. Bei der Verarbeitung großer Datenmengen kann das Deaktivieren der Indizes sinnvoll sein.	`keep`
`--compute-extent`	Envelopes von Features berechnen und ersetzen.
`--transform= <m0,m1,…,m11\|swap-xy>`	Koordinaten mit einer 3x4-Matrix im Row-Major-Format transformieren. `swap-xy` kann als Abkürzung verwendet werden.

<file>…

Eine oder mehrere Dateien oder Verzeichnisse zur Verarbeitung (Glob-Patterns erlaubt).

--input-encoding=<encoding>

Kodierung der Eingabedatei(en).

--fail-fast

Bei Fehlern sofort beenden.

--temp-dir=<dir>

Temporäre Dateien in diesem Verzeichnis speichern.

-m, --import-mode=<mode>

Importmodus: import_all, skip, delete, terminate.

import_all

--threads=<threads>

Anzahl der Threads für die parallele Verarbeitung.

--preview

Im Vorschau-Modus ausführen. Features werden nicht importiert.

--index-mode=<mode>

Indexmodus: keep, drop, drop_create. Bei der Verarbeitung großer Datenmengen kann das Deaktivieren der Indizes sinnvoll sein.

keep

--compute-extent

Envelopes von Features berechnen und ersetzen.

--transform= <m0,m1,…,m11|swap-xy>

Koordinaten mit einer 3x4-Matrix im Row-Major-Format transformieren. swap-xy kann als Abkürzung verwendet werden.

Metadatenoptionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`--lineage=<lineage>`	Datenabstammung oder Ursprung der Features.
`--updating-person=<name>`	Name des Benutzers, der für den Import verantwortlich ist.	Datenbankbenutzer
`--reason-for-update=<reason>`	Grund für den Import der Daten.

--lineage=<lineage>

Datenabstammung oder Ursprung der Features.

--updating-person=<name>

Name des Benutzers, der für den Import verantwortlich ist.

Datenbankbenutzer

--reason-for-update=<reason>

Grund für den Import der Daten.

Filteroptionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`-t`, `--type-name=<[prefix:]name> [,<[prefix:]name>…]`	Namen der zu verarbeitenden Features.
`-i`, `--id=<id>[,<id>…]`	Identifier der zu verarbeitenden Features.
`-b`, `--bbox=<x_min,y_min,x_max,y_max[,srid]>`	Bounding Box als räumlicher Filter.
`--bbox-mode=<mode>`	Bounding Box Modus: `intersects`, `contains`, `on_tile`.	`intersects`
`--limit=<count>`	Maximale Anzahl der zu verarbeitenden Features.
`--start-index=<index>`	Index innerhalb der Eingabemenge, ab dem Features verarbeitet werden.

-t, --type-name=<[prefix:]name> [,<[prefix:]name>…]

Namen der zu verarbeitenden Features.

-i, --id=<id>[,<id>…]

Identifier der zu verarbeitenden Features.

-b, --bbox=<x_min,y_min,x_max,y_max[,srid]>

Bounding Box als räumlicher Filter.

--bbox-mode=<mode>

Bounding Box Modus: intersects, contains, on_tile.

intersects

--limit=<count>

Maximale Anzahl der zu verarbeitenden Features.

--start-index=<index>

Index innerhalb der Eingabemenge, ab dem Features verarbeitet werden.

Befehle

Befehl Beschreibung

Befehl	Beschreibung
`help`	Hilfe zum angegebenen Befehl anzeigen.
`citygml`	Daten im CityGML-Format importieren.
`cityjson`	Daten im CityJSON-Format importieren.

help

Hilfe zum angegebenen Befehl anzeigen.

citygml

Daten im CityGML-Format importieren.

cityjson

Daten im CityJSON-Format importieren.

Zusätzliche Befehle zur Unterstützung weiterer Formate können in zukünftigen Versionen hinzukommen. Es kann auch ein eigenes Plugin umgesetzt werden, um ein bestimmtes Format zu unterstützen.

Verwendung

Import-Dateien angeben

Der Input für den Import wird über ein oder mehrere <file> Argumente angegeben, von denen jedes auf eine Datei oder ein Verzeichnis verweisen kann. Es können auch Glob-Pattern mit Platzhaltern wie *, ?, [ ] oder { } verwendet werden, um mehrere Dateien auszuwählen.

Wird ein Verzeichnis angegeben, wird es rekursiv nach unterstützten Eingabedateien durchsucht. Die unterstützten Formate und Dateiendungen hängen vom Unterbefehl ab. Neben regulären Dateien werden auch ZIP-Archive und GZIP-komprimierte Dateien als Eingabe unterstützt. Wie Verzeichnisse werden auch ZIP-Archive rekursiv nach unterstützten Eingabedateien durchsucht. Das folgende Beispiel zeigt verschiedene Möglichkeiten zur Angabe von Eingabedateien.

Linux
Windows CMD

./vcdb import citygml [...] \
    /path/to/my-city.gml \
    /foo/ \
    /bar/**/city*.{gml,gz,zip}

vcdb import citygml [...] ^
    C:\path\to\my-city.gml ^
    C:\foo\ ^
    C:\bar\**\city*.{gml,gz,zip}

Um eine bestimmte Zeichenkodierung für die Eingabedateien festzulegen, muss der IANA-basierte Kodierungsname (z.B. UTF-8) mit der --input-encoding Option angegeben werden. Diese Kodierung wird auf alle Eingabedateien angewendet.

Importmodi und doppelte Objekte

Der Importmodus, der über die Option --import-mode festgelegt wird, bestimmt, wie mit doppelten Stadtobjekten in der Datenbank umgegangen wird. Die verfügbaren Modi sind:

import_all: Alle Features aus den Eingabedateien werden importiert, auch wenn dadurch Duplikate in der Datenbank entstehen. Dies ist der Standardmodus.
skip: Bereits in der Datenbank vorhandene Features haben Vorrang. Wird ein Duplikat gefunden, wird das Feature aus der Eingabedatei ignoriert und nicht importiert.
delete: Features aus den Eingabedateien haben Vorrang. Wird ein Duplikat gefunden, wird das vorhandene Feature in der Datenbank gelöscht, bevor das neue Feature importiert wird.
terminate: Ähnlich wie bei delete, jedoch wird das doppelte Feature in der Datenbank terminiert anstatt gelöscht (zum Unterschied siehe den delete Befehl).

Duplikate werden erkannt, indem die Spalte objectid in der FEATURE Tabelle mit dem Identifier des Features aus der Eingabedatei verglichen wird (z.B. gml:id bei CityGML-Dateien). Es werden keine zusätzlichen Prüfungen zur Erkennung von Duplikaten durchgeführt.
Bereits terminierte Features werden bei der Duplikatsprüfung nicht berücksichtigt.

Importvorschau

Die Option --preview führt den Import im Vorschau-Modus aus. Die Eingabedaten werden dabei so verarbeitet, als ob der Import tatsächlich stattfinden würde, jedoch werden keine Änderungen an der Datenbank vorgenommen. Dieser Modus hilft dabei, potenzielle Probleme wie Konflikte oder Fehler im Vorfeld zu erkennen, bevor sie Auswirkungen auf die Datenbank haben. So lässt sich sicherstellen, dass der eigentliche Import wie erwartet durchgeführt werden kann.

Filterung von Features

Der import Befehl bietet verschiedene Filteroptionen, mit denen kontrolliert werden kann, welche Features aus den Eingabedateien importiert werden.

Feature-Typ Filter

Über die Option --type-name können eine oder mehrere Feature-Typen angegeben werden, die importiert werden sollen. Für jeden Feature-Typ ist der Typname wie in der Tabelle OBJECTCLASS der VCDB v5 anzugeben. Um Mehrdeutigkeit zu vermeiden, kann der Namespace-Alias aus der NAMESPACE Tabelle als Präfix im Format prefix:name hinzugefügt werden. Es werden nur Features importiert, die einem der angegebenen Typen entsprechen.

Feature-Identifier Filter

Die --id Option ermöglicht das Filtern nach einem oder mehreren Identifiern, die als kommaseparierte Liste angegeben werden. Nur Features mit einem entsprechenden Identifier werden importiert.

Bounding-Box Filter

Mit der Option --bbox kann eine 2D Bounding-Box als räumlicher Filter angegeben werden – bestehend aus vier Koordinaten für den linken unteren und rechten oberen Eckpunkt. Standardmäßig wird angenommen, dass die Koordinaten im gleichen CRS vorliegen, das auch für die VCDB-Instanz verwendet wird. Optional kann die SRID des CRS als fünfter Wert angegeben werden (z.B. 4326 für WGS84). Alle Werte müssen durch Kommas getrennt werden.

Das Verhalten dieses Filters wird durch die --bbox-mode gesteuert:

intersects: Es werden nur Features importiert, deren Bounding-Box sich mit dem angegebenen Bereich überschneidet. Dies ist der Standardmodus.
contains: Es werden nur Features importiert, deren Bounding-Box vollständig innerhalb des angegebenen Bereichs liegt.
on_tile: Es werden nur Features importiert, deren Bounding-Box-Mittelpunkt innerhalb des angegebenen Bereichs oder auf dessen linken bzw. unteren Rand liegt. Dieser Modus stellt sicher, dass bei mehreren Filterbereichen, die in einem Kachelraster organisiert sind, jedes Feature genau einer Kachel zugeordnet wird.

Count-Filter

Mit --limit wird die maximale Anzahl der zu importierenden Features festgelegt. Die --start-index Option definiert den 0-basierten Index des ersten Features, bei welchem der Import beginnen soll. Beide Optionen gelten global für alle Eingabedateien und können getrennt oder zusammen verwendet werden, um die Gesamtanzahl der zu importierenden Features zu definieren.

Filter-Beispiel

Das folgende Beispiel zeigt einen CityGML Import-Befehl mit mehreren Filterkriterien:

Linux
Windows CMD

./vcdb import citygml [...] my-city.gml \
    --type-name=bldg:Building,tran:Road \
    --bbox=367123,5807268,367817,5807913,25833 \
    --bbox-mode=on_tile \
    --limit=100

vcdb import citygml [...] my-city.gml ^
    --type-name=bldg:Building,tran:Road ^
    --bbox=367123,5807268,367817,5807913,25833 ^
    --bbox-mode=on_tile ^
    --limit=100

Wenn mehrere Filter verwendet werden, müssen alle Bedingungen erfüllt sein, damit ein Feature importiert wird.
Komplexe Filerausdrücke können sehr komfortable in Konfigurationsdateien oder Argumentdateien ausgelagert und einfach wiederverwendet werden.

Verwaltung von Indizes während des Imports

Während des Imports von Daten werden Datenbankindizes in Echtzeit aktualisiert, was den Importprozess verlangsamen kann, insbesondere bei großen Datenmengen. Die Option --index-mode bietet die folgenden Modi zur Steuerung des Indexverhaltens:

keep: Die Indizes bleiben unverändert. Dies ist der Standardmodus.
drop: Die Indizes werden vor dem Import deaktiviert, was die Import-Performance verbessert.
drop_create: Wie drop, aber die Indizes werden nach dem Import automatisch wieder aktiviert. Die stellt sicher, dass sie für nachfolgende Abfragen verfügbar sind.

Das Deaktivieren und Wiederherstellen von Indizes kann je nach Datenbankgröße ebenfalls viel Zeit in Anspruch nehmen. Der drop_create Modus ist daher besonders beim Import großer Datensätze sinnvoll, z.B. beim initialen Befüllen der Datenbank. Wenn die Datenbank jedoch bereits sehr groß ist und viele Daten enthält, kann der Zeitaufwand für das Deaktivieren und Neuerstellen der Indizies höher sein als für den Import bei aktivierten Indizes – insbesondere wenn nur kleinere Datensätze importiert werden.

Mit dem index Befehl können Indizes auch unabhängig von einem Importvorgang verwaltet werden, was eine gezieltere Kontrolle ermöglicht.

Berechnung von Envelopes

Standardmäßig liest vcdb-tool die Bounding Boxes der Features aus der Eingabedatei und speichert sie in der envelope Spalte der FEATURE Tabelle. Ein korrekter Envelope ist unerlässlich für räumliche Abfragen. Mit der Option --compute-extent berechnet vcdb-tool die Envelopes stattdessen selbst. Dabei werden die Geometrien des Features und seiner Subfeatures über alle LoDs hinweg berücksichtigt.

Envelopes können auch nach dem Import mit Datenbankfunktionen der VCDB v5 neu berechnet werden, wie hier erläutert.

Transformation von Geometrien

Die --transform Option wendet eine affine Transformation auf die Eingabegeometrien an, bevor sie in die Datenbank importiert werden. Dabei wird eine 3x4-Transformationsmatrix verwendet, die mit homogenen Koordinaten arbeitet, um die transformierten Koordinaten zu berechnen:

Die Option --transform erwartet eine kommaseparierte Liste der 12 Matrix-Koeffizienten im Row-Major-Format, also von bis :

--transform=m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11

Ein häufiges Anwendungsbeispiel ist das Vertauschen der - und -Koordinaten, während die -Koordinaten unverändert beibehalten werden. Für diese Transformation kann auch swap_xy als Kurzschreibweise verwendet werden, wie im folgenden Beispiel gezeigt.

Linux
Windows CMD

./vcdb import citygml [...] my-city.gml \
    --transform=swap_xy

vcdb import citygml [...] my-city.gml ^
    --transform=swap_xy

Es muss sichergestellt werden, dass die transformierten Koordinaten weiterhin zum CRS der VCDB-Instanz passen.

Definition von Import-Metadaten

Die Optionen --lineage, --updating-person und --reason-for-update erfassen Metadaten über den Ursprung des Features, die verantwortliche Person für den Import und den Grund des Imports. Diese Metadaten sind spezifisch für die VCDB und sind nicht Teil des CityGML-Standards (siehe auch hier). Wenn --updating-person nicht angegeben wird, wird standardmäßig der Benutzername verwendet, mit dem die Verbindung zur VCDB-Datenbank hergestellt wurde.

Steuerung des Importprozesses

Der import Befehl bietet folgende Optionen zur Steuerung des Importprozesses:

--fail-fast: Beendet den Prozess sofort beim Auftreten eines Fehlers. Standardmäßig wird der Import trotz Fehlern beim Import einzelner Features fortgesetzt.
--temp-dir: Legt das Verzeichnis für temporäre Dateien während des Imports fest. Für optimale Performance sollte ein schnelles Speichermedium gewählt werden, das nicht zum Lesen der Eingabedateien verwendet wird.
--threads: Setzt die Anzahl der Threads für die parallele Prozessierung fest. Eine höhere Anzahl von Threads kann zu einer Performance-Steigerung führen. Standardmäßig entspricht die Anzahl der Threads der Anzahl der für die JVM verfügbaren Prozessoren, mindestens jedoch zwei.

Eine zu hohe Anzahl an Threads kann zu Leistungseinbußen durch Thrashing führen. Außerdem benötigt jeder Thread eine eigene Datenbankverbindung, weshalb sichergestellt werden muss, dass die Datenbank die erforderliche Anzahl von Verbindungen zur Verfügung stellen kann.