Export CityJSON Command

The export cityjson command exports city model data from the VCDB v5 to a CityJSON file. Since CityJSON implements only a subset of the CityGML Conceptual Model, some data may not be fully exportable.

Synopsis

vcdb export cityjson [OPTIONS]

Options

The export cityjson command inherits global options from the main vcdb command and general export, query and filter, and tiling options from its parent export command. Additionally, it provides CityJSON format-specific export 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 export options

Option Description Default value

-o, --output=<file>

Name of the output file.

--output-encoding=<encoding>

Encoding to use for the output file.

--fail-fast

Fail fast on errors.

--temp-dir=<dir>

Store temporary files in this directory.

--threads=<threads>

Number of threads to use for parallel processing.

--crs=<crs>

SRID or identifier of the CRS to use for the coordinates of geometries.

VCDB CRS

--crs-name=<name>

Name of the CRS to use in the output file.

--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 export options and usage hints, see here.

CityJSON export options

Option Description Default value

-v, --cityjson-version=<version>

CityJSON version: 2.0, 1.1, 1.0.

2.0

--[no-]json-lines

Write output as CityJSON Text Sequence in JSON Lines format. This option requires CityJSON 1.1 or later.

true

--pretty-print

Format and indent output file.

--html-safe

Write JSON that is safe to embed into HTML.

--vertex-precision=<digits>

Number of decimal places to keep for geometry vertices.

3

--template-precision=<digits>

Number of decimal places to keep for template vertices.

3

--texture-vertex-precision=<digits>

Number of decimal places to keep for texture vertices.

7

--[no-]transform-coordinates

Transform coordinates to integer values when exporting in CityJSON 1.0.

true

--replace-templates

Replace template geometries with real coordinates.

--[no-]material-defaults

Use CityGML default values for material properties.

true

Upgrade options for CityGML 2.0 and 1.0

Option Description Default value

--use-lod4-as-lod3

Use LoD4 as LoD3, replacing an existing LoD3.

Query and filter options

Option Description Default value

-t, --type-name=<[prefix:]name>
[,<[prefix:]name>…​]

Names of the features to process.

-f, --filter=<cql2-text>

Filter to apply when retrieving features. Use the extended CQL2 filtering language of the VCDB.

--filter-crs=<crs>

SRID or identifier of the CRS to use for geometries in the filter expression.

VCDB CRS

--sql-filter=<sql>

SQL query expression to use as filter.

-s, --sort-by=<property[+|-]>
[,<property[+|-]>…​]

Properties and sort orders for sorting features.

--limit=<count>

Maximum number of features to process.

--start-index=<index>

Index within the input set from which features are processed.

-l, --lod=<lod>[,<lod>…​]

Export geometries with a matching LoD.

--lod-mode=<mode>

LoD filter mode: or, and, minimum, maximum.

or

--lod-search-depth=<0..n|all>

Levels of sub-features to search for matching LoDs

0

--no-appearances

Do not process appearances.

-a, --appearance-theme=<theme>[,<theme>…​]

Process appearances with a matching theme. Use none for the null theme.

For more details on the query and filter options and usage hints, see here.

Time-based feature history options

Option Description Default value

-M, --validity=<mode>

Process features by validity: valid, invalid, all.

valid

-T, --validity-at=<time>

Check validity at a specific point in time. If provided, the time must be in <YYYY-MM-DD> or <YYYY-MM-DDThh:mm:ss[(+|-)hh:mm]> format.

--validity-reference=<source>

Validity time reference: database, real_world

database

--lenient-validity

Ignore incomplete validity intervals of features.

For more details on the time-based feature history options and usage hints, see here.

Tiling options

Option Description Default value

--tile-matrix=<columns,rows>

Export tiles in a columns x rows grid.

--tile-dimension=<width[unit],height[unit]>

Export tiles with specified width and height, aligned with the database CRS grid (default length unit of the CRS assumed).

