Import CityJSON Command

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

Synopsis

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

Options

The import cityjson command inherits global options from the main vcdb 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.

--quiet

Disable console log messages.

--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.

Filter options

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 VCDB is running.

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

Port of the VCDB server.

5432

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

Name of the VCDB database to connect to.

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

Schema to use when connecting to the VCDB.

citydb or username

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

Username to use when connecting to the VCDB.

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

Password to use when connecting to the VCDB. 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

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 vcdb-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.
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 VCDB v5, vcdb-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.

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