Export-Befehl

Der export Befehl exportiert Stadtmodelldaten aus der VCDB v5 in ein unterstütztes Format. Für jedes Format gibt es einen eigenen Unterbefehl mit formatspezifischen Optionen.

Synopsis

vcdb export [OPTIONS] COMMAND

Optionen

Der export Befehl erbt globale Optionen vom Hauptbefehl vcdb. Zusätzlich definiert er allgemeine Export-, Abfrage-, Filter- und Kachelungsoptionen, die für alle seine 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 Exportoptionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`-o`, `--output=<file>`	Name der Ausgabedatei.
`--output-encoding=<encoding>`	Kodierung, die für die Ausgabedatei verwendet wird.
`--fail-fast`	Bei Fehlern sofort beenden.
`--temp-dir=<dir>`	Temporäre Dateien in diesem Verzeichnis speichern.
`--threads=<threads>`	Anzahl der Threads für die parallele Verarbeitung.
`--crs=<crs>`	SRID oder Identifier des CRS, das für die Koordinaten von Geometrien verwendet wird.	VCDB CRS
`--crs-name=<name>`	Name des CRS, der in der Ausgabedatei verwendet werden soll.
`--transform= <m0,m1,…,m11\|swap-xy>`	Koordinaten mit einer 3x4-Matrix im Row-Major-Format transformieren. `swap-xy` kann als Abkürzung verwendet werden.

-o, --output=<file>

Name der Ausgabedatei.

--output-encoding=<encoding>

Kodierung, die für die Ausgabedatei verwendet wird.

--fail-fast

Bei Fehlern sofort beenden.

--temp-dir=<dir>

Temporäre Dateien in diesem Verzeichnis speichern.

--threads=<threads>

Anzahl der Threads für die parallele Verarbeitung.

--crs=<crs>

SRID oder Identifier des CRS, das für die Koordinaten von Geometrien verwendet wird.

VCDB CRS

--crs-name=<name>

Name des CRS, der in der Ausgabedatei verwendet werden soll.

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

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

Abfrage- und Filteroptionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`-t`, `--type-name=<[prefix:]name> [,<[prefix:]name>…]`	Namen der zu verarbeitenden Features.
`-f`, `--filter=<cql2-text>`	Filter zum Abrufen von Features. Verwenden Sie die erweiterte CQL2-Filtersprache der VCDB.
`--filter-crs=<crs>`	SRID oder Identifier des CRS, das für Geometrien im Filterausdruck verwendet wird.	VCDB CRS
`--sql-filter=<sql>`	SQL-Query, die als Filter verwendet wird.
`-s`, `--sort-by=<property[+\|-]> [,<property[+\|-]>…]`	Eigenschaften und Sortierreihenfolgen zur Sortierung der Features.
`--limit=<count>`	Maximale Anzahl der zu verarbeitenden Features.
`--start-index=<index>`	Index innerhalb der Eingabemenge, ab dem Features verarbeitet werden.
`-l`, `--lod=<lod>[,<lod>…]`	Exportiere Geometrien mit passendem LoD.
`--lod-mode=<mode>`	LoD-Filtermodus: `or`, `and`, `minimum`, `maximum`.	`or`
`--lod-search-depth=<0..n\|all>`	Anzahl der Ebenen von Subfeatures, die nach passenden LoDs durchsucht werden.	0
`--no-appearances`	Appearances nicht verarbeiten.
`-a`, `--appearance-theme=<theme>[,<theme>…]`	Appearances mit passendem Theme verarbeiten. Verwenden Sie `none` für das Null-Theme.

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

Namen der zu verarbeitenden Features.

-f, --filter=<cql2-text>

Filter zum Abrufen von Features. Verwenden Sie die erweiterte CQL2-Filtersprache der VCDB.

--filter-crs=<crs>

SRID oder Identifier des CRS, das für Geometrien im Filterausdruck verwendet wird.

VCDB CRS

--sql-filter=<sql>

SQL-Query, die als Filter verwendet wird.

-s, --sort-by=<property[+|-]> [,<property[+|-]>…]

Eigenschaften und Sortierreihenfolgen zur Sortierung der Features.

--limit=<count>

Maximale Anzahl der zu verarbeitenden Features.

--start-index=<index>

