Import Command

The import command imports city model data into the VCDB v5 in a supported format. Each format has a dedicated subcommand with format-specific options.

Synopsis

vcdb import [OPTIONS] COMMAND

Options

The import command inherits global options from the main vcdb command. Additionally, it defines general import, metadata, and filter options, which apply to all of its subcommands.

Global options

Option Description Default value

[@<filename>…​]

One or more argument files containing options.

-h, --help

Show a help message and exit.

-V, --version

Print version information and exit.

--config-file=<file>

Load configuration from this file.

-L, --log-level=<level>

Log level: fatal, error, warn, info, debug, trace.

info

--log-file=<file>

Write log messages to this file.

--quiet

Disable console log messages.

--pid-file=<file>

Create a file containing the process ID.

--plugins=<dir>

Load plugins from this directory.

--use-plugin=<plugin[=true|false]>
[,<plugin[=true|false]>…​]

Enable or disable plugins with a matching fully qualified class name.

true

For more details on the global options and usage hints, see here.

General import options

Option Description Default value

<file>…​

One or more files and directories to process (glob patterns allowed).

--input-encoding=<encoding>

Encoding of input file(s).

--fail-fast

Fail fast on errors.

--temp-dir=<dir>

Store temporary files in this directory.

-m, --import-mode=<mode>

Import mode: import_all, skip, delete, terminate.

import_all

--threads=<threads>

Number of threads to use for parallel processing.

--preview

Run in preview mode. Features will not be imported.

--index-mode=<mode>

Index mode: keep, drop, drop_create. Consider dropping indexes when processing large quantities of data.

keep

--compute-extent

Compute and overwrite extents of features.

--transform=
<m0,m1,…​,m11|swap-xy>

Transform coordinates using a 3x4 matrix in row-major order. Use swap-xy as a shortcut.

Metadata options

Option Description Default value

--lineage=<lineage>

Lineage to use for the features.

--updating-person=<name>

Name of the user responsible for the import.

database user

--reason-for-update=<reason>

Reason for importing the data.

Filter options

Option Description Default value

-t, --type-name=<[prefix:]name>
[,<[prefix:]name>…​]

Names of the features to process.

-i, --id=<id>[,<id>…​]

Identifiers of the features to process.

-b, --bbox=<x_min,y_min,x_max,y_max[,srid]>

Bounding box to use as spatial filter.

--bbox-mode=<mode>

Bounding box mode: intersects, contains, on_tile.

intersects

--limit=<count>

Maximum number of features to process.

--start-index=<index>

Index within the input set from which features are processed.

Commands

Command Description

help

Display help information about the specified command.

citygml

Import data in CityGML format.

cityjson

Import data in CityJSON format.
Additional subcommands to support more formats may be added in future versions. You can also implement your own plugin to add support for a specific format.

Usage

Specifying import files

The input for import is specified using one or more <file> arguments, each of which can point to either a file or a directory. You can also use glob patterns with wildcard characters such as *, ?, [ ], or { } to match multiple files.

If a directory is provided, it will be scanned recursively for supported input files. The supported file formats and extensions depend on the subcommand. In addition to regular files, ZIP archives and GZIP-compressed files are supported as input. Like directories, ZIP archives are also scanned recursively for supported input files. The following example shows different ways for defining input files.

  • Linux

  • Windows CMD

./vcdb import citygml [...] \
    /path/to/my-city.gml \
    /foo/ \
    /bar/**/city*.{gml,gz,zip}
vcdb import citygml [...] ^
    C:\path\to\my-city.gml ^
    C:\foo\ ^
    C:\bar\**\city*.{gml,gz,zip}

To enforce a specific encoding for the input files, provide the IANA-based encoding name (e.g., UTF-8) with the --input-encoding option. This encoding will be applied to all input files.

Import modes and duplicate features

The import mode, defined by the --import-mode option, determines how duplicate features are handled in the database. The available modes are:

  • import_all: All features from the input files are imported, even if duplicates are created. This is the default mode.

  • skip: Features already in the database take precedence. If a duplicate is found, the feature from the input file is ignored and not imported.

  • delete: Features from the input files take precedence. If a duplicate is found, the existing feature in the database is deleted before the new feature is imported.

  • terminate: Similar to delete, but the duplicate feature in the database is terminated rather than deleted (for the difference, see the delete command).

  • Duplicates are identified by comparing the objectid column in the FEATURE table with the feature identifier from the input file (e.g., gml:id for CityGML files). No additional checks are applied for identifying duplicates.

  • Terminated features are excluded from the duplicates check.

Previewing the import

The --preview option runs the import in preview mode. The input data is processed as if the import were taking place, but no changes are made to the database. This mode helps identify potential issues, such as conflicts or errors, before they affect the database, ensuring the actual import proceeds as expected.

Filtering features

The import command provides several filtering options to control which features are imported from the input files.

Feature type filter

