Export CityGML command¶

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

Synopsis¶

citydb export citygml [OPTIONS]

Options¶

The export citygml command inherits global options from the main citydb 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.
`--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 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.	3DCityDB 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.

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 3DCityDB.
`--filter-crs=<crs>`	SRID or identifier of the CRS to use for geometries in the filter expression.	3DCityDB 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 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 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 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 either CityGML 2.0 or 1.0 is the primary format for your 3DCityDB 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.

Note

The upgrade options are not required if you only manage CityGML 3.0 data in your 3DCityDB v5. However, be cautious when exporting to CityGML 2.0 or 1.0 in this setup, as citydb-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.

LinuxWindows CMD

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

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