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 and inherit. 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 and inherit. 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) and within. When set to overlaps, all features overlapping with the bounding box are imported. Otherwise, features must be within 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), 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 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.