Export CityJSON command¶
The export cityjson command exports city model data from the 3DCityDB v5 to a CityJSON file.
Since CityJSON implements only a subset of the CityGML Conceptual Model,
some data may not be fully exportable.
Synopsis¶
Options¶
The export cityjson command inherits global options from the main citydb 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. | |
--pid-file=<file> |
Create a file containing the process ID. | |
--plugins=<dir> |
Load plugins from this directory. | |
--use-plugin=<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 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. | 3DCityDB 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 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> |
Names of the features to process. | |
-f, --filter=<cql2-text> |
Filter to apply when retrieving features. Use the extended CQL2 filtering language of the 3DCityDB. | |
--filter-crs=<crs> |
SRID or identifier of the CRS to use for geometries in the filter expression. | 3DCityDB CRS |
--sql-filter=<sql> |
SQL query expression to use as filter. | |
-s, --sort-by=<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> |
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> |
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 |
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 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 to use when connecting to the 3DCityDB. Leave empty to be prompted. | |
--db-property=<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 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.
Note
CityJSON 1.0 does not support CityJSONSeq or streaming.
Warning
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 3DCityDB 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.
Note
Replacing templates will increase the file size and eliminate the benefits of reusing them.
Suppressing material defaults¶
By default, citydb-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.
Note
The --pretty-print option cannot be used with streaming exports that use newline-delimited JSON.