Index innerhalb der Eingabemenge, ab dem Features verarbeitet werden.

-l, --lod=<lod>[,<lod>…]

Exportiere Geometrien mit passendem LoD.

--lod-mode=<mode>

LoD-Filtermodus: or, and, minimum, maximum.

or

--lod-search-depth=<0..n|all>

Anzahl der Ebenen von Subfeatures, die nach passenden LoDs durchsucht werden.

--no-appearances

Appearances nicht verarbeiten.

-a, --appearance-theme=<theme>[,<theme>…]

Appearances mit passendem Theme verarbeiten. Verwenden Sie none für das Null-Theme.

Zeitbasierte Objekt-Historie-Optionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`-M`, `--validity=<mode>`	Verarbeitung von Feature basierend auf ihrer Gültigkeit: `valid`, `invalid`, `all`.	`valid`
`-T`, `--validity-at=<time>`	Gültigkeit zu einem bestimmten Zeitpunkt prüfen. Das Zeitformat muss `<YYYY-MM-DD>` oder `<YYYY-MM-DDThh:mm:ss[(+\|-)hh:mm]>` sein.
`--validity-reference=<source>`	Referenz für die Gültigkeitszeit: `database`, `real_world`	`database`
`--lenient-validity`	Unvollständige Gültigkeitsintervalle von Features ignorieren.

-M, --validity=<mode>

Verarbeitung von Feature basierend auf ihrer Gültigkeit: valid, invalid, all.

valid

-T, --validity-at=<time>

Gültigkeit zu einem bestimmten Zeitpunkt prüfen. Das Zeitformat muss <YYYY-MM-DD> oder <YYYY-MM-DDThh:mm:ss[(+|-)hh:mm]> sein.

--validity-reference=<source>

Referenz für die Gültigkeitszeit: database, real_world

database

--lenient-validity

Unvollständige Gültigkeitsintervalle von Features ignorieren.

Kachelungsoptionen

Option Beschreibung Standardwert

Option	Beschreibung	Standardwert
`--tile-matrix=<columns,rows>`	Exportiere Kacheln in einem Spalten x Zeilen Raster.
`--tile-dimension=<width[unit],height[unit]>`	Exportiere Kacheln mit angegebener Breite und Höhe, ausgerichtet am Raster des Datenbank-CRS (die Längeneinheit des CRS wird als Standard angenommen).
`--tile-extent=<x_min,y_min,x_max,y_max[,srid]>`	Ausdehnung, die für die Kachelung verwendet wird.	automatisch berechnet
`--tile-origin=<origin>`	Ursprung der Kachel-Indizes: `top_left`, `bottom_left`.	`top_left`

--tile-matrix=<columns,rows>

Exportiere Kacheln in einem Spalten x Zeilen Raster.

--tile-dimension=<width[unit],height[unit]>

Exportiere Kacheln mit angegebener Breite und Höhe, ausgerichtet am Raster des Datenbank-CRS (die Längeneinheit des CRS wird als Standard angenommen).

--tile-extent=<x_min,y_min,x_max,y_max[,srid]>

Ausdehnung, die für die Kachelung verwendet wird.

automatisch berechnet

--tile-origin=<origin>

Ursprung der Kachel-Indizes: top_left, bottom_left.

top_left

Befehle

Befehl Beschreibung

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

help

Hilfe zum angegebenen Befehl anzeigen.

citygml

Daten im CityGML-Format exportieren.

cityjson

Daten im CityJSON-Format exportieren.

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

Ausgabedatei angeben

Die Ausgabedatei für den Export wird mit der Option --output angegeben. Die Dateierweiterung sollte dabei dem Zielformat entsprechen. Der Export-Befehl unterstützt auch GZIP-Komprimierung und ZIP-Archivierung. Um diese zu nutzen, verwenden Sie die entsprechenden unten augeführten Dateierweiterungen:

Dateityp Dateierweiterungen

Dateityp	Dateierweiterungen
Reguläre Datei	abhängig vom Zielformat
GZIP-komprimierte Datei	`.gz`, `.gzip`
ZIP-Archiv	`.zip`

Reguläre Datei

abhängig vom Zielformat

GZIP-komprimierte Datei

.gz, .gzip

ZIP-Archiv

.zip

