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 arecollada
,geometry
,extruded
, andfootprint
. 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
and4
to export a specific LoD. Alternatively, you can set the value tohalod
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
andall
. When choosinglatest
, only those features that have not been terminated in the database are exported, whereasall
will export all features. You can also choose to export only features that were valid at a given timestamp usingat
or for a given time range usingbetween
. Likewise,terminated
will return all terminated features whereasterminated_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 formYYYY-MM-DD
or as date-time specified asYYYY-MM-DDThh:mm:ss[(+|-)hh:mm
. The date-time format supports an optional UTC offset. Use one timestamp with theat
andterminated_at
values and two timestamps separated by comma with thebetween
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
andcolumns
separated by a comma for the grid, or useauto[=length]
as value. In the latter case, the bounding box will be automatically split into tiles having a size of the givenlength
value. Iflength
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
and1
must be provided. The default value of1
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
, andtpim_wo_rotation
. By default, texture atlases are created for all visualization exports using thebasic
mode. Usenone
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
and2.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), andoracle
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 and1521
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.