AdV CityGML Export

The export citygml-adv command of the AdV plugin extends the export command of vcdb-tool and enables the AdV-compliant output of 3D building models from the VCDB v5. Compared to the existing CityGML export command, the export citygml-adv command applies strict filter criteria. As a result, only the feature types, attributes, and geometries permitted under the AdV CityGML 3.0 format are exported. Further requirements regarding metadata as well as decimal places for coordinates and measured values are also automatically taken into account.

The export command of the AdV plugin ensures the structural content of the output format. However, the data is not validated against the AdV PQS standard.

Synopsis

vcdb export citygml-adv [OPTIONS]

Options

The export citygml-adv command offers the same options as the export citygml command. The overview below is therefore provided mainly for completeness. Further settings can be defined via a JSON configuration file.

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

--extensions=<dir>

Load extensions 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.

For more details on the CityGML export 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.

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

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 the documentation of the individual options and general usage hints, see the documentation for the export citygml command here.

Feature and attribute filtering

The export citygml-adv command restricts the export to the feature types and attributes specified by the AdV PQS standard, as well as the predefined geometry representations and LoD levels. Additional feature types and attributes in the database that go beyond the requirements of the AdV PQS standard are generally not output. This ensures that every export produced with the AdV plugin conforms to the AdV CityGML 3.0 format.

The feature type filter via the --type-name option is therefore only usable to a limited extent, since only permitted feature types are accepted. For example, an AdV export can be restricted to bldg:Building or con:OtherConstruction objects via --type-name. Other CityGML feature types, such as veg:SolitaryVegetationObject, are not exported even if they are specified in the feature type filter, since they are not part of the AdV standard.

The LoD filter via the --lod option is likewise restricted to the AdV-compliant LoD levels.

For the output of attributes, the export citygml-adv command allows the following exceptions:

  • Attribute mapping: Existing attributes in the database can be mapped to an AdV-compliant attribute before output. This allows the content of other attributes to be used for an AdV-compliant export without having to rename these attributes in the database.

  • Attribute filter: Using the export citygml-adv command’s own attribute filters, you can specify that certain attributes are exported anyway or excluded from the export.

The attribute mapping and attribute filters are defined in the JSON configuration of the export citygml-adv command and are described in more detail here.

The use of attribute filters can cause the resulting output file to no longer comply with the requirements of the AdV CityGML 3.0 format and therefore no longer be AdV-compliant.
Within the scope of the AdV standard’s requirements, all filter options can be used. The documentation of the export command’s general query and filter options can be found here.

CityGML version

The AdV standard fixes the CityGML version of the output file to CityGML 3.0. Specifying a different target version via the --citygml-version option therefore always results in an error message and aborts the export process.

Decimal places

In accordance with the requirements of the AdV standard, the decimal places of coordinates and measured values, such as the building height (con:Height/con:value), are limited to three decimal places.

Adjustments to attribute values

For the following attributes, fixed requirements of the AdV standard apply during export, even if the database contains different values:

  • The con:highReference of the building height is set to topOfConstruction.

  • The con:lowReference of the building height is set to lowestGroundPoint.

  • The con:status of the building height is set depending on the generic attribute DatenquelleDachhoehe:

    • estimated: For a value of 3000.

    • measured: For all other values.

  • The con:value of the building height receives the value urn:adv:uom:m as its unit.

  • The core:informationSystem of external references is not output.

  • Date and time values are serialized without a time zone offset.

File metadata

For each output file, the export command sets the following metadata in the core:CityModel root element:

  • File name without file extension as gml:name.

  • Bounding box of the file as gml:Envelope. The bounding box is calculated across all objects in the file and therefore does not correspond merely to the tile boundaries of a tiled export.

  • Coordinate reference system (CRS) as the srsName attribute of the gml:Envelope element.

The identifier of the database CRS, which was specified when setting up the VCDB instance and is stored in the DATABASE_SRS table, is used to specify the CRS. If a different CRS identifier should be used for the export, it can be specified using the --crs-name option.

Tiled export

The tile and file name structure for exports from the VCDB v5 is not prescribed by the export citygml-adv command but can be freely chosen, as with a regular CityGML export. This allows both single files and tiled exports.

The options of the export citygml-adv command make it easy to implement the AdV requirements for tiled data delivery:

  • --tile-dimension: Sets the width and height of the resulting tiles. For an export with a tile grid of 1x1 km, the value must be set to 1000,1000 or 1km,1km. For the output of tiles measuring 2x2 km, the value must be set accordingly to 2000,2000 or 2km,2km.

  • --skip-empty-tiles: Can optionally be specified if empty tiles should be deleted automatically.

Furthermore, the file name of each tile file is expected to follow this format:

LoD<Level>_<UTM-Zone>_<East>_<North>_<edge length>_<state>.gml

The values for the placeholders <Level>, <UTM-Zone>, <edge length>, and <state> are identical for all tile files and can therefore be fixed in the file name. Only the <East> and <North> placeholders are dynamic and depend on the tile currently being processed. For this purpose, the export command of vcdb-tool already supports predefined placeholders in the file name, which are replaced by the corresponding tile values at runtime.

The following placeholders must be used for an AdV-compliant output:

AdV token Description vcdb-tool token

<East>

3-digit easting of the lower-left corner in kilometers.

@x_min,%3.3s@

<North>

4-digit northing of the lower-left corner in kilometers.

@y_min,%4.4s@
All options for tiled exports are described in detail in the export command of vcdb-tool.

Example

The following example shows how to invoke the export citygml-adv command for a tiled export of the German federal state of Schleswig-Holstein (SH) at LoD 2 and UTM zone 32, with a tile edge length of 2km. Empty tiles are to be removed automatically, and the CRS identifier in the output files is to be set to ETRS89_UTM32*DE_DHHN2016_NH.

  • Linux

  • Windows CMD

./vcdb export citygml-adv [...] \
    -H my_server -d my_database -u my_user -p my_password \
    --crs-name=ETRS89_UTM32*DE_DHHN2016_NH \
    --tile-dimension=2000,2000 \
    --skip-empty-tiles \
    -o /my/path/LoD2_32_@x_min,%3.3s@_@y_min,%4.4s@_2_SH.gml
vcdb export citygml-adv [...] ^
    -H my_server -d my_database -u my_user -p my_password ^
    --crs-name=ETRS89_UTM32*DE_DHHN2016_NH ^
    --tile-dimension=2000,2000 ^
    --skip-empty-tiles ^
    -o C:\my\path\LoD2_32_@x_min,%3.3s@_@y_min,%4.4s@_2_SH.gml