AdV CityGML Import

The AdV plugin extends the import command of vcdb-tool with the citygml-adv subcommand. It allows datasets in the AdV CityGML 1.0 format to be imported into the VCDB v5. Compared to the existing CityGML import command, import citygml-adv automatically converts the input data into the AdV CityGML 3.0 format. This particularly concerns the conversion of building models into bridges or other constructions based on predefined values of the bldg:function attribute.

The input data for the import citygml-adv command should conform to the AdV PQS standard in version 2.6. However, this is not mandatory. The import citygml-adv command also supports CityGML data that, for example, contains feature types, LoD levels, or attributes that go beyond the AdV specification, or that is provided in other CityGML versions.

Synopsis

vcdb import citygml-adv [OPTIONS] <file>...

Options

The import citygml-adv command offers the same options as the import 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 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.

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

Metadata options

Option Description Default value

--creation-date=<time>

Time in <YYYY-MM-DD> or <YYYY-MM-DDThh:mm:ss[(+|-)hh:mm]> format or now to use as creation date.

attribute value or now

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

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

Filter options

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.

For more details on the filter 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 import citygml command here.

Unlike the regular CityGML import command, import citygml-adv converts building models into a different CityGML feature type during import into the database if required by the AdV PQS standard v3.0. To do this, every top-level object of type bldg:Building in the input data is examined and the associated function code is read from the bldg:function attribute.

The function code is used to determine whether a conversion into a different feature type is required. The check is performed in the following order:

  1. Conversion into a bridge (brid:Bridge)

  2. Conversion into an other construction (con:OtherConstruction)

  3. Retention of the object as bldg:Building (default behavior)

Which function codes trigger the conversion of a building into brid:Bridge or con:OtherConstruction is defined according to the AdV PQS standard. However, the list of function codes can be customized per feature type using the JSON configuration.

Depending on the target feature type, different conversion steps are carried out, which are described in the following sections.

Retaining buildings

Conversion of feature types

When retaining a building, the feature types are reclassified for AdV CityGML 3.0 as follows:

Source object Target object

bldg:Building

bldg:Building

bldg:BuildingPart

bldg:BuildingPart

bldg:WallSurface

con:WallSurface

bldg:RoofSurface

con:RoofSurface

bldg:GroundSurface

con:GroundSurface

bldg:ClosureSurface

core:ClosureSurface

Conversion of attributes

The following rules apply to the conversion of attributes:

  • Generic attributes are generally retained. The attribute values are not validated.

  • The following generic attributes are stored on the bldg:BuildingPart in AdV CityGML 1.0 and must be merged onto the bldg:Building for conversion to AdV CityGML 3.0. In case of conflicting attribute values, the following rules apply:

    • DatenquelleBodenhoehe: The first value is retained.

    • DatenquelleLage: The first value is retained.

    • Grundrissaktualitaet: The oldest date is retained.

  • The generic attribute LetzteAenderung is mandatory for bldg:Building objects. If it is not set for the input object, it is added and populated with the value of core:creationDate. If that is also not present, the current date is used.

  • For core:ExternalReference, the core:informationSystem attribute is removed.

  • bldg:measuredHeight attributes are rewritten as con:Height. The status attribute is set depending on the generic attribute DatenquelleDachhoehe as follows:

    • estimated: For a value of 3000.

    • measured: For all other values.

  • Addresses of the building are retained.

Retaining geometries

All geometries of the building object and its child objects are retained unchanged. This applies to all geometry types, such as gml:Solid and gml:MultiSurface, as well as gml:MultiCurve geometries of terrain intersection curves. Geometry validation is not performed.

Conversion into bridges

Conversion of feature types

When converting a building into a bridge, the building and its child objects are reclassified as follows:

Source object Target object

bldg:Building

brid:Bridge

bldg:BuildingPart

brid:BridgePart

bldg:WallSurface

con:WallSurface

bldg:RoofSurface

con:OuterFloorSurface

bldg:GroundSurface

con:OuterCeilingSurface

bldg:ClosureSurface

core:ClosureSurface

Conversion of attributes

The following rules apply to the conversion of attributes:

  • Building-specific attributes from the bldg namespace are retained, provided a corresponding attribute exists for the bridge object.

  • Generic attributes are generally retained. The attribute values are not validated.

  • The following generic attributes are stored on the bldg:BuildingPart in AdV CityGML 1.0 and must be merged onto the brid:Bridge for conversion to AdV CityGML 3.0. In case of conflicting attribute values, the following rules apply:

    • DatenquelleBodenhoehe: The first value is retained.

    • DatenquelleLage: The first value is retained.

    • Grundrissaktualitaet: The oldest date is retained.

  • The following generic attributes are not intended for bridges and are removed:

    • BezugspunktDach

    • DatenquelleGeschossanzahl

  • The generic attribute LetzteAenderung is mandatory for brid:Bridge objects. If it is not set for the bldg:Building, it is added and populated with the value of core:creationDate. If that is also not present, the current date is used.

  • Depending on the function code, brid:isMovable is set to true or false.

  • For core:ExternalReference, the core:informationSystem attribute is removed.

  • bldg:measuredHeight attributes are rewritten as con:Height. The status attribute is set depending on the generic attribute DatenquelleDachhoehe as follows:

    • estimated: For a value of 3000.

    • measured: For all other values.

  • Addresses of the building are retained for the bridge.

