Kommandozeile#

Beide Distributionen von CityDoctor – die Batch-Version (CityDoctorValidation) und die grafische Version (CityDoctorGUI) – sind Java-Programme, die über die Kommandozeile gestartet werden.

Startskripte#

Am einfachsten werden Parameter über die mitgelieferten Startskripte übergeben (start.bat unter Windows, start.sh unter Linux/Mac). Alle Parameter, die dem Skript übergeben werden, reicht es unverändert an CityDoctor weiter:

start.bat -in stadt.gml -config plan.yml -xmlReport stadt_bericht.xml

./start.sh -in stadt.gml -config plan.yml -xmlReport stadt_bericht.xml

Die Skripte können aus jedem Verzeichnis aufgerufen werden. Distributionen mit mitgelieferter Java-Laufzeitumgebung verwenden diese aus dem Ordner runtime; Distributionen ohne Laufzeitumgebung verwenden die Java-Installation aus JAVA_HOME oder, falls diese Variable nicht gesetzt ist, das java aus dem PATH.

Wird das Startskript der Batch-Version ohne Parameter aufgerufen, prüft es die mitgelieferte Beispieldatei REKaiserwall.gml mit dem Prüfplan testConfigWithStreaming.yml und schreibt den Bericht output.xml.

Direkter Java-Aufruf#

Die Startskripte können auch durch einen direkten Java-Aufruf ersetzt werden, z. B. in eigenen Skripten. Die folgenden Beispiele gehen davon aus, dass der Befehl in dem Verzeichnis ausgeführt wird, in das die Zip-Datei entpackt wurde (es enthält die Ordner app und plugins und je nach Distribution runtime).

Note

Unter Linux und Mac muss das Trennzeichen ; im Classpath durch : ersetzt werden. Distributionen mit mitgelieferter Java-Laufzeitumgebung verwenden runtime/bin/java (bzw. runtime\bin\java.exe unter Windows) anstelle von java; in der Mac-Distribution liegt die Laufzeitumgebung unter runtime/Contents/Home/bin/java.

Batch-Version (CityDoctorValidation)#

Die Batch-Version prüft eine CityGML-Datei ohne Benutzeroberfläche und schreibt die Ergebnisse in Berichtsdateien.

