CityJSON Export

Der export cityjson Befehl exportiert Stadtmodelldaten aus der VCDB v5 in eine CityJSON-Datei. Da CityJSON nur einen Teil des CityGML Conceptual Model abbildet, kann es beim Export nach CityJSON möglicherweise zu Datenverlust kommen.

Synopsis

vcdb export cityjson [OPTIONS]

Optionen

Der export cityjson Befehl erbt globale Optionen vom Hauptbefehl vcdb sowie allgemeine Export-, Abfrage-, und Filter- und Kachelungsoptionen von seinem übergeordneten export Befehl. Zusätzlich stellt er formatspezifische Exportoptionen für CityJSON bereit.

Globale Optionen

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

Weitere Informationen zu den globalen Optionen und Nutzungshinweise siehe hier.

Allgemeine Exportoptionen

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.

Weitere Informationen zu den allgemeinen Exportoptionen und Nutzungshinweise siehe hier.

CityJSON-Exportoptionen

Option Beschreibung Standardwert

-v, --cityjson-version=<version>

CityJSON-Version: 2.0, 1.1, 1.0.

2.0

--[no-]json-lines

Ausgabe als CityJSON Text Sequence im JSON Lines Format. Diese Option erfordert CityJSON 1.1 oder höher.

true

--pretty-print

Ausgabedatei formatieren und einrücken.

--html-safe

Gibt JSON aus, das sicher in HTML eingebettet werden kann.

--vertex-precision=<digits>

Anzahl der Nachkommastellen für Geometriekoordinaten.

3

--template-precision=<digits>

Anzahl der Nachkommastellen für Template-Koordinaten.

3

--texture-vertex-precision=<digits>

Anzahl der Nachkommastellen für Texturkoordinaten.

7

--[no-]transform-coordinates

Umwandlung von Koordinaten in Ganzzahlen beim Export nach CityJSON 1.0.

true

--replace-templates

Ersetzt Template-Geometrien durch Realwelt-Koordinaten.

--[no-]material-defaults

Verwendung von CityGML-Standardwerten für Materialeigenschaften.

true

Upgrade-Optionen für CityGML 2.0 und 1.0

Option Beschreibung Standardwert

--use-lod4-as-lod3

Verwende LoD4 als LoD3 und ersetze bestehende LoD3 Geometrien.

Abfrage- und Filteroptionen

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.

Weitere Informationen zu den Abfrage- und Filteroptionen und Nutzungshinweise siehe hier.

Zeitbasierte Objekt-Historie-Optionen

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.

Weitere Informationen zu den zeitbasierten Objekt-Historie-Optionen und Nutzungshinweise siehe hier.

Kachelungsoptionen

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

Weitere Informationen zu den Kachelungsoptionen und Nutzungshinweise siehe hier.

Datenbank-Verbindungsoptionen

Option Beschreibung Standardwert

-H, --db-host=<host>

Hostname des VCDB Datenbankservers.

-P, --db-port=<port>

Port des VCDB Datenbankservers.

5432

-d, --db-name=<database>

Name der VCDB-Instanz, zu eine Verbindung hergestellt werden soll.

-S, --db-schema=<schema>

Schema, das beim Verbinden zur VCDB verwendet werden soll.

citydb oder Benutzername

-u, --db-username=<user>

Benutzername für die Verbidung zur VCDB.

-p, --db-password
[=<password>]

Passwort für die Verbidung zur VCDB. Leer lassen, um zur Eingabe aufgefordert zu werden.

--db-property=<property=value>
[,<proeprty=value>…​]

Datenbankspezifische Verbindungsparameter.

Weitere Informationen zu den Datenbank-Verbindungsoptionen und Nutzungshinweise siehe hier.

Verwendung

Allgemeine Hinweise zur Nutzung, die für alle Unterbefehle des export Befehls gelten (einschließlich, aber nicht beschränkt auf export cityjson), finden Sie in der Dokumentation zum export Befehl hier.

Angabe der CityJSON-Version

Der export cityjson Befehl unterstützt die CityJSON-Versionen 2.0, 1.1 und 1.0 als Ausgabeformate. Verwenden Sie die Option --cityjson-version, um eine bestimmte Version für den Export auszuwählen (Standard: 2.0).

Streaming-Exporte

Beim Export nach CityJSON 2.0 und 1.1 ist das Standardausgabeformat CityJSON Text Sequence (CityJSONSeq), mit dem das Streaming auch sehr großer Exporte effizient unterstützt wird. Die Features werden dabei chunk-weise als einzelne CityJSONFeature Objekte exportiert, wobei jedes Objekt in einer eigenen Zeile in die Ausgabedatei geschrieben wird. Dieser Streaming-Ansatz verbessert die Effizienz für die Speicherung, reduziert den Speicherbedarf und ermöglicht den direkten Zugriff auf die CityJSON-Objekte während des Streamings.

Wenn das zeilenbasierte CityJSONSeq-Format nicht gewünscht wird, kann das Streaming mit der Option --no-json-lines deaktiviert werden.