Mit der Option --output-encoding kann eine bestimmte Zeichenkodierung für die Ausgabedatei festgelegt werden. Hierzu muss der IANA-konforme Kodierungsname angegeben werden (z.B. UTF-8).

Wenn der Export Texturdateien umfasst, wird ein Unterordner namens appearance relativ zur Ausgabedatei erstellt, in dem alle Texturen gespeichert werden. Ebenso wird ein Unterordner namens library-objects erstellt, um Bibliotheksobjekte zu speichern, die von impliziten Geometrien verwendet werden. Beim Export als ZIP-Archiv werden diese Ordner ins Archiv aufgenommen.

Abfragen und Filter

Mit vcdb-tool können alle in einer VCDB v5 Instanz gespeicherten Features in eine einzelne Datei exportiert werden. In der Praxis wird jedoch häufig nur eine bestimmte Teilmenge von Features benötigt. Der export Befehl stellt hierfür verschiedene Abfrage- und Filteroptionen bereit, um die Untermenge der benötigten Features festzulegen.

Feature-Typ Filter

Über die Option --type-name können eine oder mehrere Feature-Typen angegeben werden, die exportiert 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 exportiert, die einem der angegebenen Typen entsprechen.

CQL2-basierte Filterung

vcdb-tool unterstützt die OGC Common Query Language (CQL2) als Standard-Abfragesprache für die Filterung von Features aus der VCDB v5. CQL2 erlaubt sowohl attributbasierte als auch räumliche Filter und bietet eine umfangreichen Satz an Vergleichsoperatoren, räumlichen Funktionen und logischen Operatoren. Nur Features, die die angegebenen Filterkriterien erfüllen, werden exportiert.

CQL2-Filterausdrücke werden dem export Befehl über die Option --filter übergeben. Gegebenenfalls müssen sie in Anführungszeichen notiert werden. Bei räumlichen Filtern wird davon ausgegangen, dass die Filtergeometrien im gleichen Koordinatenreferenzsystem (CRS) vorliegen, das auch für die VCDB-Instanz definiert sind. Um ein anderes CRS anzugeben, kann die Option --filter-crs mit der entsprechenden SRID (z.B. 4326 für WGS84) verwendet werden.

Weitere Information zur Verwendung von CQL2 mit der VCDB v5 finden Sie in der CQL2-Dokumentation.

Das folgende Beispiel zeigt den Export von Gebäuden basierend auf ihrem height Attribut.

Linux
Windows CMD

./vcdb export citygml [...] -o my-city.gml \
    --type-name=bldg:Building \
    --filter="con:height > 15"

vcdb export citygml [...] -o my-city.gml ^
    --type-name=bldg:Building ^
    --filter="con:height > 15"

Um die envelope Eigenschaft von Features gegen einen Bounding-Box-Filter zu prüfen, kann der folgende CQL2-Filterausdruck verwendet werden.

Linux
Windows CMD

./vcdb export citygml [...] -o my-city.gml \
    --filter="s_intersects(core:envelope, bbox(13.369,52.506,13.405,52.520))" \
    --filter-crs=4326

vcdb export citygml [...] -o my-city.gml ^
    --filter="s_intersects(core:envelope, bbox(13.369,52.506,13.405,52.520))" ^
    --filter-crs=4326

SQL-basierte Filterung

Mit der Option --sql-filter können SQL SELECT Anweisungen als Filterausdrücke verwendet werden, mit denen alle Details des relationalen Schemas abgefragt werden können. Jede SELECT Statement, das vom zugrunde liegenden Datenbanksystem unterstützt wird, ist als Eingabe erlaubt, sofern es als Ergebnis eine Liste von id Werten aus der FEATURE Tabelle zurückliefert. Nur Features, die in der zurückgegebenen Liste enthalten sind, werden exportiert.

Das nachfolgende Beispiel zeigt die Filterung von Features anhand ihres Identifiers in der Spalte objectid der FEATURE Tabelle. Die SELECT Anweisung muss in Anführungszeichen gesetzt und Sonderzeichen gegebenenfalls maskiert werden.

Linux
Windows CMD

./vcdb export citygml [...] -o my-city.gml \
    --sql-filter="SELECT id FROM feature WHERE objectid IN ('ABC', 'DEF')"

