4.9.4. Visualization export command

Synopsis

impexp export-vis [-hjVz] [--ade-extensions=<folder>] [-c=<file>]
                  [--log-file=<file>] [--log-level=<level>] -o=<file>
                  [--pid-file=<file>] [--plugins=<folder>]
                  [--use-plugin=<plugin[=true|false]>[,<plugin
                  [=true|false]>...]]... [--worker-threads=<threads[,max]
                  >] [-D=<form[=pixels]>[,<form[=pixels]>...] [-D=<form
                  [=pixels]>[,<form[=pixels]>...]]... -l=<0..4 | halod>
                  [-a=<theme>]] [[[-t=<[prefix:]name>[,<[prefix:]
                  name>...]]... [--namespace=<prefix=name>[,
                  <prefix=name>...]]...] [[-r=<version>] [-R=<timestamp[,
                  timestamp]>]] [-i=<id>[,<id>...] [-i=<id>[,
                  <id>...]]...] [-b=<minx,miny,maxx,maxy[,srid]>]
                  [-g=<rows,columns | auto[=length]>] [-s=<select>]]
                  [[-B] [--no-surface-normals] [-C] [-f=<0..1>]
                  [-x=<mode>] [--no-pot-atlases]] [-G
                  [--gltf-version=<version>] [--gltf-converter=<file>]
                  [--gltf-embed-textures] [--gltf-binary]
                  [--gltf-draco-compression] [-m]] [[-A=<mode>]
                  [-O=<number|globe|generic>]
                  [--google-elevation-api=<api-key>]
                  [--transform-height]] [[-T=<database>] [-H=<host>]
                  [-P=<port>] [-d=<name>] [-S=<schema>] [-u=<name>] [-p
                  [=<password>]]] [@<filename>...]

Description

The export-vis command exports top-level city objects from the 3D City Database in KML/COLLADA/glTF format for visualization. It corresponds to the visualization export operation offered on the VIS Export tab of the graphical user interface (see Section 4.5). The command provides a range of options to adapt the export process. If you miss settings available for the GUI version of this command, you can use the --config option to pass a config file containing these settings.

General options

-o, --output=<file>

Specify the path where where the main KML output file should be saved.

-z, --kmz

Flag to indicate that KML/COLLADA output should be packaged into a KMZ archive per tile and display form (see Section 4.6.7.1 for more details). This option cannot be used with glTF exports.

-j, --json-metadata

Flag to indicate that metadata about the exported top-level features should be recorded in a separate JSON file. Further details are provided in Section 4.6.7.1.

--worker-threads=<threads[,max]>

Number of parallel threads to use for the visualization export process. You can also specify a minimum and maximum number of threads separated by commas.

Display options

-D, --display-form=<form[=pixels]>[,<form[=pixels]>...]

This option controls the display forms to be exported. The display forms are given as comma-separated list of one or more form[=pixels] pairs. Allowed values for the display form are collada, geometry, extruded, and footprint. For each display form, its visibility in terms of screen pixels can be optionally defined. If omitted, the display form will always be visible in the viewer. More information about display forms and their visibility can be found in Section 4.6.

-l, --lod=<0..4 | halod>

Define the LoD representation of the city objects that shall be used for creating the visualization models. The value must either be given as integer between 0 and 4 to export a specific LoD. Alternatively, you can set the value to halod in which case the highest available LoD representation will be chosen for each city object.

-a, --appearance-theme=<theme>

Appearance theme to use for texturing and coloring the exported city objects. Use none as value to address appearance features in the database lacking a theme attribute. This option is only considered for COLLADA/glTF exports.

Query and filter options

The export-vis command offers additional options to define both thematic and spatial filters that are used to restrict the visualization export to a subset of the top-level city objects stored in the 3D City Database.

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

Comma-separated list of one or more names of the top-level feature types to be exported. The type names are case sensitive and shall match one of the official CityGML feature type names or a feature type name from a CityGML ADE. To avoid ambiguities, you can use an optional prefix for each name. The prefix must be associated with the official XML namespace of the feature type. You can either use the official CityGML namespace prefixes listed in Table 4.11. Or you can use the --namespace option to declare your own prefixes.

--namespace=<prefix=name>[,<prefix=name>...]

Used to specify namespaces and their prefixes as comma-separated list of one or more prefix=name pairs. The prefixes can be used in other options such as --type-name.

-r, --feature-version=<version>