Retaining geometries

All geometries of the building object and its child objects are retained unchanged in the corresponding bridge objects. This applies to all geometry types, such as gml:Solid and gml:MultiSurface, as well as gml:MultiCurve geometries of terrain intersection curves. Geometry validation is not performed.

Conversion into other constructions

Conversion of feature types

When converting a building into an other construction, the building and its child objects are reclassified as follows:

Source object Target object

bldg:Building

con:OtherConstruction

bldg:BuildingPart

merged into con:OtherConstruction

bldg:WallSurface

con:WallSurface

bldg:RoofSurface

con:RoofSurface

bldg:GroundSurface

con:GroundSurface

bldg:ClosureSurface

-
Unlike bldg:Building, con:OtherConstruction does not allow further subdivision into construction parts. Building parts therefore cannot be retained as such but are merged into the con:OtherConstruction object. For this purpose, boundary surfaces of the bldg:BuildingPart objects are transferred into the con:OtherConstruction object.

Conversion of attributes

The following rules apply to the conversion of attributes:

  • Building-specific attributes from the bldg namespace are retained, provided a corresponding attribute exists for con:OtherConstruction.

  • Generic attributes are generally retained. The attribute values are not validated.

  • The following generic attributes are stored on the bldg:BuildingPart in AdV CityGML 1.0 and are merged for the conversion to con:OtherConstruction. In case of conflicting attribute values, the following rules apply:

    • DatenquelleDachhoehe: The first value is retained.

    • BezugspunktDach: The first value is retained.

    • DatenquelleBodenhoehe: The first value is retained.

    • DatenquelleLage: The first value is retained.

    • Grundrissaktualitaet: The oldest date is retained.

  • The following generic attributes are not intended for other constructions and are removed:

    • DatenquelleGeschossanzahl

  • The generic attribute LetzteAenderung is mandatory for con:OtherConstruction objects. If it is not set for the bldg:Building, it is added and populated with the value of core:creationDate. If that is also not present, the current date is used.

  • For core:ExternalReference, the core:informationSystem attribute is removed.

  • bldg:measuredHeight attributes are rewritten as con:Height. The status attribute is set depending on the generic attribute DatenquelleDachhoehe as follows:

    • estimated: For a value of 3000.

    • measured: For all other values.

  • When merging building parts, the largest existing part height is used as the height of the construction.

  • Addresses of the building are not retained for con:OtherConstruction.

Retaining geometries

The geometries of the building object are generally retained unchanged in con:OtherConstruction. This applies to all geometry types, such as gml:Solid and gml:MultiSurface, as well as gml:MultiCurve geometries of terrain intersection curves. Geometry validation is not performed.

If building parts are modeled, an additional conversion is required at the geometry level. The following rules apply to merging the geometries in the con:OtherConstruction object:

  • Boundary surfaces of type bldg:WallSurface, bldg:RoofSurface, and bldg:GroundSurface, including their geometry, are transferred into con:OtherConstruction.

  • The polygons of the transferred boundary surfaces are included as references in the LoD2 Solid geometry of the con:OtherConstruction.

  • Boundary surfaces of type bldg:ClosureSurface serve exclusively as a separating surface between two bldg:BuildingPart objects. They are therefore removed entirely, including their geometry.

  • The LoD1 Solid geometries of the building parts are merged into a single LoD1 Solid geometry for the con:OtherConstruction.

  • Geometries of the terrain intersection curves of the building parts are merged into a single gml:MultiCurve geometry as the terrain intersection curve of the con:OtherConstruction, separately for LoD2 and LoD1.

With valid input data, the merged geometries remain valid at LoD2 and LoD1. Only in the LoD1 Solid geometry can duplicate polygons arise at the contact surfaces of the original building parts, which can render the solid geometry invalid.

Logging

After a successful import, the AdV plugin writes the number of building objects that were converted into bridges or other constructions as a summary to the vcdb-tool log output. If no conversions took place, this is also logged.

If --log-level is set to debug, a log entry with the function code that triggered the conversion is additionally written for each converted building.

The log output of the AdV plugin contains the [AdV] marker, making it easy to search and filter.