vcdb export citygml [...] -o my-city.gml ^
    --sql-filter="SELECT id FROM feature WHERE objectid IN ('ABC', 'DEF')"

Count-Filter

Mit --limit wird die maximale Anzahl der zu exportierenden Features festgelegt. Die --start-index Option definiert den 0-basierten Index des ersten Features in der Ergebnismenge, mit welchem der Export beginnen soll. Beide Optionen können getrennt oder zusammen verwendet werden, um die Gesamtanzahl der zu exportierenden Features zu definieren.

LoD-Filter

Der export Befehl ermöglicht mit der --lod Option das Filtern von Geometrien nach ihrem Level-of-Detail (LoD). Eine oder mehrere LoD Stufen können als kommageseparierte Liste angegeben werden. Typische Werte reichen von [0..3] oder [0..4], je nach der CityGML-Version in der Datenbank. Es sind jedoch auch beliebige andere String-Werte erlaubt.

Wird nur eine LoD Stufe angegeben, werden nur Geometrien mit diesem LoD für den Export berücksichtigt. Features ohne entsprechende LoD Stufe werden nicht exportiert.
Bei Angabe mehrerer LoDs werden nur Geometrien in einem entsprechenden LoD berücksichtigt. Das weitere Filterverhalten wird dann durch die Option --lod-mode gesteuert:
- or: Features mit mindestens einer passenden LoD Stufe werden exportiert. Dies ist der Standardmodus.
- and: Nur Features, die in allen angefragten LoDs repräsentiert sind, werden exportiert.
- minimum: Wie or, aber nur die niedrigste LoD Stufe des Features wird exportiert.
- maximum: Wie or, aber nur die höchste LoD Stufe des Features wird exportiert.

Mit --lod-search-depth wird festgelegt, wie viele Ebenen von verschachtelten Subfeatures nach einer passenden LoD Repräsentation durchsucht werden. Mit dem Standardwert 0 werden nur das Feature selbst und seine direkten Begrenzungsflächen berücksichtigt. Der LoD-Filter ist erfüllt, wenn mindestens ein Subfeature eine passende LoD Stufe besitzt.

Der nachfolgende Befehl exportiert Features, die entweder eine LoD2 oder LoD3 Repräsentation besitzen, wobei nur die höhere LoD Stufe in die Ausgabedatei geschrieben wird.

Linux
Windows CMD

./vcdb export citygml [...] -o my-city.gml \
    --lod=2,3 \
    --lod-mode=maximum

vcdb export citygml [...] -o my-city.gml ^
    --lod=2,3 ^
    --lod-mode=maximum

Appearance-Filter

Die --appearance-theme Option filtert Appearances nach ihrem <theme>. Ein oder mehrere Themes können als kommaseparierte Liste angegeben werden. Um Appearances zu filtern, die kein Theme Attribute besitzen, muss none als Wert verwendet werden. Es werden nur Appearances exportiert, deren Theme mit einem der Werte übereinstimmt. Um keine Appearances zu exportieren, verwenden Sie die Option --no-appearances.

Sortierung von Features nach Attributen

Zusätzlich zu den beschriebenen Filtermöglichketen erlauben die Abfrageoptionen des export Befehls auch die Sortierung von Features nach einem oder mehreren ihrer Eigenschaften, die über die --sort-by Option spezifiziert werden. Die Sortierung nach Attributen von Subfeatures wird dabei ebenfalls unterstützt. Die Attribute müssen hierzu über dieselbe JSON-Pfad Notation referenziert werden, die auch für CQL2-Ausdrücke verwendet wird (siehe hier). Ein + oder - Zeichen hinter dem Attributnamen definiert die Sortierreihenfolge: + für aufsteigend (Standard) und - für absteigend.

Das folgende Beispiel exportiert Gebäude und sortiert sie zuerst nach height in aufsteigender Reihenfolge und danach nach objectId in absteigender Reihenfolge.

Linux
Windows CMD

./vcdb export citygml [...] -o my-city.gml \
    --type-name=bldg:Building \
    --sort-by=con:height,core:objectId-

vcdb export citygml [...] -o my-city.gml ^
    --type-name=bldg:Building ^
    --sort-by=con:height,core:objectId-

