Import CityGML command¶
The import citygml command imports one or more CityGML files
into the 3DCityDB v5.
Synopsis¶
Options¶
The import citygml command inherits global options from the main citydb command and general import,
metadata, and filter options from its parent import command. Additionally, it provides CityGML
format-specific import 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]> |
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> |
Apply XSLT stylesheets to transform input. | |
--no-appearances |
Do not process appearances. | |
-a, --appearance-theme=<theme> |
Process appearances with a matching theme. Use none for the null theme. |
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. |
Filter options¶
| Option | Description | Default value |
|---|---|---|
-t, --type-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 |
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 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 to use when connecting to the 3DCityDB. Leave empty to be prompted. | |
--db-property=<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 features¶
The import citygml command inherits filtering options from the parent import
command. In the context of CityGML input files, the filters operate as follows:
| Filter | Description |
|---|---|
| Feature identifier filter | Applies to the gml:id property of input features. |
| Bounding box filter | Applies to the gml:boundedBy property of input features. |
Note
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.
Filtering appearances¶
By default, the import citygml command imports all appearance information from the input files. The
--appearance-theme option restricts the import of appearances based on their <theme> property. 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.
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.
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.