Import command¶

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

Synopsis¶

citydb import [OPTIONS] COMMAND

Options¶

The import command inherits global options from the main citydb 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.
`--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.

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.

Note

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. Contributions are welcome.

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.

LinuxWindows CMD

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

citydb 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).

Note

Duplicates are identified by comparing the objectid column in the FEATURE 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 3DCityDB 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 3DCityDB 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:

LinuxWindows CMD

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

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

Note

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.

Note

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.

Tip

The index command allows you to manage indexes independently of the import operation, giving you greater control over index handling.

Computing extents¶

By default, citydb-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, citydb-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.

Tip

You can also recompute envelopes after import using database functions in the 3DCityDB 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 \((x', y', z')\):

\[ \begin{pmatrix} x' \\ y' \\ z' \end{pmatrix} = \begin{pmatrix} m_0 & m_1 & m_2 & m_3 \\ m_4 & m_5 & m_6 & m_7 \\ m_8 & m_9 & m_{10} & m_{11} \end{pmatrix} \cdot \begin{pmatrix} x \\ y \\ z \\ 1 \end{pmatrix} \]

The --transform option expects a comma-separated list of 12 matrix coefficients in row-major order, from \(m_0\) to \(m_{11}\):

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

A common use case is swapping the \(x\) and \(y\) coordinates while keeping \(z\) unchanged. You can use swap_xy as a shorthand for this transformation, as shown below.

LinuxWindows CMD

./citydb import citygml [...] my-city.gml \
    --transform=swap_xy

citydb import citygml [...] my-city.gml ^
    --transform=swap_xy

Note

Ensure that the transformed coordinates remain consistent with the CRS defined for your 3DCityDB 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 3DCityDB and is not part of the CityGML standard (see also here). If not provided, the username used to establish the 3DCityDB 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.

Note

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.

Import command¶

Synopsis¶

Options¶

Global options¶

General import options¶

Metadata options¶

Filter options¶

Commands¶

Usage¶

Specifying import files¶

Import modes and duplicate features¶

Previewing the import¶

Filtering features¶

Feature type filter¶

Feature identifier filter¶

Bounding box filter¶

Count filter¶

Filter example¶

Managing indexes during import¶

Computing extents¶

Transforming geometries¶

Defining import metadata¶

Controlling the import process¶