Werden mehrerer Filter verwendet werden, müssen alle Bedingungen erfüllt sein, damit ein Feature exportiert wird.
Komplexe Filterausdrücke können sehr komfortabl in Konfigurationsdaten oder Argumentdateien ausgelagert und einfach wiederverwendet werden.
Bei aktiviertem trace Log-Level, wird die finale SQL SELECT Anweisung, die aus den Abfrage- und Filteroptionen generiert wurde und intern zur Abfrage der VCDB verwendet wird, in der Konsole ausgegeben.

Export historischer Versionen

Die bi-temporalen Intervalle [creation_date, termination_date) und [valid_from, valid_to) ermöglichen Objekt-Historien in der VCDB v5 (siehe hier). Das erste Intervall beschreibt die Lebensdauer des Features in der Datenbank – also wann es eingefügt und terminiert wurde. Das zweite Intervall beschreibt die Lebensdauer des Features in der realen Welt.

Die Gültigkeit eines Features hängt davon ab, ob das entsprechende Zeitintervall beschränkt oder unbeschränkt ist:

Unbeschränkt (kein Enddatum): Das Feature ist derzeit gültig.
Beschränkt: Das Feature war nur während des angegebenen Intervalls gültig, ist aber aktuell nicht mehr gültig.

Die --validity Option steuert, welche Features in Abhängigkeit von ihrer Gültigkeit exportiert werden:

valid: Exportiert nur aktuell gültige Features. Dies ist der Standardmodus.
invalid: Exportiert nur historische, nicht mehr gültige Features.
all: Exportiert alle Features – unabhängig von ihrer Gültigkeit.

Mit der Option --validity-reference wird festgelegt, ob sich die Gültigkeit auf die Datenbankzeit (database, Standard) oder auf die Realzeit (real_world) bezieht.

Zusätzlich erlaubt die Option --validity-at die Prüfung der Gültigkeit zu einem bestimmten Zeitpunkt in der Vergangenheit. Dieser Zeitpunkt kann entweder als Datum (<YYYY-MM-DD>) oder als Zeitstempel mit optionalem UTC-Offset (<YYYY-MM-DDThh:mm:ss[(+|-)hh:mm]>) angegeben werden. Es werden nur Features exportiert, die zu diesem Zeitpunkt entweder valid oder invalid waren.

Das folgende Beispiel zeigt den Export einer historischen Version des Stadtmodells, die am 01.07.2018 gültig war:

Linux
Windows CMD

./vcdb export citygml [...] -o my-city.gml \
    --validity=valid \
    --validity-at=2018-07-01 \
    --validity-referene=database

vcdb export citygml [...] -o my-city.gml ^
    --validity=valid ^
    --validity-at=2018-07-01 ^
    --validity-referene=database

Um historische Versionen exportieren zu können, müssen diese in der Datenbank gespeichert bleiben.
Die Datenbankzeit wird automatisch verwaltet: Das creation_date wird beim Import gesetzt, während das termination_date beim Terminieren von Features über den [delete](delete.md) Befehl eingetragen wird.
Standardmäßig erfolgt eine strenge Prüfung der Zeitintervalle. Mit der Option --lenient-validity wird dies aufgelockert, indem auch Zeitintervalle als gültig betrachtet werden, deren Startdatum nicht gesetzt ist.

Umprojizieren von Geometrien

Der export Befehl ermöglicht das Umprojizieren von Geometrien in ein anderes Koordinatenreferenzsystem (CRS) während des Exports. Dies ist hilfreich, wenn für die VCDB v5 Instanz ein bestimmtes CRS definiert wurde, die exportierten Daten jedoch in einem anderen CRS benötigt werden. Die Umprojektion erfolgt über die räumlichen Funktionen des zugrunde liegenden Datenbanksystems.

Um ein anderes Ziel-CRS für den Export festzulegen, wird die Option --crs-Option verwendet, gefolgt vom Datenbank-SRID oder dem Identifier des Ziel-CRS. vcdb-tool unterstützt sowohl OGC-konforme Namen wie http://www.opengis.net/def/crs/EPSG/0/4326 als auch einfachere Formate wie EPSG:4326 als Identifier.

