Command Line#

Both distributions of CityDoctor — the batch version (CityDoctorValidation) and the graphical version (CityDoctorGUI) — are Java programs started from the command line.

Start scripts#

The easiest way to pass parameters is via the supplied start scripts (start.bat on Windows, start.sh on Linux/Mac). All parameters given to the script are passed on to CityDoctor unchanged:

start.bat -in city.gml -config plan.yml -xmlReport city_report.xml

./start.sh -in city.gml -config plan.yml -xmlReport city_report.xml

The scripts can be called from any directory. Distributions with a bundled Java runtime use it from the folder runtime; distributions without a runtime use the Java installation referenced by JAVA_HOME or, if it is not set, the java found on the PATH.

If the start script of the batch version is called without parameters, it validates the bundled example file REKaiserwall.gml with the validation plan testConfigWithStreaming.yml and writes the report output.xml.

Direct Java call#

The start scripts can also be replaced by a direct Java call, e.g. in your own scripts. The examples below assume that the command is executed in the directory where the zip file was extracted (it contains the folders app and plugins and, depending on the distribution, runtime).

Note

On Linux and Mac the classpath separator ; has to be replaced by :. Distributions that include a Java runtime use runtime/bin/java (or runtime\bin\java.exe on Windows) instead of java; in the Mac distribution the runtime is located in runtime/Contents/Home/bin/java.

Batch version (CityDoctorValidation)#

The batch version validates a CityGML file without a user interface and writes the results into report files.

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

Parameters#

Parameter	Required	Description
`-in <file>`	yes	CityGML file to validate. The file name has to end with `.gml` or `.xml`.
`-config <file>`	no	Validation plan in YAML format. If omitted, a default configuration is used (see below).
`-xmlReport <file>`	no	Writes an XML report to the given location.
`-pdfReport <file>`	no	Writes a PDF report to the given location.
`-out <file>`	no	Writes a copy of the input file to the given location in which the validation results are stored using the Quality-ADE.
`-db_location <path>`	no	Location of the embedded database that CityDoctor uses while processing. If the path does not point to an existing file, it is treated as a directory and the database file `cd_db` is created inside it (missing directories are created). See Database settings.
`-db_config <file>`	no	`.properties` file overriding the settings of the embedded database (see Database settings).

Each parameter starts with a single - followed by exactly one value. Parameter names are not case-sensitive (-xmlReport and -xmlreport are equivalent). Paths containing spaces have to be quoted.

Note

If none of -xmlReport, -pdfReport or -out is given, the validation runs but no result file is written.

Examples#

Validation with a validation plan and both reports:

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

Validation with the default configuration, writing the results into the CityGML file (Linux/Mac):

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

Exit codes#

If the parameters are invalid the program terminates with an exit code other than 0:

Exit code	Cause
1	`-in` missing, input file does not exist, file does not end with `.gml`/`.xml`, or a parameter could not be parsed
2	`-in` has not exactly one value
4	`-config` has not exactly one value
5	`-xmlReport` has not exactly one value
6	`-pdfReport` has not exactly one value
12	`-out` has not exactly one value

Errors that occur while reading the CityGML file (e.g. a file that is not well-formed XML) or while writing reports end the program with an error message and a stack trace.

Alternative entry point with long options#

The batch distribution additionally contains the entry point de.hft.stuttgart.citydoctor2.CityDoctorValidationCLI. It provides the same functions with short and long option names in the usual GNU style, as well as a help text:

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

Option	Corresponds to
`-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`	prints the help text

Example:

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

In contrast to CityDoctorValidation, the option names of this entry point are case-sensitive.

Graphical version (CityDoctorGUI)#

Without parameters the graphical user interface starts empty and a file can be loaded via the menu (see User Interface):

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

The GUI accepts the same parameters as the batch version. If -in is given, CityDoctor loads the file directly after startup, runs the validation and, if requested, writes the reports. The model and the errors can then be inspected in the user interface.

Parameter	Description
`-in <file>`	CityGML file that is loaded and validated after startup.
`-config <file>`	Validation plan used for the validation at startup. Default configuration if omitted.
`-xmlReport <file>`	Writes an XML report after the validation at startup.
`-pdfReport <file>`	Writes a PDF report after the validation at startup.
`-db_location <path>`	Location of the embedded database (see batch version).
`-db_config <file>`	Settings of the embedded database (see batch version).

-config, -xmlReport and -pdfReport are only evaluated together with -in. The parameter -out is not supported by the GUI; the validated file can be saved from the user interface instead.

Example:

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

Note

When the GUI validates a file at startup, the setting useStreaming of the validation plan is ignored: the complete file is loaded into memory so that it can be displayed.

Default configuration#

If no validation plan is given, CityDoctor uses a default configuration:

all available geometric and semantic requirements are enabled with their default parameters (see Validation Plan),
numberOfRoundingPlaces: 8, minVertexDistance: 0.0001,
schematronPath: checkForSolid.xml (relative to the working directory; if the file does not exist, the Schematron validation is skipped with a warning),
no streaming, no XML schema validation, no filter.

A warning in the log indicates that the default configuration is used. For reproducible results it is recommended to always pass an explicit validation plan.

Database settings#

During processing CityDoctor stores data in an embedded database file (H2). By default the file cd_db is created in the directory citydoctor/database inside the system's temporary directory (e.g. %TEMP%\citydoctor\database on Windows, /tmp/citydoctor/database on Linux). Another location, e.g. a drive with more free space, can be set with -db_location.

Further settings can be made in a .properties file that is passed with -db_config. A file named DBSettings.properties in the working directory is read automatically. Supported keys:

Key	Default	Description
`database.directory`	`<temp>/citydoctor/database`	Directory of the database file
`database.name`	`cd_db`	Name of the database file
`database.connectionPoolSize`	number of CPU cores	Maximum number of pooled database connections
`database.tempMode`	`false`	Creates the database file in a new, uniquely named subdirectory of `database.directory` that is deleted when CityDoctor exits. Useful if several CityDoctor instances run at the same time.
`database.inMemoryMode`	`false`	Keeps the database in RAM. Can lead to out-of-memory errors for large files.
`database.attemptFallback`	`true`	Switches to in-memory mode if the database file cannot be created
`database.debugMode`	`false`	Starts the database in mixed mode with a local server (for debugging only)

Example:

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

If both are given, -db_location overrides database.directory and database.name from the -db_config file.

Memory#

For large files the maximum memory of the Java virtual machine can be increased with the JVM option -Xmx, which has to be placed before -classpath:

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

Alternatively the batch version can read the file piece by piece with useStreaming: true in the validation plan, which considerably reduces the memory requirement.