"terminateWithSub
Features"
](delete.md#delete-mode) | Also terminate sub-features. | `true` |
37 | | [`"terminationDate"`](delete.md#defining-termination-metadata) | Time in `<YYYY-MM-DDThh:mm:ss[(+|-)hh:mm]>
format to use as termination date. | `now` |
38 | | [`"lineage"`](delete.md#defining-termination-metadata) | Lineage to use for the features. | |
39 | | [`"updatingPerson"`](delete.md#defining-termination-metadata) | Name of the user responsible for the delete | database user |
40 | | [`"reasonForUpdate"`](delete.md#defining-termination-metadata) | Reason for importing the data. | |
41 |
42 | ## Query options
43 |
44 | The `"query"` property is a container object for the following query and filtering options.
45 |
46 | ```json
47 | {
48 | "query": {
49 | "featureTypes": [ // (1)!
50 | {
51 | "name": "bldg:Building"
52 | },
53 | {
54 | "name": "Road",
55 | "namespace": "http://3dcitydb.org/3dcitydb/transportation/5.0"
56 | }
57 | ],
58 | "filter": {
59 | "op": "s_intersects",
60 | "args": [
61 | {
62 | "property": "core:envelope"
63 | },
64 | {
65 | "bbox": [10.0,10.0,20.0,20.0]
66 | }
67 | ]
68 | },
69 | "filterSrs": { // (2)!
70 | "srid": 4326,
71 | "identifier": "http://www.opengis.net/def/crs/EPSG/0/4326"
72 | },
73 | "countLimit": {
74 | "limit": 1000,
75 | "startIndex": 20
76 | }
77 | }
78 | }
79 | ```
80 |
81 | 1. The `"name"` property is mandatory. To avoid ambiguity, use the format `"prefix:name"` with a namespace alias as prefix or
82 | specify the full namespace using the `"namespace"` property.
83 | 2. Use either `"srid"`, `"identifier"`, or both to define the target CRS.
84 |
85 | | <YYYY-MM-DDThh:mm:ss[(+|-)hh:mm]>
format. | |
111 | | [`"reference"`](delete.md#deleting-historical-versions) | Validity time reference: `database`, `realWorld`. | `database` |
112 | | [`"lenient"`](delete.md#deleting-historical-versions) | Ignore incomplete validity intervals of features. | `false` |
113 |
--------------------------------------------------------------------------------
/docs/citydb-tool/export-citygml.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Export CityGML command
3 | description: Exporting CityGML data
4 | tags:
5 | - citydb-tool
6 | - CityGML
7 | - export
8 | ---
9 |
10 | # Export CityGML command
11 |
12 | The `export citygml` command exports city model data from the 3DCityDB `v5` to a [CityGML file](https://www.ogc.org/publications/standard/citygml/).
13 |
14 | ## Synopsis
15 |
16 | ```bash
17 | citydb export citygml [OPTIONS]
18 | ```
19 |
20 | ## Options
21 |
22 | The `export citygml` command inherits global options from the main [`citydb`](cli.md) command and general export, query
23 | and filter, and tiling options from its parent [`export`](export.md) command. Additionally, it provides CityGML
24 | format-specific export options.
25 |
26 | ### Global options
27 |
28 | --8<-- "docs/citydb-tool/includes/global-options.md"
29 |
30 | For more details on the global options and usage hints, see [here](cli.md#options).
31 |
32 | ### General export options
33 |
34 | --8<-- "docs/citydb-tool/includes/export-general-options.md"
35 |
36 | For more details on the general export options and usage hints, see [here](export.md#general-export-options).
37 |
38 | ### CityGML export options
39 |
40 | | Option | Description | Default value |
41 | |------------------------------------------------------------------------------|---------------------------------------------|---------------|
42 | | `-v`, `--citygml-version=--xsl-transform=<stylesheet>
[,<stylesheet>...]
| Apply XSLT stylesheets to transform output. | |
45 |
46 | ### Upgrade options for CityGML 2.0 and 1.0
47 |
48 | | Option | Description | Default value |
49 | |------------------------|---------------------------------------------------------|---------------|
50 | | `--use-lod4-as-lod3` | Use LoD4 as LoD3, replacing an existing LoD3. | |
51 | | `--map-lod0-roof-edge` | Map LoD0 roof edges onto roof surfaces. | |
52 | | `--map-lod1-surface` | Map LoD1 multi-surfaces onto generic thematic surfaces. | |
53 |
54 | ### Query and filter options
55 |
56 | --8<-- "docs/citydb-tool/includes/export-filter-options.md"
57 |
58 | For more details on the query and filter options and usage hints, see [here](export.md#query-and-filter-options).
59 |
60 | ### Time-based feature history options
61 |
62 | --8<-- "docs/citydb-tool/includes/export-history-options.md"
63 |
64 | For more details on the time-based feature history options and usage hints, see [here](export.md#time-based-feature-history-options).
65 |
66 | ### Tiling options
67 |
68 | --8<-- "docs/citydb-tool/includes/export-tiling-options.md"
69 |
70 | For more details on the tiling options and usage hints, see [here](export.md#tiling-options).
71 |
72 | ### Database connection options
73 |
74 | --8<-- "docs/citydb-tool/includes/db-options.md"
75 |
76 | For more details on the database connection options and usage hints, see [here](database.md#using-command-line-options).
77 |
78 | ## Usage
79 |
80 | !!! tip
81 | For general usage hints applicable to all subcommands of the `export` command (including but not limited to
82 | `export citygml`), refer to the documentation for the `export` command [here](export.md#usage).
83 |
84 | ### Specifying the CityGML version
85 |
86 | The `export citygml` command supports CityGML versions 3.0, 2.0, and 1.0 as output formats. Use the `--citygml-version`
87 | option to select a specific version for export (default: `3.0`).
88 |
89 | ### Upgrading CityGML 2.0 and 1.0
90 |
91 | CityGML data can be exported from the 3DCityDB `v5` in the same version as it was imported, without loss. However,
92 | switching CityGML versions between import and export may result in data loss, as CityGML 3.0 is not fully backward
93 | compatible with versions 2.0 and 1.0. While citydb-tool applies automatic conversions where possible, certain
94 | scenarios require user input.
95 |
96 | If either CityGML 2.0 or 1.0 is the primary format for your 3DCityDB `v5`, the following upgrade options are
97 | available to resolve compatibility issues when exporting to CityGML 3.0:
98 |
99 | - `--use-lod4-as-lod3`: Converts LoD4 geometries to LoD3, replacing any existing LoD3.
100 | - `--map-lod0-roof-edge`: Converts LoD0 roof edge geometries into roof surface features.
101 | - `--map-lod1-surface`: Converts LoD1 multi-surfaces into generic thematic surface features.
102 |
103 | !!! note
104 | The upgrade options are not required if you only manage CityGML 3.0 data in your 3DCityDB `v5`. However,
105 | be cautious when exporting to CityGML 2.0 or 1.0 in this setup, as citydb-tool does not offer downgrade options. Any
106 | CityGML 3.0 content that cannot be automatically downgraded during export will be skipped. For more details, refer to
107 | the [compatibility and data migration](../compatibility.md) guide.
108 |
109 | ### Applying XSL transformations
110 |
111 | XSLT stylesheets enable the on-the-fly transformation of database content before it is written to the CityGML output file.
112 | This allows you to modify or restructure the data to meet specific needs, such as changing values, filtering attributes,
113 | or removing and replacing entire GML/XML structures.
114 |
115 | The `--xsl-transform` option specifies one or more XSLT stylesheets to be applied to the output file. Each stylesheet must
116 | be referenced by its filename and path, which can be either absolute or relative to the current directory. Multiple XSLT
117 | stylesheets can be listed, separated by commas, to facilitate a multi-step transformation process. In this case, the
118 | stylesheets are executed in the specified order, with the output of one stylesheet serving as the input for the next.
119 |
120 | === "Linux"
121 |
122 | ```bash
123 | ./citydb export citygml [...] -o my-city.gml \
124 | --xsl-transform=my-first-stylesheet.xsl,my-second-stylesheet.xsl
125 | ```
126 |
127 | === "Windows CMD"
128 |
129 | ```bat
130 | citydb export citygml [...] -o my-city.gml ^
131 | --xsl-transform=my-first-stylesheet.xsl,my-second-stylesheet.xsl
132 | ```
133 |
134 | !!! note
135 | - To handle large output files, citydb-tool chunks the export into top-level features, which are then written
136 | to the output file. As a result, each XSLT stylesheet operates on individual top-level features, not the entire file.
137 | Keep this in mind when developing your XSLT.
138 | - The output of each XSLT stylesheet must be valid CityGML.
139 |
140 | ### Formatting the output
141 |
142 | By default, the `export citygml` command uses pretty printing to format the GML/XML output. This approach enhances
143 | readability by adding line breaks and indentation to clearly represent the hierarchy and nesting of XML elements. In
144 | scenarios where human readability is less important, pretty printing can be disabled using the `--no-pretty-print` option.
145 | This reduces file size and optimizes storage and transfer efficiency.
--------------------------------------------------------------------------------
/docs/citydb-tool/export-cityjson.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: Export CityJSON command
3 | description: Exporting CityJSON data
4 | tags:
5 | - citydb-tool
6 | - CityJSON
7 | - export
8 | ---
9 |
10 | # Export CityJSON command
11 |
12 | The `export cityjson` command exports city model data from the 3DCityDB `v5` to a [CityJSON file](https://www.cityjson.org/).
13 | Since CityJSON implements only a subset of the [CityGML Conceptual Model](https://docs.ogc.org/is/20-010/20-010.html),
14 | some data may not be fully exportable.
15 |
16 | ## Synopsis
17 |
18 | ```bash
19 | citydb export cityjson [OPTIONS]
20 | ```
21 |
22 | ## Options
23 |
24 | The `export cityjson` command inherits global options from the main [`citydb`](cli.md) command and general export, query
25 | and filter, and tiling options from its parent [`export`](export.md) command. Additionally, it provides CityJSON
26 | format-specific export options.
27 |
28 | ### Global options
29 |
30 | --8<-- "docs/citydb-tool/includes/global-options.md"
31 |
32 | For more details on the global options and usage hints, see [here](cli.md#options).
33 |
34 | ### General export options
35 |
36 | --8<-- "docs/citydb-tool/includes/export-general-options.md"
37 |
38 | For more details on the general export options and usage hints, see [here](export.md#general-export-options).
39 |
40 | ### CityJSON export options
41 |
42 | | Option | Description | Default value |
43 | |---------------------------------------|----------------------------------------------------------------------------------------------------------|---------------|
44 | | `-v`, `--cityjson-version=--xsl-transform=<stylesheet>
[,<stylesheet>...]
| Apply XSLT stylesheets to transform input. | |
45 | | `--no-appearances` | Do not process appearances. | |
46 | | `-a`, --appearance-theme=<theme>
[,<theme>...]
| Process appearances with a matching theme. Use `none` for the null theme. | |
47 |
48 | ### Metadata options
49 |
50 | --8<-- "docs/citydb-tool/includes/import-metadata-options.md"
51 |
52 | For more details on the metadata options and usage hints, see [here](import.md#metadata-options).
53 |
54 | ### Upgrade options for CityGML 2.0 and 1.0
55 |
56 | | Option | Description | Default value |
57 | |------------------------|---------------------------------------------------------|---------------|
58 | | `--use-lod4-as-lod3` | Use LoD4 as LoD3, replacing an existing LoD3. | |
59 | | `--map-lod0-roof-edge` | Map LoD0 roof edges onto roof surfaces. | |
60 | | `--map-lod1-surface` | Map LoD1 multi-surfaces onto generic thematic surfaces. | |
61 |
62 | ### Filter options
63 |
64 | --8<-- "docs/citydb-tool/includes/import-filter-options.md"
65 |
66 | For more details on the filter options and usage hints, see [here](import.md#filter-options).
67 |
68 | ### Database connection options
69 |
70 | --8<-- "docs/citydb-tool/includes/db-options.md"
71 |
72 | For more details on the database connection options and usage hints, see [here](database.md#using-command-line-options).
73 |
74 | ## Usage
75 |
76 | !!! tip
77 | For general usage hints applicable to all subcommands of the `import` command (including but not limited to
78 | `import citygml`), refer to the documentation for the `import` command [here](import.md#usage).
79 |
80 | ### Supported CityGML versions
81 |
82 | The `import citygml` command supports importing CityGML files in versions 3.0, 2.0, and 1.0. It recognizes the following
83 | file types and extensions:
84 |
85 | | File type | File extensions |
86 | |----------------------|-----------------|
87 | | CityGML file | `.gml`, `.xml` |
88 | | GZIP compressed file | `.gz`, `.gzip` |
89 | | ZIP archive | `.zip` |
90 |
91 | The file extensions are used when a directory or ZIP archive is provided as `--appearance-theme=<theme>
[,<theme>...]
| Process appearances with a matching theme. Use `none` for the null theme. | |
45 |
46 | ### Metadata options
47 |
48 | --8<-- "docs/citydb-tool/includes/import-metadata-options.md"
49 |
50 | For more details on the metadata options and usage hints, see [here](import.md#metadata-options).
51 |
52 | ### Filter options
53 |
54 | --8<-- "docs/citydb-tool/includes/import-filter-options.md"
55 |
56 | For more details on the filter options and usage hints, see [here](import.md#filter-options).
57 |
58 | ### Database connection options
59 |
60 | --8<-- "docs/citydb-tool/includes/db-options.md"
61 |
62 | For more details on the database connection options and usage hints, see [here](database.md#using-command-line-options).
63 |
64 | ## Usage
65 |
66 | !!! tip
67 | For general usage hints applicable to all subcommands of the `import` command (including but not limited to
68 | `import cityjson`), refer to the documentation for the `import` command [here](import.md#usage).
69 |
70 | ### Supported CityJSON versions
71 |
72 | The `import cityjson` command supports importing CityJSON files in versions 2.0, 1.1, and 1.0. In addition to regular
73 | CityJSON files, the [CityJSON Text Sequence (CityJSONSeq)](https://www.cityjson.org/cityjsonseq/) format is also
74 | supported. CityJSONSeq decomposes the CityJSON dataset into its 1st-level features, which are stored as separate JSON
75 | objects on individual lines, each delimited by newlines. This format enables efficient streaming of large CityJSON data.
76 |
77 | The following file types and extensions are recognized by citydb-tool:
78 |
79 | | File type | File extensions |
80 | |----------------------|-------------------|
81 | | CityJSON file | `.json`, `.jsonl` |
82 | | GZIP compressed file | `.gz`, `.gzip` |
83 | | ZIP archive | `.zip` |
84 |
85 | The file extensions are used when a directory or ZIP archive is provided as `--db-password
[=<password>]
| Password to use when connecting to the 3DCityDB. Leave empty to be prompted. | |
9 | | --db-property=<property=value>
[,<property=value>...]
| Database-specific connection properties. | |
10 |
--------------------------------------------------------------------------------
/docs/citydb-tool/includes/export-filter-options.md:
--------------------------------------------------------------------------------
1 | | Option | Description | Default value |
2 | |----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------|---------------|
3 | | `-t`, --type-name=<[prefix:]name>
[,<[prefix:]name>...]
| Names of the features to process. | |
4 | | `-f`, `--filter=--sort-by=<property[+|-]>
[,<property[+|-]>...]
| Properties and sort orders for sorting features. | |
8 | | `--limit=--lod=<lod>
[,<lod>...]
| Export geometries with a matching LoD. | |
11 | | `--lod-mode=--lod-search-depth=<0..n|all>
| Levels of sub-features to search for matching LoDs | 0 |
13 | | `--no-appearances` | Do not process appearances. | |
14 | | `-a`, --appearance-theme=<theme>
[,<theme>...]
| Process appearances with a matching theme. Use `none` for the null theme. | |
15 |
--------------------------------------------------------------------------------
/docs/citydb-tool/includes/export-general-options.md:
--------------------------------------------------------------------------------
1 | | Option | Description | Default value |
2 | |----------------------------------------------------------|-------------------------------------------------------------------------------------------|---------------|
3 | | `-o`, `--output=--transform=<m0,m1,...,m11|swap-xy>
| Transform coordinates using a 3x4 matrix in row-major order. Use `swap-xy` as a shortcut. | |
11 |
--------------------------------------------------------------------------------
/docs/citydb-tool/includes/export-history-options.md:
--------------------------------------------------------------------------------
1 | | Option | Description | Default value |
2 | |---------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------|
3 | | `-M`, `--validity=