Export CityGML Command

The export citygml command exports city model data from the VCDB v5 to a CityGML file.

Synopsis

vcdb export citygml [OPTIONS]

Options

The export citygml command inherits global options from the main vcdb command and general export, query and filter, and tiling options from its parent export command. Additionally, it provides CityGML format-specific export 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.

--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 export options

Option Description Default value

-o, --output=<file>

Name of the output file.

--output-encoding=<encoding>

Encoding to use for the output file.

--fail-fast

Fail fast on errors.

--temp-dir=<dir>

Store temporary files in this directory.

--threads=<threads>

Number of threads to use for parallel processing.

--crs=<crs>

SRID or identifier of the CRS to use for the coordinates of geometries.

VCDB CRS

--crs-name=<name>

Name of the CRS to use in the output file.

--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 export options and usage hints, see here.

CityGML export options

Option Description Default value

-v, --citygml-version=<version>

CityGML version: 3.0, 2.0, 1.0.

3.0

--[no-]pretty-print

Format and indent output file.

true

-x, --xsl-transform=<stylesheet>[,<stylesheet>…​]

Apply XSLT stylesheets to transform output.

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.

Query and filter options

Option Description Default value

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

Names of the features to process.

-f, --filter=<cql2-text>

Filter to apply when retrieving features. Use the extended CQL2 filtering language of the VCDB.

--filter-crs=<crs>

SRID or identifier of the CRS to use for geometries in the filter expression.

VCDB CRS

--sql-filter=<sql>

SQL query expression to use as filter.

-s, --sort-by=<property[+|-]>
[,<property[+|-]>…​]

Properties and sort orders for sorting features.

--limit=<count>

Maximum number of features to process.

--start-index=<index>

Index within the input set from which features are processed.

-l, --lod=<lod>[,<lod>…​]

Export geometries with a matching LoD.

--lod-mode=<mode>

LoD filter mode: or, and, minimum, maximum.

or

--lod-search-depth=<0..n|all>

Levels of sub-features to search for matching LoDs

0

--no-appearances

Do not process appearances.

-a, --appearance-theme=<theme>[,<theme>…​]

Process appearances with a matching theme. Use none for the null theme.

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

Time-based feature history options

Option Description Default value

-M, --validity=<mode>

Process features by validity: valid, invalid, all.

valid

-T, --validity-at=<time>

Check validity at a specific point in time. If provided, the time must be in <YYYY-MM-DD> or <YYYY-MM-DDThh:mm:ss[(+|-)hh:mm]> format.

--validity-reference=<source>

Validity time reference: database, real_world

database

--lenient-validity

Ignore incomplete validity intervals of features.

For more details on the time-based feature history options and usage hints, see here.

Tiling options

Option Description Default value

--tile-matrix=<columns,rows>

Export tiles in a columns x rows grid.

--tile-dimension=<width[unit],height[unit]>

Export tiles with specified width and height, aligned with the database CRS grid (default length unit of the CRS assumed).

--tile-extent=<x_min,y_min,x_max,y_max[,srid]>

Extent to use for tiling.

auto-computed

--tile-origin=<origin>

Tile indexes origin: top_left, bottom_left.

top_left

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

Database connection options

Option Description Default value

-H, --db-host=<host>

Name of the host on which the VCDB is running.

-P, --db-port=<port>

Port of the VCDB server.

5432

-d, --db-name=<database>

Name of the VCDB database to connect to.

-S, --db-schema=<schema>

Schema to use when connecting to the VCDB.

citydb or username

-u, --db-username=<user>

Username to use when connecting to the VCDB.

-p, --db-password
[=<password>]

Password to use when connecting to the VCDB. 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

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

Specifying the CityGML version

The export citygml command supports CityGML versions 3.0, 2.0, and 1.0 as output formats. Use the --citygml-version option to select a specific version for export (default: 3.0).

Upgrading CityGML 2.0 and 1.0

CityGML data can be exported from the VCDB 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 vcdb-tool applies automatic conversions where possible, certain scenarios require user input.

If either CityGML 2.0 or 1.0 is the primary format for your VCDB v5, the following upgrade options are available to resolve compatibility issues when exporting to CityGML 3.0:

  • --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.

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

Applying XSL transformations

XSLT stylesheets enable the on-the-fly transformation of database content before it is written to the CityGML output file. 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 output file. 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.

  • Linux

  • Windows CMD

./vcdb export citygml [...] -o my-city.gml \
    --xsl-transform=my-first-stylesheet.xsl,my-second-stylesheet.xsl
vcdb export citygml [...] -o my-city.gml ^
    --xsl-transform=my-first-stylesheet.xsl,my-second-stylesheet.xsl

  • To handle large output files, vcdb-tool chunks the export into top-level features, which are then written to the output file. 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.

Formatting the output

By default, the export citygml command uses pretty printing to format the GML/XML output. This approach enhances readability by adding line breaks and indentation to clearly represent the hierarchy and nesting of XML elements. In scenarios where human readability is less important, pretty printing can be disabled using the --no-pretty-print option. This reduces file size and optimizes storage and transfer efficiency.