The --type-name option specifies one or more feature types to import. For each feature type, provide its type name as defined in the OBJECTCLASS table of the VCDB v5. To avoid ambiguity, you can use the namespace alias from the NAMESPACE table as a prefix in the format prefix:name. Only features matching the specified type will be imported.

Feature identifier filter

The --id option enables filtering by one or more feature identifiers provided as a comma-separated list. Only features with a matching identifier will be imported.

Bounding box filter

The --bbox option defines a 2D bounding box as a spatial filter using four coordinates for the lower-left and upper-right corners. By default, the coordinates are assumed to be in the same CRS as the VCDB instance. However, you can specify the database SRID of the CRS as a fifth value (e.g., 4326 for WGS84). All values must be separated by commas.

The filter behavior is controlled by the --bbox-mode option:

  • intersects: Only features whose bounding box overlaps with the filter bounding box will be imported. This is the default mode.

  • contains: Only features whose bounding box is entirely within the filter bounding box will be imported.

  • on_tile: Only features whose bounding box center lies within the filter bounding box or on its left/bottom boundary will be imported. This mode ensures that when multiple filter bounding boxes are organized in a tile grid, each feature matches exactly one tile.

Count filter

The --limit option sets the maximum number of features to import. The --start-index option defines the 0-based index of the first feature to import. These options apply across all input files and can be used separately or together to control the total number of features imported.

Filter example

The following example illustrates a CityGML import command with multiple filters:

  • Linux

  • Windows CMD

./vcdb import citygml [...] my-city.gml \
    --type-name=bldg:Building,tran:Road \
    --bbox=367123,5807268,367817,5807913,25833 \
    --bbox-mode=on_tile \
    --limit=100
vcdb import citygml [...] my-city.gml ^
    --type-name=bldg:Building,tran:Road ^
    --bbox=367123,5807268,367817,5807913,25833 ^
    --bbox-mode=on_tile ^
    --limit=100

  • When using multiple filters, all conditions must be satisfied for a feature to be imported.

  • Configuration and argument files are an excellent way to store complex filter expressions and easily reuse them.

Managing indexes during import

When importing data, database indexes are updated in real time, which can slow down the import process, especially with large datasets. The --index-mode option offers the following modes for handling indexes during the import operation:

  • keep: The indexes remain unchanged. This is the default mode.

  • drop: The indexes are removed before the import starts, improving import performance.

  • drop_create: Similar to drop, but the indexes are re-created after the import completes, ensuring they are available for subsequent queries.

Dropping and re-creating indexes can also take a significant amount of time, depending on the size of the database. This mode is beneficial when importing large datasets, such as during the initial loading of the database. However, as the database grows, the overhead of dropping and re-creating indexes may outweigh the benefits, especially when importing smaller datasets.
The index command allows you to manage indexes independently of the import operation, giving you greater control over index handling.

Computing extents

By default, vcdb-tool reads feature bounding boxes from the input file and stores them in the envelope column of the FEATURE table. A correct envelope is essential for spatial queries. With the --compute-extent option, vcdb-tool computes envelopes instead of using those from the input file. The computation considers the geometries of each feature and its subfeatures across all LoDs.

You can also recompute envelopes after import using database functions in the VCDB v5, as explained here.

Transforming geometries

The --transform option applies an affine transformation to input geometries using a 3x4 transformation matrix before they are imported into the database. The matrix operates on homogeneous coordinates to compute the transformed coordinates :

The --transform option expects a comma-separated list of 12 matrix coefficients in row-major order, from to :

--transform=m0,m1,m2,m3,m4,m5,m6,m7,m8,m9,m10,m11

A common use case is swapping the and coordinates while keeping unchanged. You can use swap_xy as shorthand for this transformation, as shown below.

  • Linux

  • Windows CMD

./vcdb import citygml [...] my-city.gml \
    --transform=swap_xy
vcdb import citygml [...] my-city.gml ^
    --transform=swap_xy
Ensure that the transformed coordinates remain consistent with the CRS defined for your VCDB instance.

Defining import metadata

The options --lineage, --updating-person, and --reason-for-update capture metadata about the feature’s origin, the person responsible for the import, and the reason for the import. This metadata is specific to VCDB and is not part of the CityGML standard (see also here). If not provided, the username used to establish the VCDB database connection will be used as the default value for --updating-person.

Controlling the import process

The import command offers the following options to control the import process:

  • --fail-fast: Terminates the process immediately upon encountering an error. By default, the import continues despite errors with individual features.

  • --temp-dir: Specifies the directory for storing temporary files during import. For optimal performance, choose a fast storage medium not used for reading the input files.

  • --threads: Sets the number of threads for parallel processing to improve performance. By default, it equals the number of processors available to the JVM, or at least two.

Setting the number of threads too high can lead to performance issues due to thrashing. Additionally, each thread requires a separate database connection, so ensure your database can handle the required number of connections.