Mit der Option --crs-name-Option kann der Name oder Identifier des Ziel-CRS angegeben werden, der in die Ausgabedatei geschrieben werden soll – beispielsweise als Wert für das srsName Attribut in CityGML-Dateien.

Linux
Windows CMD

./vcdb export citygml [...] -o my-city.gml \
    --crs=25833 \
    --crs-name=urn:ogc:def:crs,crs:EPSG::25833,crs:EPSG::7837

vcdb export citygml [...] -o my-city.gml ^
    --crs=25833 ^
    --crs-name=urn:ogc:def:crs,crs:EPSG::25833,crs:EPSG::7837

Transformation von Geometrien

Die --transform Option wendet eine affine Transformation auf die Geometrien an, bevor sie in die Ausgabedatei exportiert 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 -Koordinate unverändert beibehalten wird. Für diese Transformation kann auch swap_xy als Kurzschreibweise verwendet werden, wie im folgenden Beispiel gezeigt.

Linux
Windows CMD

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

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

Es muss sichergestellt werden, dass die transformierten Koordinaten weiterhin zu dem CRS passen, das für den Export verwendet wird.

Gekachelte Exporte

Anstatt Stadtmodelldaten aus der VCDB v5 in eine einzige, möglicherweise sehr große Datei zu exportieren, unterstützt vcdb-tool den Export in mehrere Dateien bzw. Kacheln auf Grundlage regelmäßiger räumlicher Gitter. Das Kacheln großer Exporte in kleinere Teile erleichtert die Verarbeitung, Übertragung und Visualisierung der Daten.

Definition der Ausdehnung für die Kachelung

Um einen kachelbasierten Export durchzuführen, muss zunächst die Ausdehnung für die Kachelung bestimmt werden. Dies kann auf zwei Arten erfolgen:

Automatisch berechnet: Die Ausdehnung wird automatisch als Bounding Box über alle zu exportierenden Features berechnet. Dies ist die Standardmethode.
Manuell definiert: Mit der Option --tile-extent kann die Ausdehnung auch manuell als 2D Bounding-Box durch vier Koordinaten für den linken unteren und rechten oberen Eckpunkt angegeben werden. 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.

Definition des Kachelgitters

Die Kachelausdehnung wird über eines von zwei Verfahren in ein Gitter unterteilt, das die Größe der einzelnen Kacheln bestimmt:

--tile-matrix: Gibt die Anzahl der Spalten (columns) und Zeilen (rows) des Gitters an. Die Ausdehnung wird gleichmäßig in Kacheln aufgeteilt. Eine höhere Anzahl von Spalten und Zeilen führt zu kleineren Kacheln.
--tile-dimension: Legt die Breite (width) und Höhe (height) jeder Kachel fest. Die Kacheln werden am Raster des Datenbank-CRS ausgerichtet und so gewählt, dass sie die Ausdehnung vollständig abdecken. Das kann auch dazu führen, dass sie über die Ausdehnung hinausreichen. Die Einheiten für width und height können explizit angegeben werden. Andernfalls wird die Einheit des Datenbank-CRS verwendet.

Jede Kachel wird durch ihre Spalten- und Zeilenindizes eindeutig identifiziert, wobei der Spaltenindex in horizontale Richtung zunimmt. Standardmäßig liegt der Ursprung (0,0) in der linken oberen Ecke. Dies kann mit --tile-origin auf die linke untere Ecke geändert werden.

vcdb-tool stellt sicher, dass jedes Feature genau einer Kachel zugewiesen wird. Für den Fall, dass die Kachelungsausdehnung manuell definiert wurde und ein Feature keiner Kachel zugewiesen werden kann, wird es vom Export ausgeschlossen.

Organisation gekachelter Exporte

Beim Exportieren in Kacheln können Platzhalter im Ausgabepfad und Dateinamen verwendet werden, um die Ausgabedateien systematisch zu organisieren. Die folgenden kachelspezifischen Tokens sind verfügbar:

Token Beschreibung

Token	Beschreibung
`@column@`	Spaltenindex der Kachel.
`@row@`	Zeilenindex der Kachel.
`@x_min@`	X-Koordinate des linken unteren Eckpunkts der Kachel.
`@y_min@`	Y-Koordinate des linken unteren Eckpunkts der Kachel.
`@x_max@`	X-Koordinate des rechten oberen Eckpunkts der Kachel.
`@y_max@`	Y-Koordinate des rechten oberen Eckpunkts der Kachel.