Specify the version of the top-level features to use for the visualization export. Allowed values are latest, at, between, terminated, terminated_at and all. When choosing latest, only those features that have not been terminated in the database are exported, whereas all will export all features. You can also choose to export only features that were valid at a given timestamp using at or for a given time range using between. Likewise, terminated will return all terminated features whereas terminated_at will select features that were terminated at a given timestamp. In all cases, timestamps must be provided using the --feature-version-timestamp option. Further details about the feature version filter are available in Section 4.6.1.

-R, --feature-version-timestamp=<timestamp[,timestamp]>

One or two timestamps to be used with the --feature-version option. A timestamp can be given as date in the form YYYY-MM-DD or as date-time specified as YYYY-MM-DDThh:mm:ss[(+|-)hh:mm. The date-time format supports an optional UTC offset. Use one timestamp with the at and terminated_at values and two timestamps separated by comma with the between value of the --feature-version option.

-i, --resource-id=<id>[,<id>...]

Comma-separated list of one or more identifiers. Only top-level features having a matching value for their identifier attribute will be exported.

-b, --bbox=<minx,miny,maxx,maxy[,srid]>

2D bounding box to use as spatial filter. The bounding box is given by four coordinates that define its lower left and upper right corner. By default, the coordinates are assumed to be in the same CRS that is used by the 3DCityDB instance. Alternatively, you can provide the database srid of the CRS associated with the coordinates as fifth value (e.g. 4326 for WGS84). All values must be separated by commas. The bounding box is evaluated against the GMLID column of the CITYOBJECT table.

-g, --tiling=<rows,columns | auto[=length]>

Use this option to enable tiling for the visualization export. The bounding box of the entire export area is split into a regular grid, and each grid cell is exported as separate tile. You can either define the number of rows and columns separated by a comma for the grid, or use auto[=length] as value. In the latter case, the bounding box will be automatically split into tiles having a size of the given length value. If length is omitted, a default side length of 125m is used. The bounding box used for tiling is either specified through the --bbox option or calculated automatically in case --bbox is not provided. More information about tiled exports is provided in Section 4.6.

-s, --sql-select=<select>

Provide an SQL SELECT statement to be used as SQL filter when querying the database. In general, any SELECT statement can be used as long as it returns a list of database IDs of the selected city objects (see Section 4.6.4 for more information). You can also use an @-file to provide the SELECT statement (see Section 4.9.9.3).

COLLADA/glTF rendering options

The following options are specific to COLLADA/glTF exports. They are ignored if the list of display forms given by the --display-form option does not contain the value collada.

-B, --double-sided

Flag to disable backface culling and rather force a viewer to render both sides of each polygons. Be aware that this might decrease the visualization performance.

--no-surface-normals

If this flag is set, surface normals of polygons are not stored in the output. When exporting textured models, surface normals often do not increase the visual quality and can be omitted.

-C, --crop-textures

Use this flag to let the export operation cut each texture image to the minimum size required for texturing the corresponding polygon. This option can help to avoid loading massive texture data into a viewer.

-f, --texture-scale-factor=<0..1>

Scale down texture images by the given factor. A value between 0 and 1 must be provided. The default value of 1 means no scaling.

-x, --texture-atlas=<mode>

Specify if and how texture atlases should be created for each top-level feature from the exported texture images. Allowed values are none, basic, tpim, and tpim_wo_rotation. By default, texture atlases are created for all visualization exports using the basic mode. Use none to disable the creation of texture atlases. The further values correspond to the names of the supported algorithms for creating texture atlases as described in Section 4.6.7.1.

--no-pot-atlases

By default, texture atlases are created with power-of-two (PoT) side lengths. Use this flag to disable the default behaviour.

glTF export options

The export-vis command supports exporting glTF models by converting the COLLADA output to glTF on the fly. This is achieved by using the open source COLLADA2glTF converter tool. The following options control the glTF export.

-G, --gltf

Set this flag on your command line to enable the glTF export. This requires that collada has been selected as display form with the --display-form option.

--gltf-version=<version>

Specify the glTF version to use for the export. Allowed values are 1.0 and 2.0 (default).

--gltf-converter=<file>

Provide the path to the executable of the COLLADA2glTF converter tool. By default, the COLLADA2glTF tool shipped with the Importer/Exporter is used in the conversion. Be careful when using a different version of the tool as this might result in unexpected behaviour. More information is provided in Section 4.6.7.1.

--gltf-embed-textures

By default, texture images are exported as separate files relative to the location of the glTF output. With this flag, texture images are rather embedded in the glTF files by encoding the texture data using a base 64 encoding.

--gltf-binary

Flag to indicate that the glTF output should be converted and compressed to binary glTF format.

--gltf-draco-compression

Flag to indicate that geometry data should be compressed using the Google Draco compression technology. Draco compression is only available for glTF version 2.0, so make sure the --gltf-version option is correctly set.

-m, --remove-collada

Use this flag to remove the COLLADA files after the conversion and only keep the glTF output as result.

Database connection options

The following options allow you to define the connection details that shall be used for establishing a connection to the 3D City Database. You can also use environment variables for this purpose (see Section 4.9.8).

-T, --db-type=<database>

Specify the database system used for running the 3DCityDB. Allowed values are postgresql for PostgreSQL/PostGIS databases (default), and oracle for Oracle Spatial/Locator databases.

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

Specify the host name of the machine on which the 3DCityDB database server is running.

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

Specify the TCP port on which the 3DCityDB database server is listening for connections. The default value is 5432 for PostgreSQL and 1521 for Oracle.

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

Specify the name of the 3DCityDB database to connect to. When connecting to an Oracle database, provide the database SID or service name as value.

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

Name of the database schema to use when connecting to the 3DCityDB. If not provided, the citydb schema is used for PostgreSQL by default, whereas the schema of the user specified by the option --db-username is used under Oracle.

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

Connect to the 3DCityDB database server as the user given by name.

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

Specify the password to use when connecting to the 3DCityDB database server. You can either provide the password as value for this option or leave the value empty to be prompted to enter the password on the console before connecting to the database. If you skip this option completely, the impexp tool will try to connect to the database without a password. If the database server requires password authentication and a password is not available by other means, the connection attempt will fail in this case.

Examples

$ impexp export-vis -T oracle -H localhost -d citydb_v4 -u citydb_user -p my_password \
                    -D collada -l 2 -a visual -o my_vis.kml

Export all city objects from the database as COLLADA in LoD2. The appearance theme visual is used for texturing/coloring the objects. The output is stored in the main KML file my_vis.kml that can be loaded with a viewer. The 3DCityDB to connect to is supposed to be running on an Oracle database on the same machine. The connection will be established to the citydb_v4 database with the user citydb_user and the password my_password.

$ impexp export-vis -H localhost -d citydb_v4 -u citydb_user -p my_password \
                    -D footprint=50,extruded=125,collada=200 -l halod \
                    -t Building -b 13.3508824,52.4799281,13.3578297,52.4862805,4326 \
                    -g 3,4 -o my_vis.kml

Export all Building features inside the given bounding box as footprint, extruded and collada models using their highest available LoD representation. Tiling is enabled for this export, and 3x4 tiles are created per display form. Each display form is assigned a different visibility value. A footprint tile will become visible in the viewer as soon as it occupies 50 square pixels of screen space. When zooming in, the viewer will switch to extruded and finally to collada as soon as their visibility value is reached.

$ impexp export-vis -H localhost -d citydb_v4 -u citydb_user -p my_password \
                    -D geometry -l 2 \
                    -t CityFurniture,Bridge -g auto \
                    -z -j -o my_vis.kml

Export all CityFurniture and Bridge objects as geometry from LoD2. Again, tiling is applied to the export. Since a --bbox option is not provided, the bounding box is automatically calculated from all features. This bounding box is then automatically tiled using a default side length of 125m per tile. Moreover, each tile file is compressed as ZIP archive and an additional JSON file containing metadata about all exported features is created.

$ impexp export-vis -H localhost -d citydb_v4 -u citydb_user -p my_password \
                    -D collada -l halod \
                    -i ID_0815,ID_0816 --double-sided \
                    -a visual -x tpim_wo_rotation -C \
                    -o my_vis.kml

Export the top-level city objects with the identifiers ID_0815 and ID_0816 as collada using their highest available LoD representation. Textures shall be exported from the appearance theme visual. The texture images are first cropped and then packaged into texture atlases using the tpim_wo_rotation algorithm. Moreover, backface culling is disabled for this export.

$ impexp export-vis -H localhost -d citydb_v4 -u citydb_user -p my_password \
                    -D collada -l 3 \
                    -s "select cityobject_id from cityobject_genericattrib \
                    where attrname='energy_level' and realval < 12" \
                    -G --gltf-binary --gltf-draco-compression -m
                    -o my_vis.kml

Export all city objects satisfying the given SQL SELECT statement as collada based on their LoD3 geometries. The models are converted to binary glTF format and Draco compression is applied to the geometries. The intermediate COLLADA output is removed for the final result.