Import CityJSON command¶

The import cityjson command imports one or more CityJSON files into the 3DCityDB v5.

Synopsis¶

citydb import cityjson [OPTIONS] <file>...

Options¶

The import cityjson command inherits global options from the main citydb command and general import, metadata, and filter options from its parent import command. Additionally, it provides CityJSON 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]> [,<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.

CityJSON import options¶

Option	Description	Default value
`--[no-]map-unknown-objects`	Map city objects from unsupported extensions onto generic city objects.	`true`
`--no-appearances`	Do not process appearances.
`-a`, `--appearance-theme=<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.

Option	Description	Default value
`-t`, `--type-name=<[prefix:]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 [,srid]>`	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>]`	Password to use when connecting to the 3DCityDB. Leave empty to be prompted.
`--db-property=<property=value> [,<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 cityjson), refer to the documentation for the import command here.

Supported CityJSON versions¶

The import cityjson command supports importing CityJSON files in versions 2.0, 1.1, and 1.0. In addition to regular CityJSON files, the CityJSON Text Sequence (CityJSONSeq) format is also supported. CityJSONSeq decomposes the CityJSON dataset into its 1st-level features, which are stored as separate JSON objects on individual lines, each delimited by newlines. This format enables efficient streaming of large CityJSON data.

The following file types and extensions are recognized by citydb-tool:

File type	File extensions
CityJSON file	`.json`, `.jsonl`
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.

Filtering CityJSON features¶

The import cityjson command inherits filtering options from the parent import command. In the context of CityJSON input files, the filters operate as follows:

Filter	Description
Feature identifier filter	Regular CityJSON files: Applies to the `key` in the `"CityObjects"` collection. CityJSONSeq files: Applies to the `"id"` property of `"CityJSONFeature"` objects.
Bounding box filter	Applies to the `"geographicalExtent"` property of input features.

Note

Filters are applied to the 1st-level city objects in the input file. Matching city objects are imported, including all their 2nd-level city objects. Filtering 2nd-level city objects is not supported.

Filtering appearances¶

By default, the import cityjson 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.

Handling unknown extensions¶

CityJSON provides a flexible extension mechanism similar to CityGML Application Domain Extensions (ADE). This mechanism allows the addition of new feature attributes and feature types not covered by the CityJSON specification. If a dataset contains extensions that are not registered in the 3DCityDB v5, citydb-tool handles them as follows:

Unknown attributes are mapped to generic attributes and stored in the database.
Unknown feature types are mapped to generic city objects in the database. This default behavior can be suppressed using the --no-map-unknown-objects option, which will prevent unknown feature types from being imported.

Tip

To import CityJSON extensions as defined, the corresponding type definitions have to be registered in the OBJECTCLASS and DATATYPE metadata tables of the 3DCityDB v5. Additionally, a corresponding extension module must be loaded for citydb-tool to correctly parse and import the extensions.