@column@

Spaltenindex der Kachel.

@row@

Zeilenindex der Kachel.

@x_min@

X-Koordinate des linken unteren Eckpunkts der Kachel.

@y_min@

Y-Koordinate des linken unteren Eckpunkts der Kachel.

@x_max@

X-Koordinate des rechten oberen Eckpunkts der Kachel.

@y_max@

Y-Koordinate des rechten oberen Eckpunkts der Kachel.

Werden zum Beispiel die folgenden Platzhalter bei Angabe der Ausgabedatei genutzt:

--output=tiles/@column@/tile_@row@.gml

Dann wird die folgende Dateistruktur erzeugt:

tiles/0/tile_0.gml
tiles/0/tile_1.gml
tiles/1/tile_0.gml
...

Wenn keine Platzhalter angegeben werden, hängt vcdb-tool automatisch den Suffix _@column@_@row@ an den Dateinamen an.
Es muss sichergestellt werden, dass das Muster der verwendeten Platzhalter keine Dateikonflikte oder Überschreibungen verursacht.

Formatierung der Tokens

Für jeden Platzhalter kann zusätzlich ein Formatstring verwendet werden, um den Wert des Platzhalters zu formatieren, z.B. zur Begrenzung der Nachkommastellen von Koordinatenwerten. Der Formatstring wird nach dem Token getrennt durch ein Komma angegeben. Zum Beispiel führt die Angabe von @x_min,%.2f@ dazu, dass der Koordinatenwert x_min auf zwei Nachkommastellen abgeschnitten wird.

Die Syntax für den Formatstring folgt der Java-Sprachkonvention. Einige häufig genutzte Beispiele sind:

%s: Formatiert den Wert als Zeichenkette (Standardformat).
%d: Formatiert den Wert als Ganzzahl.
%f: Formatiert den Wert als Dezimalzahl.
%.2f: Formatiert den Wert als Dezimalzahl mit zwei Nachkommastellen.
%4.4s: Formatiert den Wert als Zeichenkette, gibt aber nur genau vier Zeichen aus.

Beispiel für gekachelte Exporte

Im nachfolgenden Beispiel werden alle Straßen aus der VCDB exportiert und in 2x2 km große Kacheln aufgeteilt. Die Ausdehnung der Kachelung wird automatisch bestimmt. Die Kacheln sind am CRS-Raster ausgerichtet und werden so gewählt, dass sie die Kachelungsausdehnung abdecken. Weiterhin wird die Dateistruktur über formatierte Tokens im Ausgabepfad gesteuert.

Linux
Windows CMD

./vcdb export citygml [...] -o tiles/tile_@x_min,%3.3s@_@y_min,%4.4s@.gml \
    --type-name=tran:Road \
    --tile-dimension=2km,2km

vcdb export citygml [...] -o tiles\tile_@x_min,%3.3s@_@y_min,%4.4s@.gml ^
    --type-name=tran:Road ^
    --tile-dimension=2km,2km

In diesem Beispiel wird die Längeneinheit km explizit angegeben. Falls die Einheit weggelassen wird, wird stattdessen die Einheit des Datenbank-CRS verwendet. Nutzt das CRS beispielsweise Meter als Längeneinheit, muss eine 2x2 km Kachelung wie folgt definiert werden:

--tile-dimension=2000,2000

Wenn die resultierende Kachelgröße nicht den Erwartungen entspricht, überprüfen Sie die Einheit des Datenbank-CRS.

Steuerung des Exportprozesses

Der export Befehl bietet die folgenden Optionen zur Steuerung des Export-Prozesses:

--fail-fast: Beendet den Prozess sofort beim Auftreten eines Fehlers. Standardmäßig wird der Export trotz Fehlern beim Export einzelner Features fortgesetzt.
--temp-dir: Legt das Verzeichnis für temporäre Dateien während des Exports fest. Für optimale Performance sollte ein schnelles Speichermedium gewählt werden, das nicht zum Schreiben der Ausgabedateien verwendet wird.
--threads: Setzt die Anzahl der Threads für parallele Prozessierung fest. Eine höhere Anzahl 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.