vcdb-tool

vcdb-tool is the default command-line client for the VC Database v5. It supports importing and exporting city model data, as well as data and database management operations. The command-line interface (CLI) offers various commands for interacting with the database, each with its own parameters and options. In addition to manual execution in a shell, vcdb-tool can be automated, integrated with other software, and used in workflows and pipelines.

Key features

Support for CityGML 3.0, 2.0, and 1.0
Support for CityJSON 2.0, 1.1, and 1.0, including CityJSONSeq
On-the-fly upgrade and downgrade between versions
Import and export of datasets of any file size
Multiple import strategies for consistent city model updates
Deletion and termination of city objects with support for object histories
Advanced querying capabilities based on OGC CQL2 and SQL
Extensible via user-defined plugins
Easy deployment and execution in a Docker container
Seamless integration into automation workflows for streamlined processes

Installing and launching

vcdb-tool is distributed as a ZIP package and does not require installation. 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.

To launch vcdb-tool, open a shell, navigate to the vcdb-tool installation directory, and run the following command to display a general help message in the console. On UNIX/Linux systems, you may first need to adjust file permissions to make the script executable.

Java is required to run the software. For more information, consult the system requirements.

Linux
Windows CMD

chmod u+x vcdb
./vcdb --help

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

If your system is set up correctly and the vcdb --help command runs successfully, you should see output similar to the example below.

Figure 1. Running vcdb --help in the Windows Command Prompt.

Using environment variables for launch

vcdb-tool supports the following environment variables to configure the launch process.

Environment variable Description

Environment variable	Description
`JAVA_HOME`	Specifies the directory where the Java Runtime Environment (JRE) or Java Development Kit (JDK) is installed on your system.
`DEFAULT_JVM_OPTS`	Defines Java Virtual Machine (JVM) options for the launch process.
`JAVA_OPTS`	Functions like `DEFAULT_JVM_OPTS`, but takes precedence over it.
`VCDB_OPTS`	Functions like `JAVA_OPTS` and `DEFAULT_JVM_OPTS`, but takes precedence over both.

JAVA_HOME

Specifies the directory where the Java Runtime Environment (JRE) or Java Development Kit (JDK) is installed on your system.

DEFAULT_JVM_OPTS

Defines Java Virtual Machine (JVM) options for the launch process.

JAVA_OPTS

Functions like DEFAULT_JVM_OPTS, but takes precedence over it.

VCDB_OPTS

Functions like JAVA_OPTS and DEFAULT_JVM_OPTS, but takes precedence over both.

JAVA_HOME defines the JRE or JDK that vcdb-tool will use. This is helpful if you want to use a different version of Java than the system default or if the Java installation is not automatically detected, preventing vcdb-tool from launching.

vcdb-tool is launched with default JVM options, which can be overridden by setting the VCDB_OPTS environment variable. You can also use JAVA_OPTS or DEFAULT_JVM_OPTS to pass JVM options to the vcdb script. For example, to increase the JVM’s maximum heap size, the option -Xmx can be used. The following command shows how to set JAVA_HOME to specify the Java installation and use VCDB_OPTS to allocate two gigabytes for the heap space.

Linux
Windows CMD

export JAVA_HOME="/path/to/your/java/installation"
export VCDB_OPTS="-Xmx2g"

./vcdb import citygml \
    -H localhost -d citydb -u citydb_user -p mySecret \
    /my/city.gml

set JAVA_HOME="C:\path\to\your\java\installation"
set VCDB_OPTS="-Xmx2g"

vcdb import citygml citygml ^
    -H localhost -d citydb -u citydb_user -p mySecret ^
    C:\my\city.gml

Additional JVM options, such as -Xms for the initial heap size or -Dproperty=value for system properties, can also be added as needed.

The default JVM options are typically sufficient for most use cases and should only be overridden if necessary. Advanced users can also modify the vcdb start script directly to adjust the launch configuration and add custom JVM options.