Using vcdb-tool

This guide provides a quick introduction to importing and exporting CityGML or CityJSON data into the VCDB using vcdb-tool. It is intended to help you get started with the basics, while the full documentation of vcdb-tool is available here. vcdb-tool is the default command-line client for VCDB v5, designed for importing and exporting city model data and performing various database operations.

Prerequisites

Before you begin, ensure you have the following:

A ready-to-use VCDB v5 instance (see VCDB setup guide).
A matching release package of vcdb-tool.
A system that meets the requirements for running vcdb-tool.
A CityGML dataset to import.

Step 1: Setting up vcdb-tool

vcdb-tool is distributed as a ZIP package and does not require a specific installation process. Simply extract the package to a directory of your choice. Inside this directory, you will find the vcdb start script for running the tool. Two versions of this start script are provided:

vcdb for UNIX/Linux/macOS systems; and
vcdb.bat for Windows systems.

vcdb-tool is a command-line tool that offers multiple commands, each with its own set of command-line parameters and options, making it best run from within a shell environment. To quickly verify that the tool is working correctly on your system, open a shell, navigate to the installation directory of vcdb-tool, and run the following command to print its version information to the console. On UNIX/Linux machines, you may first need to set the appropriate file permissions to make the script executable.

Linux
Windows CMD

chmod u+x citydb
./vcdb --version

vcdb --version    # you can omit the .bat file extension

vcdb --help lists all available commands in vcdb-tool. Note that some commands may have subcommands. To display help information for a specific (sub)command, simply use vcdb COMMAND [SUBCOMMAND…] --help.

Step 2: Importing CityGML data

Once you have confirmed that vcdb-tool is working correctly, you can proceed with importing CityGML data into your VCDB instance. For this, ensure that you have the database connection details ready or consult your database administrator.

If you do not have a CityGML dataset available for this step, you can use one of the sample datasets provided by vcdb-tool in the samples/datasets subfolder.

Linux
Windows CMD

./vcdb import citygml \
    -H the.host.de \
    -d theDBName \
    -u theUsername \
    -p theSecretPass \
    /path/to/citygml.gml

vcdb import citygml ^
    -H the.host.de ^
    -d theDBName ^
    -u theUsername ^
    -p theSecretPass ^
    C:\path\to\citygml.gml

The parameters used in this simple example are:

-H: The host of your VCDB instance (e.g., localhost or the.host.de).
-d: The name of the VCDB database where the CityGML data will be imported.
-u: The database username with sufficient privileges to perform the import.
-p: The password for the provided database username (leave empty to be prompted!).
/path/to/citygml.gml: The path to the CityGML file you wish to import.

During the import process, log messages will be printed to the console, informing you about the progress of the operation. If the import completes successfully, a summary of the imported city objects will be displayed. In case of errors, the import is aborted, and an error message with details about the cause will be shown. To enable more verbose logging and get additional error details, add the --log-level debug parameter to the import command.

Figure 1. Example console output of a vcdb-tool import operation.

To import a CityJSON dataset instead, simply use the command import cityjson and point to your CityJSON input file.

Step 3: Exporting CityGML data

Exporting the data from the VCDB back to CityGML format is as easy as this:

Linux
Windows CMD

./vcdb export citygml \
    -H the.host.de \
    -d theDBName \
    -u theUsername \
    -p theSecretPass \
    -o /path/to/target/citygml.gml

vcdb export citygml ^
    -H the.host.de ^
    -d theDBName ^
    -u theUsername ^
    -p theSecretPass ^
    -o C:\path\to\target\citygml.gml

The output file’s path and name must be specified using the -o parameter. All other parameters in this example match those used in the import operation. The export process logs progress and errors just like the import. Use --log-level debug for detailed output. If you want to export to a different CityGML version, use the -v parameter with 3.0, 2.0, or 1.0 as the value, depending on the desired target version.

Once the export completes successfully, a summary of the exported city objects will be shown.

Figure 2. Example console output of a vcdb-tool export operation.

To export the data in CityJSON format, simply use the command export cityjson instead. This works even if you have imported a CityGML file, as vcdb-tool applies an on-the-fly conversion between both formats.