java -classpath app/*;plugins/* de.hft.stuttgart.citydoctor2.CityDoctorValidation -in <datei.gml> [Optionen]

Parameter#

Parameter	Pflicht	Beschreibung
`-in <datei>`	ja	Zu prüfende CityGML-Datei. Der Dateiname muss auf `.gml` oder `.xml` enden.
`-config <datei>`	nein	Prüfplan im YAML-Format. Ohne Angabe wird eine Standardkonfiguration verwendet (siehe unten).
`-xmlReport <datei>`	nein	Schreibt einen XML-Bericht an den angegebenen Ort.
`-pdfReport <datei>`	nein	Schreibt einen PDF-Bericht an den angegebenen Ort.
`-out <datei>`	nein	Schreibt eine Kopie der Eingabedatei an den angegebenen Ort, in der die Prüfergebnisse mit der Quality-ADE gespeichert sind.
`-db_location <pfad>`	nein	Ort der eingebetteten Datenbank, die CityDoctor während der Verarbeitung nutzt. Zeigt der Pfad nicht auf eine bestehende Datei, wird er als Verzeichnis behandelt und darin die Datenbankdatei `cd_db` angelegt (fehlende Verzeichnisse werden erstellt). Siehe Datenbankeinstellungen.
`-db_config <datei>`	nein	`.properties`-Datei, die die Einstellungen der eingebetteten Datenbank überschreibt (siehe Datenbankeinstellungen).

Jeder Parameter beginnt mit einem einfachen - und erwartet genau einen Wert. Groß- und Kleinschreibung der Parameternamen spielt keine Rolle (-xmlReport und -xmlreport sind gleichwertig). Pfade mit Leerzeichen müssen in Anführungszeichen gesetzt werden.

Note

Wird keiner der Parameter -xmlReport, -pdfReport oder -out angegeben, läuft die Prüfung zwar durch, es wird aber keine Ergebnisdatei geschrieben.

Beispiele#

Prüfung mit Prüfplan und beiden Berichten:

java -classpath app/*;plugins/* de.hft.stuttgart.citydoctor2.CityDoctorValidation -in stadt.gml -config plan.yml -xmlReport stadt_bericht.xml -pdfReport stadt_bericht.pdf

Prüfung mit Standardkonfiguration, Ergebnisse werden in die CityGML-Datei geschrieben (Linux/Mac):

java -classpath "app/*:plugins/*" de.hft.stuttgart.citydoctor2.CityDoctorValidation -in stadt.gml -out stadt_geprueft.gml

Exit-Codes#

Bei ungültigen Parametern beendet sich das Programm mit einem Exit-Code ungleich 0:

Exit-Code	Ursache
1	`-in` fehlt, Eingabedatei existiert nicht, Datei endet nicht auf `.gml`/`.xml` oder ein Parameter konnte nicht gelesen werden
2	`-in` hat nicht genau einen Wert
4	`-config` hat nicht genau einen Wert
5	`-xmlReport` hat nicht genau einen Wert
6	`-pdfReport` hat nicht genau einen Wert
12	`-out` hat nicht genau einen Wert

Fehler beim Einlesen der CityGML-Datei (z. B. kein wohlgeformtes XML) oder beim Schreiben der Berichte beenden das Programm mit einer Fehlermeldung und einem Stacktrace.

Alternativer Einstiegspunkt mit langen Optionen#

Die Batch-Distribution enthält zusätzlich den Einstiegspunkt de.hft.stuttgart.citydoctor2.CityDoctorValidationCLI. Er bietet dieselben Funktionen mit kurzen und langen Optionsnamen im üblichen GNU-Stil sowie einen Hilfetext:

java -classpath app/*;plugins/* de.hft.stuttgart.citydoctor2.CityDoctorValidationCLI --help

Option	Entspricht
`-i`, `--in`, `--input`	`-in`
`-c`, `--config`, `--configuration`, `--plan`	`-config`
`-x`, `--xml`, `--xmlReport`	`-xmlReport`
`-p`, `--pdf`, `--pdfReport`	`-pdfReport`
`-o`, `--out`, `--output`	`-out`
`--db_location`, `--db_loc`	`-db_location`
`-db`, `--db_config`, `--db_settings`	`-db_config`
`-h`, `--help`	gibt den Hilfetext aus

Beispiel:

java -classpath app/*;plugins/* de.hft.stuttgart.citydoctor2.CityDoctorValidationCLI -i stadt.gml -c plan.yml -x stadt_bericht.xml

Anders als bei CityDoctorValidation wird bei diesem Einstiegspunkt zwischen Groß- und Kleinschreibung der Optionsnamen unterschieden.

Grafische Version (CityDoctorGUI)#

Ohne Parameter startet die grafische Oberfläche leer, und eine Datei kann über das Menü geladen werden (siehe Nutzeroberfläche):

java -classpath app/*;plugins/* de.hft.stuttgart.citydoctor2.gui.CityDoctorGUIStarter

Die GUI akzeptiert dieselben Parameter wie die Batch-Version. Ist -in angegeben, lädt CityDoctor die Datei direkt nach dem Start, führt die Prüfung durch und schreibt bei Bedarf die Berichte. Modell und Fehler können anschließend in der Oberfläche untersucht werden.

Parameter	Beschreibung
`-in <datei>`	CityGML-Datei, die nach dem Start geladen und geprüft wird.
`-config <datei>`	Prüfplan für die Prüfung beim Start. Ohne Angabe Standardkonfiguration.
`-xmlReport <datei>`	Schreibt nach der Prüfung beim Start einen XML-Bericht.
`-pdfReport <datei>`	Schreibt nach der Prüfung beim Start einen PDF-Bericht.
`-db_location <pfad>`	Ort der eingebetteten Datenbank (siehe Batch-Version).
`-db_config <datei>`	Einstellungen der eingebetteten Datenbank (siehe Batch-Version).

-config, -xmlReport und -pdfReport werden nur zusammen mit -in ausgewertet. Der Parameter -out wird von der GUI nicht unterstützt; die geprüfte Datei kann stattdessen aus der Oberfläche heraus gespeichert werden.

Beispiel:

java -classpath app/*;plugins/* de.hft.stuttgart.citydoctor2.gui.CityDoctorGUIStarter -in stadt.gml -config plan.yml -pdfReport stadt_bericht.pdf

Note

Prüft die GUI eine Datei beim Start, wird die Einstellung useStreaming des Prüfplans ignoriert: Die komplette Datei wird in den Speicher geladen, damit sie angezeigt werden kann.

Standardkonfiguration#

Wird kein Prüfplan angegeben, verwendet CityDoctor eine Standardkonfiguration:

alle verfügbaren geometrischen und semantischen Anforderungen sind mit ihren Standardparametern aktiviert (siehe Prüfplan),
numberOfRoundingPlaces: 8, minVertexDistance: 0.0001,
schematronPath: checkForSolid.xml (relativ zum Arbeitsverzeichnis; existiert die Datei nicht, wird die Schematron-Prüfung mit einer Warnung übersprungen),
kein Streaming, keine XML-Schemavalidierung, kein Filter.

Eine Warnung im Log weist darauf hin, dass die Standardkonfiguration verwendet wird. Für reproduzierbare Ergebnisse empfiehlt es sich, immer einen expliziten Prüfplan zu übergeben.

Datenbankeinstellungen#

Während der Verarbeitung legt CityDoctor Daten in einer eingebetteten Datenbankdatei (H2) ab. Standardmäßig wird die Datei cd_db im Verzeichnis citydoctor/database innerhalb des temporären Verzeichnisses des Systems angelegt (z. B. %TEMP%\citydoctor\database unter Windows, /tmp/citydoctor/database unter Linux). Ein anderer Ort, z. B. ein Laufwerk mit mehr freiem Speicher, kann mit -db_location festgelegt werden.

Weitere Einstellungen können in einer .properties-Datei vorgenommen werden, die mit -db_config übergeben wird. Eine Datei namens DBSettings.properties im Arbeitsverzeichnis wird automatisch eingelesen. Unterstützte Schlüssel:

Schlüssel	Standard	Beschreibung
`database.directory`	`<temp>/citydoctor/database`	Verzeichnis der Datenbankdatei
`database.name`	`cd_db`	Name der Datenbankdatei
`database.connectionPoolSize`	Anzahl der CPU-Kerne	Maximale Anzahl gepoolter Datenbankverbindungen
`database.tempMode`	`false`	Legt die Datenbankdatei in einem neuen, eindeutig benannten Unterverzeichnis von `database.directory` an, das beim Beenden von CityDoctor gelöscht wird. Nützlich, wenn mehrere CityDoctor-Instanzen gleichzeitig laufen.
`database.inMemoryMode`	`false`	Hält die Datenbank im Arbeitsspeicher. Kann bei großen Dateien zu Speicherfehlern führen.
`database.attemptFallback`	`true`	Wechselt in den In-Memory-Modus, falls die Datenbankdatei nicht angelegt werden kann
`database.debugMode`	`false`	Startet die Datenbank im Mixed Mode mit lokalem Server (nur zur Fehlersuche)

Beispiel:

database.directory=D:\\citydoctor\\db
database.connectionPoolSize=4

Sind beide angegeben, überschreibt -db_location die Werte database.directory und database.name aus der -db_config-Datei.

Arbeitsspeicher#

Bei großen Dateien kann der maximale Arbeitsspeicher der Java Virtual Machine mit der JVM-Option -Xmx erhöht werden, die vor -classpath stehen muss:

java -Xmx16g -classpath app/*;plugins/* de.hft.stuttgart.citydoctor2.CityDoctorValidation -in grosse_stadt.gml -config plan.yml -xmlReport bericht.xml

Alternativ kann die Batch-Version die Datei mit useStreaming: true im Prüfplan Stück für Stück einlesen, was den Speicherbedarf erheblich reduziert.