--tile-extent=<x_min,y_min,x_max,y_max[,srid]>

Extent to use for tiling.

auto-computed

--tile-origin=<origin>

Tile indexes origin: top_left, bottom_left.

top_left

For more details on the tiling 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 export command (including but not limited to export cityjson), refer to the documentation for the export command here.

Specifying the CityJSON version

The export cityjson command supports CityJSON versions 2.0, 1.1, and 1.0 as output formats. Use the --cityjson-version option to select a specific version for export (default: 2.0).

Streaming exports

When exporting to CityJSON 2.0 and 1.1, the default output format is CityJSON Text Sequence (CityJSONSeq), which efficiently supports streaming large exports. Features are exported in chunks as individual CityJSONFeature objects, with each object written to the output file on a separate line. This streaming approach improves memory efficiency, reduces storage requirements, and allows immediate access to the data as it is streamed.

If the newline-delimited CityJSONSeq format is not preferred, streaming can be disabled using the --no-json-lines option.

CityJSON 1.0 does not support CityJSONSeq or streaming.
Without streaming, the entire export must be loaded into memory before being written to the output file, which could quickly exceed system memory limits for large exports. In such cases, consider using filters or tiled exports to reduce the export size.

Upgrading CityGML 2.0 and 1.0

CityJSON does not support LoD4 representations of features as defined in CityGML 2.0 and 1.0. Therefore, if you have imported CityGML 2.0 or 1.0 data containing LoD4 geometries into your VCDB v5, these geometries will be skipped by default when exporting to CityJSON.

To address this, you can use the --use-lod4-as-lod3 option to map LoD4 geometries to LoD3 during export. However, this will also overwrite any existing LoD3 representation of the features.

Transforming coordinates

CityJSON applies quantization to the coordinates of the geometry vertices to reduce file size. The coordinates are represented as integer values, with the scale factor and translation required to recover the original coordinates stored as separate "transform" property.

Quantization is mandatory for CityJSON 2.0 and 1.1, but optional for CityJSON 1.0. By default, the export cityjson command uses quantization for CityJSON 1.0 as well, though it can be disabled using the --no-transform-coordinates option.

Replacing template geometries

CityJSON supports the CityGML concept of implicit geometries, enabling template geometries to be defined and stored once in a CityJSON file and reused by multiple features. These template geometries are stored using local coordinates. Features that reference a template must provide both a reference point and a transformation matrix to convert the coordinates to real-world values and place the template correctly within the city model.

If the target system consuming the CityJSON export cannot handle template geometries, the --replace-templates option can be used to replace them with real-world coordinates during export.

Replacing templates will increase the file size and eliminate the benefits of reusing them.

Suppressing material defaults

By default, vcdb-tool includes default values for material properties such as "diffuseColor", "emissiveColor", and "ambientIntensity" in the output file when specific values for these properties are missing in the database. These defaults are defined in the CityGML Appearance model and help prevent issues with target systems that do not automatically apply them.

You can use the --no-material-defaults option to suppress this behavior and omit the properties with default values, which also reduces the file size.

Formatting the output

The export cityjson command provides several options to format the CityJSON output:

  • --vertex-precision: Controls the number of decimal places retained for the coordinates of geometries. The coordinate values will be rounded to the specified number of decimal places (default: 3). This option balances data accuracy with file size. More decimal places increase precision but may result in a larger file size.

  • --template-precision: Similar to --vertex-precision, but affects the number of decimal places for the coordinates of implicit geometries (default: 3).

  • --texture-vertex-precision: Similar to --vertex-precision, but affects the number of decimal places for texture coordinates (default: 7).

  • --pretty-print: Enhances readability by adding line breaks and indentation to clearly represent the hierarchy and nesting of JSON elements, but increases file size.

  • --html-safe: Escapes special characters in the CityJSON output for safe use in HTML contexts.

The --pretty-print option cannot be used with streaming exports that use newline-delimited JSON.