4.9.2. Import command¶
Synopsis
impexp import [-hV] [--ade-extensions=<folder>] [-c=<file>]
[--import-log=<file>] [--input-encoding=<encoding>]
[--log-file=<file>] [--log-level=<level>]
[--pid-file=<file>] [--plugins=<folder>]
[--worker-threads=<threads[,max]>]
[[--creation-date=<mode>] [--termination-date=<mode>]
[--lineage=<lineage>] [--updating-person=<name>]
[--reason-for-update=<reason>] [--use-metadata-from-file]]
[[[-t=<[prefix:]name>[,<[prefix:]name>...]]...
[--namespace=<prefix=name>[,<prefix=name>...]]...] [-i=<id>
[,<id>...] [-i=<id>[,<id>...]]...] [-b=<minx,miny,maxx,maxy
[,srid]> [--bbox-mode=<mode>]] [[--count=<count>]
[--start-index=<index>]] [[--no-appearance]]]
[[-T=<database>] -H=<host> [-P=<port>] -d=<name>
[-S=<schema>] -u=<name> [-p[=<password>]]]
[@<filename>...] <file>...
Description
The import
command imports one or more CityGML or CityJSON files
into the 3D City Database. It corresponds to the import operation
offered on the Import tab of the graphical user interface (see Section 4.4).
The command provides a range of options to adapt the import 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
-
<file>...
¶
One or more input files or directories to be imported. This parameter is mandatory. Glob patterns are supported to specify a set of filenames using wildcard characters (e.g.,
/path/to/*.gml
). If a directory is provided, it will be recursively scanned for CityGML/CityJSON files. The supported input file formats and extensions are identical with those listed in Table 4.7.
-
--input-encoding
=<encoding>
¶ Specify the encoding of the input file(s). For XML documents, the encoding is automatically parsed from the XML declaration at the beginning of the dataset if present. Provide an official IANA-based character encoding name. The default value is UTF-8.
-
--import-log
=<file>
¶ If you want an import log to be created for all top-level features loaded in the database, provide the path to the import log file with this option. More information about the import log can be found in Section 4.4.5.10.
-
--worker-threads
=<threads[,max]>
¶ Number of parallel threads to use for the import process. You can also specify a minimum and maximum number of threads separated by commas. A general description of the multithreaded processing used for the import process is provided in Section 4.4.5.11.
Metadata options
The import
command allows for specifying metadata that is assigned to every city object
during import and stored in columns of the table CITYOBJECT.
-
--creation-date
=<mode>
¶ Specifies how to set the creationDate attribute for city objects. Allowed values are
replace
(default),complement
andinherit
. If the creation date is not available from the city object during import, it may either be set to the import date (complement
) or be inherited from the parent object, if available (inherit
). Alternatively, the user can choose to replace all creation dates from the input files with the import date (replace
).
-
--termination-date
=<mode>
¶ Specifies how to set the terminationDate attribute for city objects. Allowed values are
replace
(default),complement
andinherit
. If the termination date is not available from the city object during import, it may either be set to NULL (complement
) or be inherited from the parent object, if available (inherit
). Alternatively, the user can choose to replace all termination dates in the input files with NULL (replace
).
-
--lineage
=<lineage>
¶ Value to store as lineage of the city objects.
-
--updating-person
=<name>
¶ Name of the user responsible for the import. By default, the name of the database user is chosen.
-
--reason-for-update
=<reason>
¶ Reason for importing the data.
-
--use-metadata-from-file
¶
Flag to indicate that values for lineage, updating person and reason for update stored for the city objects in the input file should take precedence over the values defined on the command line.
Import filter options
The import
command offers additional options to define both thematic and spatial filters
that are used to narrow down the set of top-level city objects to be imported from the
input file(s).
-
-t
,
--type-name
=<[prefix:]name>[,<[prefix:]name>...]
¶ Comma-separated list of one or more names of the top-level feature types to be imported. 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.10. 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
.
-
-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 imported.
-
-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 gml:boundedBy property (CityGML) respectively the “geographicalExtent” property (CityJSON) of the input features.
-
--bbox-mode
=<mode>
¶ Choose the mode of the bounding box filter. Allowed values are
overlaps
(default) andwithin
. When set tooverlaps
, all features overlapping with the bounding box are imported. Otherwise, features must bewithin
the given bounding box. Can only be used together with the--bbox
option.
-
--count
=<count>
¶ Maximum number of top-level features to be imported.
-
--start-index
=<index>
¶ Index within the set of all top-level features over all input file(s) from which the import shall begin. The start index uses zero-based numbering. Thus, the first top-level feature is assigned the index 0, rather than the index 1.
-
--no-appearance
¶
Flag to indicate that appearances of the features shall not be imported.
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.
-
-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 import -H localhost -d citydb_v4 -u citydb_user -p my_password my_city.gml
Import the dataset my_city.gml
into the 3DCityDB. The 3DCityDB is supposed
to be running on a PostgreSQL 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 import -H localhost -d citydb_v4 -p -u citydb_user \
-t Building,CityFurniture /path/to/**/*.json
The folder /path/to
is recursively scanned for files with the extension .json
.
From these files, only Building
and CityFurniture
features will be imported.
Note that the password option -p
is provided without a value and, thus,
the user will be prompted for the password.
$ impexp import -H localhost -d citydb_v4 -p -u citydb_user \
-b 13.3508824,52.4799281,13.3578297,52.4862805,4326 \
--bbox-mode=within my_city.gml
Import all city objects from the my_city.gml
file that are within
the provided
bounding box. The coordinates of the bounding box are given in WGS84. For
this reason, the fifth value 4326
of the -b
option denotes the SRID
that is used by the target database for the WGS84 reference system.
$ impexp import -T oracle -H localhost -S other_user -d citydb_v4 -p -u citydb_user \
--count=10 --start-index=20 /my/city/model/files/
Recursively scan the folder /my/city/model/files/
for all supported input files and import
them into a 3DCityDB running on Oracle. Only 10 features will be imported starting
from the 20th feature in the set. Note that the connection is established with the
user citydb_user
but the data will be imported into the schema of the user
other_user
. The citydb_user
must therefore have been granted sufficient privileges.