CityJSON 1.0 unterstützt weder das CityJSONSeq Format noch generell das Streaming der Daten.
Ohne Streaming muss der gesamte Export vor dem Schreiben in die Ausgabedatei in den Hauptspeicher geladen werden. Bei großen Exporten kann dies schnell die Speichergrenzen des Systems überschreiten und damit zu Fehlern führen. Für solche Fällen sollten daher Filter oder gekachelte Exporte verwendet werden, um die Exportgröße zu reduzieren.

Upgrade von CityGML 2.0 und 1.0

CityJSON unterstützt keine LoD4-Repräsentation von Features, wie sie in CityGML 2.0 und 1.0 definiert sind. Wenn daher CityGML 2.0 oder 1.0 Daten mit LoD4-Geometrien in die VCDB v5 importiert wurden, werden diese Geometrien beim Export zu CityJSON standardmäßig nicht ausgegeben.

Um dieses Verhalten zu ändern, können LoD4-Geometrien mit der Option --use-lod4-as-lod3 während des Exports nach LoD3 konvertiert werden. Dabei werden jedoch gegebenenfalls vorhandene LoD3-Repräsentationen der Features überschrieben.

Transformation von Koordinaten

In CityJSON-Dateien können Koordinatenwerte von Geometrien als Ganzzahlen repräsentiert werden (Quantisierung), um die Dateigröße zu reduzieren. Um die Ganzzahlen wieder in die ursprünglichen Koordinatenwerte überführen zu können, werden der angewandte Skalierungs- und Translationsfaktor zur Ableitung der Ganzzahlen als "transform" Attribut in der Datei mitgespeichert.

Die Speicherung von Koordinatenwerten als Ganzzahlen ist für CityJSON 2.0 und 1.1 verpflichtend, für CityJSON 1.0 jedoch optional. Standardmäßig nutzt der export cityjson Befehl die Quantisierung auch für CityJSON 1.0, sie kann in diesem Fall aber mit der Option --no-transform-coordinates deaktiviert werden.

Ersetzung von Template-Geometrien

CityJSON unterstützt das CityGML-Konzept impliziter Geometrien, bei dem Template-Geometrien (Vorlagen) einmal gespeichert und von mehreren Features wiederverwendet werden können. Diese Template-Geometrien verwenden lokale Koordinaten. Jedes Feature, das ein solches Template nutzt, muss daher zusätzlich einen Referenzpunkt und eine Transformationsmatrix angeben, um die lokalen Koordinaten in Realwelt-Koordinaten zu überführen und das Template so feature-spezifisch im Stadtmodell zu platzieren.

Wenn die Ziel-Software, mit der der CityJSON-Export verarbeitet werden soll, keine Template-Geometrien unterstützt, kann die Option --replace-templates verwendet werden, um das Template bereits während des Exports durch Realwelt-Koordinaten zu ersetzen.

Das Ersetzen von Templates erhöht die Dateigröße und beseitigt die Vorteile ihrer Wiederverwendung.

Unterdrückung von Material-Standardwerten

Standardmäßig fügt vcdb-tool Standardwerte für Materialeigenschaften wie "diffuseColor", "emissiveColor" und "ambientIntensity" in die Ausgabedatei ein, wenn keine spezifische Werte in der Datenbank vorhanden sind. Diese Standardwerte sind im CityGML Appearance Modell definiert und helfen, Probleme mit Zielsystemen zu vermeiden, die diese Standardwerte nicht schon automatisch ergänzen.

Mit der Option --no-material-defaults kann dieses Verhalten unterdrückt werden. Dadurch werden die Standardwerte nicht mit in die Ausgabedateo geschrieben, was auch ihre Dateigröße reduziert.

Formatierung der Ausgabe

Der export cityjson Befehl bietet mehrere Optionen zur Formatierung der CityJSON-Datei:

  • --vertex-precision: Legt fest, wie viele Nachkommastellen für Geometriekoordinaten gespeichert werden. Die Koordinatenwerte werden auf die angegebene Anzahl von Nachkommastellen gerundet (Standard: 3). Diese Option bietet eine Balance zwischen Datengenauigkeit und Dateigröße. Mehr Nachkommastellen erhöhen die Präzision, können aber zu einer größeren Datei führen.

  • --template-precision: Wie --vertex-precision, betrifft aber die Anzahl der Nachkommastellen für Template-Geometrien (Standard: 3).

  • --texture-vertex-precision: Wie --vertex-precision, betrifft die Anzahl der Nachkommastellen für Texturkoordinaten (Standard: 7).

  • --pretty-print: Verbessert die Lesbarkeit der Hierarchie und Verschachtelung von JSON-Elementen durch Hinzufügung von Einrückungen und Zeilenumbrüchen, erhöht jedoch auch die Dateigröße.

  • --html-safe: Maskiert Sonderzeichen in der CityJSON-Ausgabedatei, um die JSON-Inhalte sicher in HTML einbetten zu können.

Die Option --pretty-print kann nicht mit Streaming-Exporten verwendet werden, da diese zeilenbasiertes JSON ausgeben.