Import CityGML command¶

The import citygml command imports one or more CityGML files into the 3DCityDB v5.

Synopsis¶

citydb import citygml [OPTIONS] <file>...

Options¶

The import citygml command inherits global options from the main citydb command and general import and metadata options from its parent import command. Additionally, it provides CityGML format-specific import and filter options.

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.

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

CityGML import options¶

Option	Description	Default value
`--import-xal-source`	Import XML snippets of xAL address elements.
`-x`, `--xsl-transform=<stylesheet> [,<stylesheet>...]`	Apply XSLT stylesheets to transform input.

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.

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

Upgrade options for CityGML 2.0 and 1.0¶

Option	Description	Default value
`--use-lod4-as-lod3`	Use LoD4 as LoD3, replacing an existing LoD3.
`--map-lod0-roof-edge`	Map LoD0 roof edges onto roof surfaces.
`--map-lod1-surface`	Map LoD1 multi-surfaces onto generic thematic surfaces.

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.
`--no-appearances`	Do not process appearances.
`-a`, `--appearance-theme=<theme> [,<theme>...]`	Process appearances with a matching theme. Use `none` for the null theme.

Database connection options¶

Option	Description	Default value
`-H`, `--db-host=<host>`	Name of the host on which the 3DCityDB is running.
`-P`, `--db-port=<port>`	Port of the 3DCityDB server.	5432
`-d`, `--db-name=<database>`	Name of the 3DCityDB database to connect to.
`-S`, `--db-schema=<schema>`	Schema to use when connecting to the 3DCityDB	`citydb` or username
`-u`, `--db-username=<user>`	Username to use when connecting to the 3DCityDB.
`-p`, `--db-password [=<password>]`	Password to use when connecting to the 3DCityDB. Leave empty to be prompted.
`--db-property=<property=value> [,<property=value>...]`	Database-specific connection properties.

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

Usage¶

Tip

For general usage hints applicable to all subcommands of the import command (including but not limited to import citygml), refer to the documentation for the import command here.

Supported CityGML versions¶

The import citygml command supports importing CityGML files in versions 3.0, 2.0, and 1.0. It recognizes the following file types and extensions:

File type	File extensions
CityGML file	`.gml`, `.xml`
GZIP compressed file	`.gz`, `.gzip`
ZIP archive	`.zip`

The file extensions are used when a directory or ZIP archive is provided as <file> input instead of a single file. In such cases, the directory or archive is recursively scanned for input files, which are identified using the extensions listed above and then processed for import.

Upgrading CityGML 2.0 and 1.0¶

CityGML data can be exported from the 3DCityDB v5 in the same version as it was imported, without loss. However, switching CityGML versions between import and export may result in data loss, as CityGML 3.0 is not fully backward compatible with versions 2.0 and 1.0. While citydb-tool applies automatic conversions where possible, certain scenarios require user input.

If CityGML 3.0 is the primary format for your 3DCityDB v5 instance, the following upgrade options are available to resolve compatibility issues when importing CityGML 2.0 or 1.0 files:

--use-lod4-as-lod3: Converts LoD4 geometries to LoD3, replacing any existing LoD3.
--map-lod0-roof-edge: Converts LoD0 roof edge geometries into roof surface features.
--map-lod1-surface: Converts LoD1 multi-surfaces into generic thematic surface features.

Note

The upgrade options are not required if you only manage CityGML 2.0 and 1.0 data in your 3DCityDB v5. However, be cautious when importing CityGML 3.0 in this setup, as citydb-tool does not offer downgrade options. Any CityGML 3.0 content that cannot be automatically downgraded when exporting to CityGML 2.0 or 1.0 will be skipped. For more details, refer to the compatibility and data migration guide.

Filtering CityGML content¶

The import citygml command provides several filtering options to control which content is 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 gml:id value 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 bounding box filter is applied to the gml:boundedBy property of input features. 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.

Appearance filter¶

The --appearance-theme option filters appearances based on their <theme>. You can specify one or more themes as a comma-separated list. To filter appearances that have no theme property, use none as the value. Only appearances associated with the specified themes will be imported. To exclude all appearances from the import, use the --no-appearances option.

Filter example¶

The following example illustrates an import citygml 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.
Filters are applied to the top-level <cityObjectMember> elements in the input file. Matching features are imported, including all their subfeatures. Filtering subfeatures is not supported.
Configuration and argument files are an excellent way to store complex filter expressions and easily reuse them.

Applying XSL transformations¶

XSLT stylesheets enable the on-the-fly transformation of CityGML input data before it is imported into the database. This allows you to modify or restructure the data to meet specific needs, such as changing values, filtering attributes, or removing and replacing entire GML/XML structures.

The --xsl-transform option specifies one or more XSLT stylesheets to be applied to the input files. Each stylesheet must be referenced by its filename and path, which can be either absolute or relative to the current directory. Multiple XSLT stylesheets can be listed, separated by commas, to facilitate a multi-step transformation process. In this case, the stylesheets are executed in the specified order, with the output of one stylesheet serving as the input for the next.

LinuxWindows CMD

./citydb import citygml [...] my-city.gml \
    --xsl-transform=my-first-stylesheet.xsl,my-second-stylesheet.xsl

citydb import citygml [...] my-city.gml ^
    --xsl-transform=my-first-stylesheet.xsl,my-second-stylesheet.xsl

Note

To handle large input files, citydb-tool chunks each CityGML file into top-level features, which are then imported into the database. As a result, each XSLT stylesheet operates on individual top-level features, not the entire file. Keep this in mind when developing your XSLT.
The output of each XSLT stylesheet must be valid CityGML.

Storing xAL address elements¶

CityGML uses the OASIS Extensible Address Language (xAL) standard to encode address data. During import, citydb-tool parses the xAL content and maps it to the separate columns of the ADDRESS table, which provides a comprehensive and flexible structure for storing address data. However, if the original xAL address element is too complex to be fully mapped to the ADDRESS table columns, the --import-xal-source option allows importing and retaining the original xAL element. For more details, see here.

Import CityGML command¶

Synopsis¶

Options¶

Global options¶

General import options¶

CityGML import options¶

Metadata options¶

Upgrade options for CityGML 2.0 and 1.0¶

Filter options¶

Database connection options¶

Usage¶

Supported CityGML versions¶

Upgrading CityGML 2.0 and 1.0¶

Filtering CityGML content¶

Feature type filter¶

Feature identifier filter¶

Bounding box filter¶

Count filter¶

Appearance filter¶

Filter example¶

Applying XSL transformations¶

Storing xAL address elements¶