├── .github └── workflows │ └── ci.yml ├── .gitignore ├── .vscode └── settings.json ├── LICENSE ├── README.md ├── _template.md ├── counter.sh ├── docs ├── .pages ├── 3dcitydb │ ├── .pages │ ├── appearance-module.md │ ├── assets │ │ ├── .gitkeep │ │ ├── appearance-module.png │ │ ├── citydb-docker-logo.png │ │ ├── codelist-module.png │ │ ├── feature-module.png │ │ ├── geometry-module.png │ │ ├── metadata-module.png │ │ └── relational-schema.png │ ├── codelist-module.md │ ├── db-functions.md │ ├── db-scripts.md │ ├── docker.md │ ├── feature-module.md │ ├── geometry-module.md │ ├── index.md │ ├── metadata-module.md │ └── relational-schema.md ├── assets │ ├── img │ │ └── logos │ │ │ ├── 3dcitydb-logo-long-transparent.png │ │ │ ├── 3dcitydb-logo-long.png │ │ │ ├── 3dcitydb-logo-transparent.png │ │ │ └── 3dcitydb-logo.png │ ├── javascripts │ │ ├── katex.js │ │ └── tablesort.js │ └── stylesheets │ │ └── extra.css ├── citydb-tool │ ├── .pages │ ├── assets │ │ ├── .gitkeep │ │ └── citydb-help.png │ ├── cli.md │ ├── config.md │ ├── cql2.md │ ├── database.md │ ├── delete-config.md │ ├── delete.md │ ├── docker.md │ ├── export-citygml.md │ ├── export-cityjson.md │ ├── export-config.md │ ├── export.md │ ├── import-citygml.md │ ├── import-cityjson.md │ ├── import-config.md │ ├── import.md │ ├── includes │ │ ├── db-options.md │ │ ├── export-filter-options.md │ │ ├── export-general-options.md │ │ ├── export-history-options.md │ │ ├── export-tiling-options.md │ │ ├── global-options.md │ │ ├── import-filter-options.md │ │ ├── import-general-options.md │ │ └── import-metadata-options.md │ ├── index-command.md │ └── index.md ├── compatibility.md ├── download.md ├── first-steps │ ├── .pages │ ├── assets │ │ ├── .gitkeep │ │ ├── citydb-export.png │ │ ├── citydb-import.png │ │ ├── citydb_docker_logo.png │ │ ├── citydb_docker_term.gif │ │ └── create-db.png │ ├── citydb-tool.md │ ├── docker.md │ ├── index.md │ ├── migration.md │ ├── requirements.md │ └── setup.md ├── index.md ├── partners │ ├── .pages │ ├── assets │ │ ├── .gitkeep │ │ ├── 3DCityDB2.PNG │ │ ├── HFT-Stuttgart-Logo-2025.svg │ │ ├── LIST_Eco_Endorsement_Farbe_CMYK.png │ │ ├── LIST_Eco_overview-quarter.jpg │ │ ├── List_Eco_Farbe_sRGB.svg │ │ ├── MOSS_Logo.svg │ │ ├── TUMLogo_oZ_Vollfl_blau_RGB.png │ │ ├── bwibo.jpg │ │ ├── cnagel.jpg │ │ ├── mogi.PNG │ │ ├── thkolbe.jpg │ │ ├── vcs-digital-twin-bremen.png │ │ ├── vcs-logo-small.png │ │ ├── vcs-logo.png │ │ ├── vcs-urban-simulation.jpg │ │ └── zyao.jpg │ ├── hft-stuttgart.md │ ├── index.md │ ├── list-eco.md │ ├── moss.md │ ├── tum-gis.md │ └── vcs.md ├── tags.md └── usage-contrib.md ├── includes └── abbreviations.md ├── mkdocs.yml └── requirements.txt /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: ci 2 | on: 3 | push: 4 | branches: 5 | - main 6 | 7 | permissions: 8 | contents: write 9 | jobs: 10 | deploy: 11 | runs-on: ubuntu-latest 12 | steps: 13 | 14 | - uses: actions/checkout@v4 15 | 16 | - name: Configure Git Credentials 17 | run: | 18 | git config user.name github-actions[bot] 19 | git config user.email 41898282+github-actions[bot]@users.noreply.github.com 20 | 21 | - uses: actions/setup-python@v5 22 | with: 23 | python-version: 3.x 24 | 25 | - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 26 | 27 | 28 | - uses: actions/cache@v4 29 | with: 30 | key: mkdocs-material-${{ env.cache_id }} 31 | path: .cache 32 | restore-keys: | 33 | mkdocs-material- 34 | 35 | - run: pip install -U -r requirements.txt 36 | 37 | - run: mkdocs gh-deploy --force 38 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Python venvs 2 | /.venv/ 3 | /.venv-win/ 4 | 5 | # IDE folders 6 | .idea/ 7 | 8 | # Build dirs 9 | site/ 10 | -------------------------------------------------------------------------------- /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | { 2 | "yaml.schemas": { 3 | "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml" 4 | }, 5 | "yaml.customTags": [ 6 | "!ENV scalar", 7 | "!ENV sequence", 8 | "!relative scalar", 9 | "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg", 10 | "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji", 11 | "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format", 12 | "tag:yaml.org,2002:python/object/apply:pymdownx.slugs.slugify mapping" 13 | ], 14 | "markdownlint.config": { 15 | "default": true, 16 | "MD024": false, 17 | "MD033": false, 18 | "MD046": false, 19 | "MD007": false 20 | }, 21 | "markdown.extension.toc.updateOnSave": false, 22 | "editor.tabSize": 4 23 | } 24 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # 3D City Database (3DCityDB) v5 documentation 2 | 3 | Documentation of the 3D City Database and tool starting from version `5`. 4 | 5 | :rocket: https://3dcitydb.github.io/3dcitydb-mkdocs/ :rocket: 6 | -------------------------------------------------------------------------------- /_template.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 3 | subtitle: 4 | description: 5 | # icon: material/emoticon-happy 6 | status: wip 7 | tags: 8 | - tag1 9 | - tag2 10 | - tag3 11 | --- 12 | 13 | ## hl2 14 | 15 | ### hl3 16 | 17 | 44 | -------------------------------------------------------------------------------- /counter.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Directory to iterate over (defaults to current directory if not provided) 4 | DIR=${1:-.} 5 | BASE_DIR=${2:-$DIR} # Base directory to extract relative path 6 | 7 | # Function to URL encode a string 8 | url_encode() { 9 | local string="$1" 10 | local encoded="" 11 | local i char 12 | for ((i=0; i<${#string}; i++)); do 13 | char="${string:i:1}" 14 | case "$char" in 15 | [a-zA-Z0-9.~_-]) encoded+="$char" ;; 16 | *) encoded+=$(printf '%%%02X' "'${char}") ;; 17 | esac 18 | done 19 | echo "$encoded" 20 | } 21 | 22 | # Iterate over all Markdown files in the directory and subdirectories 23 | find "$DIR" -type f -name "*.md" | while read -r FILE; do 24 | # Extract the relative path from BASE_DIR, remove file extension, replace '/' with '_' 25 | REL_PATH="${FILE#$BASE_DIR/}" 26 | REL_PATH="${REL_PATH%.md}/" # Remove file extension and add slash 27 | URL_ENCODED_PATH=$(url_encode "$REL_PATH") 28 | 29 | # Define the formatted string with the URL encoded path 30 | TEXT_TO_APPEND="[![Hits](https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2F3dcitydb.github.io%2F3dcitydb-mkdocs%2F${URL_ENCODED_PATH}&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=Visitors&edge_flat=false)](https://hits.seeyoufarm.com/#history)" 31 | 32 | # Append the formatted text to the file 33 | printf "\n" >> "$FILE" 34 | echo "$TEXT_TO_APPEND" >> "$FILE" 35 | printf "\n/// caption\n///\n" >> "$FILE" 36 | echo "Appended to $FILE: $TEXT_TO_APPEND" 37 | done 38 | -------------------------------------------------------------------------------- /docs/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - Welcome: 3 | - index.md 4 | - download.md 5 | - compatibility.md 6 | - usage-contrib.md 7 | - tags.md 8 | - First steps: first-steps 9 | - 3D City Database: 3dcitydb 10 | - citydb-tool: citydb-tool 11 | - ... 12 | -------------------------------------------------------------------------------- /docs/3dcitydb/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - index.md 3 | - Relational schema: 4 | - Schema overview: relational-schema.md 5 | - Feature module: feature-module.md 6 | - Geometry module: geometry-module.md 7 | - Appearance module: appearance-module.md 8 | - Metadata module: metadata-module.md 9 | - Codelist module: codelist-module.md 10 | - db-scripts.md 11 | - db-functions.md 12 | - ... 13 | -------------------------------------------------------------------------------- /docs/3dcitydb/assets/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/3dcitydb/assets/.gitkeep -------------------------------------------------------------------------------- /docs/3dcitydb/assets/appearance-module.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/3dcitydb/assets/appearance-module.png -------------------------------------------------------------------------------- /docs/3dcitydb/assets/citydb-docker-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/3dcitydb/assets/citydb-docker-logo.png -------------------------------------------------------------------------------- /docs/3dcitydb/assets/codelist-module.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/3dcitydb/assets/codelist-module.png -------------------------------------------------------------------------------- /docs/3dcitydb/assets/feature-module.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/3dcitydb/assets/feature-module.png -------------------------------------------------------------------------------- /docs/3dcitydb/assets/geometry-module.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/3dcitydb/assets/geometry-module.png -------------------------------------------------------------------------------- /docs/3dcitydb/assets/metadata-module.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/3dcitydb/assets/metadata-module.png -------------------------------------------------------------------------------- /docs/3dcitydb/assets/relational-schema.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/3dcitydb/assets/relational-schema.png -------------------------------------------------------------------------------- /docs/3dcitydb/codelist-module.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Codelist module 3 | description: Tables for storing codelists 4 | tags: 5 | - 3dcitydb 6 | - relational schema 7 | - codelist 8 | --- 9 | 10 | The Codelist module in 3DCityDB `v5` adds support for storing codelists, which are tables of values with corresponding 11 | descriptions or definitions. Many CityGML properties are designed to take values from codelists, as defined in the 12 | [CityGML 3.0 Conceptual Model (CM)](https://docs.ogc.org/is/20-010/20-010.html). Codelists may be required, recommended, 13 | or suggested by an authority within an organization or community, or more informally defined and used within an 14 | application domain. 15 | 16 | ![codelist module](assets/codelist-module.png) 17 | /// figure-caption 18 | Codelist module of the 3DCityDB `v5` relational schema. 19 | /// 20 | 21 | ## `CODELIST` table 22 | 23 | The `CODELIST` table is used to register codelists. Each codelist is assigned a URL as a unique identifier, which is 24 | stored in the `url` column. 25 | 26 | In case the `url` points to an existing external file, the `mime_type` column should specify the 27 | MIME type of the referenced codelist to ensure it can be processed correctly according to its format. CityGML does not 28 | prescribe specific formats for codelists but suggests using GML, JSON, and CSV-based encodings (see 29 | [here](https://docs.ogc.org/is/21-006r2/21-006r2.html#annex-codelist-usage)). 30 | 31 | The `codelist_type` column specifies the CityGML data type associated with the codelist. It stores the qualified 32 | classname of the data type as defined in the CityGML CM, such as `core:RelationTypeValue` or`bldg:BuildingClassValue`. 33 | 34 | There is no foreign key connecting the `CODELIST` table with the [`PROPERTY`](feature-module.md#property-table) table 35 | to directly link a codelist with a property that uses values from it. Instead, properties that reference codelists are 36 | typically of type `core:Code`, which includes a `codeSpace` attribute stored in the `val_codespace` column. This `codeSpace` 37 | typically points to the URL identifying the codelist from which the property value is taken. The corresponding codelist in 38 | the `CODELIST` table can be identified by matching the `codeSpace` value with the `url` column. 39 | 40 | !!! note 41 | Multiple codelists can be registered for the same `codelist_type`, such as codelists from different 42 | authorities or communities. In these cases, the combination of `codelist_type` and `url` should be unique across 43 | all entries in the `CODELIST` table. 44 | 45 | ## `CODELIST_ENTRY` table 46 | 47 | The `CODELIST_ENTRY` tables stores the values of the registered codelists. Each value is linked to a 48 | codelist through the `codelist_id` foreign key, which references an entry in the `CODELIST` table. 49 | 50 | The code for each permissible codelist value, along with its definition or description, is stored in the `code` and 51 | `definition` columns, respectively. This setup allows for easy lookup of the definition for a code that is stored as 52 | property value in the `PROPERTY` table, and vice versa. 53 | 54 | !!! tip 55 | Besides using the codelist tables to look up or validate property values associated with a codelist during data import 56 | and export, they can also be used to build a web service that provides stored codelists as files or serves as a lookup and 57 | validation service for individual codelist values. Tools for building such services are not included in the 58 | 3DCityDB `v5`, though. 59 | -------------------------------------------------------------------------------- /docs/3dcitydb/db-scripts.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Database scripts 3 | description: Database scripts of the 3DCityDB 4 | tags: 5 | - 3dcitydb 6 | - database scripts 7 | --- 8 | 9 | The 3DCityDB `v5` software package comes with shell and SQL scripts for tasks such as 10 | [setting up](../first-steps/setup.md#3dcitydb-setup-steps) or removing a 3DCityDB instance, creating 11 | additional schemas, and granting or revoking access permissions. 12 | 13 | !!! tip 14 | Follow the [download instructions](../download.md) to obtain the database scripts. They are available as an individual 15 | download package but are also included in the `citydb-tool` software bundle. 16 | 17 | ## Shell scripts 18 | 19 | The 3DCityDB `v5` shell scripts are located in the `3dcitydb/postgresql/shell-scripts` directory of the 3DCityDB 20 | software package or within the installation directory of `citydb-tool`. They are available in two variants, 21 | organized into the following subfolders: 22 | 23 | 1. `unix` for use on UNIX/Linux/macOS systems; and 24 | 2. `windows` for use on Windows systems. 25 | 26 | The following table provides an overview of the available shell scripts and their purposes. 27 | 28 | | Script [.sh\|.bat] | Description | 29 | |----------------------|-----------------------------------------------------------------------------------------------------------| 30 | | `connection-details` | Stores the connection details for a 3DCityDB instance which are used by all other scripts | 31 | | `create-db` | Creates a new 3DCityDB instance (relational schema including all database functions) | 32 | | `create-schema` | Creates an additional data schema (analogous to the default schema `citydb`) with a user-defined name | 33 | | `drop-db` | Drops a 3DCityDB instance (incl. all elements of the relational schema) | 34 | | `drop-schema` | Drops a data schema that has been created with `create-schema` | 35 | | `grant-access` | Grants read-only or read-write access to a 3DCityDB instance | 36 | | `revoke-access` | Revokes read-only or read-write access to a 3DCityDB instance, which has been granted with `grant-access` | 37 | | `create-changelog` | Create the changelog extension for a 3DCityDB instance | 38 | | `drop-changelog` | Remove the changelog extension from a 3DCityDB instance | 39 | 40 | The scripts are intended to run in an interactive shell session, prompting the user for necessary information to perform 41 | their tasks. The `connection-details` script serves a special purpose, as it defines the connection details for your 42 | 3DCityDB `v5` instance. These details are used by all other scripts, so make sure to adjust them before executing any of 43 | them. This includes specifying the full path to the `psql` executable on your system, which is required by all scripts. 44 | 45 | Open the `connection-details` script with a text editor of your choice and enter the necessary information, as shown 46 | below. 47 | 48 | === "Linux" 49 | 50 | ```bash 51 | #!/bin/bash 52 | # Provide your database details here ---------------- 53 | export PGBIN=/var/lib/postgresql/[version]/bin 54 | export PGHOST=localhost 55 | export PGPORT=5432 56 | export CITYDB=citydb_v5 57 | export PGUSER=citydb_user 58 | #---------------------------------------------------- 59 | ``` 60 | 61 | === "Windows CMD" 62 | 63 | ```bat 64 | # Provide your database details here ---------------- 65 | set PGBIN=C:\Program Files\PostgreSQL\[version]\bin 66 | set PGHOST=localhost 67 | set PGPORT=5432 68 | set CITYDB=citydb_v5 69 | set PGUSER=citydb_user 70 | #---------------------------------------------------- 71 | ``` 72 | 73 | !!! info 74 | If the `psql` executable is already on your `PATH`, you can comment out or remove the line setting 75 | the `PGBIN` variable in the script. 76 | 77 | After adjusting the `connection-details` script, all other scripts can be executed either by double-clicking them or by 78 | running them from within a shell environment. On UNIX/Linux machines, you may first need to set the appropriate file 79 | permissions to make the script executable. 80 | 81 | The example below demonstrates how to run the `create-db` script to set up a new 3DCityDB `v5` instance. 82 | 83 | === "Linux" 84 | 85 | ```bash 86 | chmod u+x create-db.sh 87 | ./create-db.sh 88 | ``` 89 | 90 | === "Windows CMD" 91 | 92 | ```bat 93 | create-db.bat 94 | ``` 95 | 96 | It is also possible to use a different `connection-details` file from another folder: 97 | 98 | === "Linux" 99 | 100 | ```bash 101 | ./create-db.sh /path/to/connection-details.sh 102 | ``` 103 | 104 | === "Windows CMD" 105 | 106 | ```bat 107 | create-db.bat C:\path\to\connection-details.bat 108 | ``` 109 | 110 | ## SQL scripts 111 | 112 | Technically, the shell scripts listed above are simply wrappers designed to collect user input in a convenient manner. 113 | The actual actions at the database level are carried out by SQL scripts that are invoked by these shell scripts. 114 | 115 | The SQL scripts are provided in the `3dcitydb/postgresql/sql-scripts` directory of the 3DCityDB software package 116 | or within the installation directory of `citydb-tool`. Similar to the shell scripts, navigate to the `unix` or `windows` 117 | subfolder, depending on your operating system. The SQL scripts are designed to be executed with `psql`. 118 | 119 | Most of the SQL scripts require input parameters to execute the database action. These parameters should be 120 | passed as command-line parameters to `psql`. Below is an example of how to invoke the `create-db.sql` script to set up 121 | a 3DCityDB `v5` instance. The required input parameters for this script are discussed in the 122 | [setup instructions](../first-steps/setup.md#3dcitydb-setup-steps). Refer to the `psql` documentation for more details 123 | on its usage and command-line options. 124 | 125 | === "Linux" 126 | 127 | ```bash 128 | psql -d "citydb_v5" \ 129 | -h localhost \ 130 | -U "citydb_user" \ 131 | -f "/path/to/the/reate-db.sql" \ 132 | -v srid="25833" \ 133 | -v srs_name="urn:ogc:def:crs:EPSG::25833" \ 134 | -v changelog="no" 135 | ``` 136 | 137 | === "Windows CMD" 138 | 139 | ```bat 140 | psql -d "citydb_v5" ^ 141 | -h localhost ^ 142 | -U "citydb_user" ^ 143 | -f "C:\path\to\the\create-db.sql" ^ 144 | -v srid="25833" ^ 145 | -v srs_name="urn:ogc:def:crs:EPSG::25833" ^ 146 | -v changelog="no" 147 | ``` 148 | 149 | !!! tip 150 | By using shell or environment variables instead of hardcoding values directly into your command as shown above, you make 151 | it easier to reuse the SQL scripts across different setups or systems. This makes automating things, integrating them 152 | into other software, or running them as part of a CI/CD pipeline way more flexible. This is an easy way to streamline 153 | workflows using the SQL scripts. -------------------------------------------------------------------------------- /docs/3dcitydb/index.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: 3D City Database 3 | description: Intro to 3DCityDB. 4 | tags: 5 | - 3dcitydb 6 | - CityGML data 7 | - features 8 | --- 9 | 10 | The **3D City Database `v5`** (3DCityDB) is a free 3D geo database to store, represent, and manage 11 | virtual 3D city models within a standard spatial relational database. The database model contains 12 | semantically rich, hierarchically structured, multi-scale urban objects, facilitating complex GIS 13 | modeling and analysis tasks, far beyond visualization. 14 | 15 | The database schema of the 3DCityDB `v5` results from a systematic mapping and complete implementation 16 | of the data model defined in the [OGC CityGML 3.0 Conceptual Model](https://www.ogc.org/standard/citygml/){target="blank"}, 17 | an international standard for representing and exchanging virtual 3D city models, issued by the 18 | [Open Geospatial Consortium (OGC)](https://www.ogc.org/){target="blank"}. 19 | 20 | The 3DCityDB is open source and hosted on [GitHub](https://github.com/3dcitydb). You can download the 3DCityDB `v5` 21 | software packages by following the [download instructions](../download.md). We also offer 22 | [Docker support](../first-steps/docker.md), making it easy to get a 3DCityDB `v5` instance up and running 23 | in just a few seconds. 24 | 25 | ## Key features of 3DCityDB v5 26 | 27 | - Full support for CityGML versions 3.0, 2.0 and 1.0 28 | - Complex thematic modeling including support for Application Domain Extensions (ADE) 29 | - Four (CityGML 3.0) or five (CityGML 2.0 and 1.0) different Levels of Detail (LoDs) 30 | - Appearance information (textures and materials) 31 | - Digital terrain models (DTMs) represented as TINs 32 | - Representation of generic and prototypical 3D objects 33 | - Free, also recursive aggregation of geo objects 34 | - Flexible 3D geometries such as Solid, CompositeSolid, MultiSurface, CompositeSurface, 35 | Polygon, TINs, MultiCurve, CompositeCurve, LineString, Point, and MultiPoint 36 | - Database functions to delete complex objects including all their nested 37 | sub-objects and geometries. As an alternative, objects can only be marked as terminated, 38 | which leaves them in the database but sets their termination date timestamps accordingly. 39 | This realizes a simple but powerful historization / versioning mechanism. 40 | - [`citydb-tool`](../citydb-tool/index.md) for importing and exporting CityGML datasets of any size, supporting both 41 | GML and CityJSON encodings. It works with CityGML versions 3.0, 2.0, and 1.0, as well as CityJSON versions 2.0, 1.1, 42 | and 1.0. Additionally, it enables seamless on-the-fly upgrading and downgrading between different versions. 43 | 44 | ## Changes with respect to 3DCityDB v4 45 | 46 | **Streamlined and optimized schema:** Compared to the earlier versions of the 3DCityDB `v4`, more generic rules have been 47 | applied in the mapping of the CityGML 3.0 data model onto the [relational schema](relational-schema.md), 48 | resulting in a significant reduction of the number of database tables. 49 | 50 | **Efficient geometry management:** [Geometry objects](geometry-module.md) are now directly mapped onto corresponding 51 | data types provided by PostGIS; i.e., Solids, MultiSurfaces, CompositeSurfaces, TINs, etc. are no longer 52 | split into their individual polygons and stored in separate rows as was done in 3DCityDB `v4`. 53 | This makes it much easier to express spatial queries in SQL, faster to evaluate such queries, 54 | and also to directly connect to the 3DCityDB from geoinformation systems 55 | like QGIS, FME, or ArcGIS and utilize the spatial objects. 56 | 57 | **New database client:** `citydb-tool` is the new default command-line client for 3DCityDB `v5`, designed to import and 58 | export city model data as well as perform data and database operations. Its command-line interface 59 | enables easy automation, integration with other software, and efficient use in workflows and pipelines. 60 | Unlike the previous [Importer/Exporter](https://github.com/3dcitydb/importer-exporter) tool for 3DCityDB `v4`, it no 61 | longer provides a graphical user interface. 62 | 63 | **Work-in-progress visualization support:** A tool for exporting 3DCityDB `v5` content in visualization formats like KML, 64 | COLLADA, or glTF, as was possible with the Importer/Exporter, is not available yet. However, we are actively working on 65 | a solution to export data in the OGC 3D Tiles format. For this purpose, we are 66 | evaluating open-source tools such as [pg2b3dm](https://github.com/Geodan/pg2b3dm){target="blank"} 67 | to work directly with the 3DCityDB `v5`. We also plan to publish the export tool as a customized Docker image. 68 | Stay tuned! 69 | 70 | !!! info "3DCityDB `v4` and legacy tool support" 71 | The 3DCityDB `v4` and its tools remain functioning and are still available. They will be maintained for an extended 72 | period to give users enough time to migrate to the new version. Please note that `v4` tools are not compatible with 73 | 3DCityDB `v5` (see our [compatibility and data migration](../compatibility.md) guide). 74 | If you are currently using or interested in using the previous version and its tools, please refer to the 75 | [3DCityDB `v4` suite](https://github.com/3dcitydb/3dcitydb-suite){target="blank"} package. The documentation 76 | of the 3DCityDB `v4` suite is still [available here](https://3dcitydb-docs.readthedocs.io/en/latest/){target="blank"}. 77 | 78 | ## Who is using the 3DCityDB? 79 | 80 | The 3D City Database `v4` is in use in real life production systems in many places around the world 81 | such as Berlin, Potsdam, Hamburg, Munich, Frankfurt, Dresden, Rotterdam, Vienna, Helsinki, 82 | Singapore, Zurich, and is also being used in a number of research projects. 83 | With the release of 3DCityDB `v5`, we expect that most users of `v4` will 84 | migrate to the new version in the future. 85 | 86 | The companies [Virtual City Systems](../partners/vcs.md) and [M.O.S.S.](../partners/moss.md), 87 | who are also partners in development, use the 3DCityDB at the core of their 88 | commercial products and services to create, maintain, visualize, transform, and export 89 | virtual 3D city models. Furthermore, the state mapping agencies of the federal states in Germany 90 | store and manage the nation-wide collected 3D city models, including approximately 56 million building models 91 | and bridges in CityGML LoD1 and LoD2, using the 3DCityDB. 92 | 93 | ## Where to find CityGML data? 94 | 95 | An excellent list of open data 3D city models, especially also represented using CityGML, 96 | can be found in the [Awesome CityGML](https://github.com/OloOcki/awesome-citygml) list. 97 | Currently, datasets from 21 countries and 65 regions/cities can be downloaded for free, 98 | with a total of >210 million semantic 3D building models. All the provided CityGML files 99 | can be loaded, analyzed, and managed using the 3DCityDB. 100 | -------------------------------------------------------------------------------- /docs/3dcitydb/relational-schema.md: -------------------------------------------------------------------------------- 1 | --- 2 | # title: Relational schema overview 3 | description: 3DCityDB v5 database schema 4 | tags: 5 | - 3dcitydb 6 | - relational schema 7 | - overview 8 | --- 9 | 10 | # Relational schema overview 11 | 12 | The 3D City Database `v5` is a major revision of the previous `v4` release. The database schema has been 13 | completely redesigned, significantly simplified, and restructured. Unlike `v4`, it no longer uses individual feature 14 | tables with dedicated attribute columns. Instead, the schema is streamlined with fewer tables, including a single 15 | `FEATURE` table for storing all features and objects, and a single `PROPERTY` table that holds most attributes and 16 | associations. 17 | 18 | The following figure illustrates the complete 3DCityDB `v5` relational database schema. 19 | 20 | ![relational schema](assets/relational-schema.png) 21 | /// figure-caption 22 | Relation schema of the 3DCityDB `v5`. 23 | /// 24 | 25 | All tables of the relation schema are logically grouped into five modules, which are discussed in the 26 | following chapters: 27 | 28 | - **Feature module**: Contains the core tables for storing feature information, excluding geometry and appearance data. 29 | - **Geometry module**: Contains tables for storing both explicit and implicit geometry data. 30 | - **Appearance module**: Contains tables for storing appearance information. 31 | - **Metadata module**: Holds meta-information about features and their properties. 32 | - **Codelist module**: Stores codelists with their corresponding values. 33 | 34 | !!! note 35 | Although conceptually the database model is applicable to any database system, this chapter uses 36 | PostgreSQL-specific figures and examples. 37 | -------------------------------------------------------------------------------- /docs/assets/img/logos/3dcitydb-logo-long-transparent.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/assets/img/logos/3dcitydb-logo-long-transparent.png -------------------------------------------------------------------------------- /docs/assets/img/logos/3dcitydb-logo-long.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/assets/img/logos/3dcitydb-logo-long.png -------------------------------------------------------------------------------- /docs/assets/img/logos/3dcitydb-logo-transparent.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/assets/img/logos/3dcitydb-logo-transparent.png -------------------------------------------------------------------------------- /docs/assets/img/logos/3dcitydb-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/assets/img/logos/3dcitydb-logo.png -------------------------------------------------------------------------------- /docs/assets/javascripts/katex.js: -------------------------------------------------------------------------------- 1 | document$.subscribe(({ body }) => { 2 | renderMathInElement(body, { 3 | delimiters: [ 4 | { left: "$$", right: "$$", display: true }, 5 | { left: "$", right: "$", display: false }, 6 | { left: "\\(", right: "\\)", display: false }, 7 | { left: "\\[", right: "\\]", display: true } 8 | ], 9 | }) 10 | }) 11 | -------------------------------------------------------------------------------- /docs/assets/javascripts/tablesort.js: -------------------------------------------------------------------------------- 1 | document$.subscribe(function() { 2 | var tables = document.querySelectorAll("article table:not([class])") 3 | tables.forEach(function(table) { 4 | new Tablesort(table) 5 | }) 6 | }) 7 | -------------------------------------------------------------------------------- /docs/assets/stylesheets/extra.css: -------------------------------------------------------------------------------- 1 | :root { 2 | --md-status--happy: url('data:image/svg+xml;charset=utf-8,'); 3 | --md-status--wip: url('data:image/svg+xml;charset=utf-8,'); 4 | } 5 | 6 | .md-status--happy::after { 7 | mask-image: var(--md-status--happy); 8 | -webkit-mask-image: var(--md-status--happy); 9 | } 10 | 11 | .md-status--wip::after { 12 | mask-image: var(--md-status--wip); 13 | -webkit-mask-image: var(--md-status--wip); 14 | } 15 | 16 | .md-typeset .admonition, 17 | .md-typeset details { 18 | font-size: 16px; 19 | } 20 | 21 | .md-typeset table:not([class]) th, 22 | .md-typeset table:not([class]) td { 23 | padding: 10px 5px; 24 | } 25 | -------------------------------------------------------------------------------- /docs/citydb-tool/.pages: -------------------------------------------------------------------------------- 1 | nav: 2 | - index.md 3 | - cli.md 4 | - database.md 5 | - Import command: 6 | - Import overview: import.md 7 | - CityGML import: import-citygml.md 8 | - CityJSON import: import-cityjson.md 9 | - Export command: 10 | - Export overview: export.md 11 | - CityGML export: export-citygml.md 12 | - CityJSON export: export-cityjson.md 13 | - delete.md 14 | - index-command.md 15 | - JSON configuration: 16 | - Configuration overview: config.md 17 | - Import configuration: import-config.md 18 | - Export configuration: export-config.md 19 | - Delete configuration: delete-config.md 20 | - cql2.md 21 | - docker.md -------------------------------------------------------------------------------- /docs/citydb-tool/assets/.gitkeep: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/citydb-tool/assets/.gitkeep -------------------------------------------------------------------------------- /docs/citydb-tool/assets/citydb-help.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/3dcitydb/3dcitydb-mkdocs/8bbffca03c463448b6422df4287e442f4fe72e8f/docs/citydb-tool/assets/citydb-help.png -------------------------------------------------------------------------------- /docs/citydb-tool/cli.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: CLI overview 3 | description: Using the CLI of citydb-tool 4 | tags: 5 | - citydb-tool 6 | - command-line interface 7 | - CLI 8 | --- 9 | 10 | `citydb` is the main command of citydb-tool. It requires a [subcommand](#commands) to perform a specific operation on a 11 | 3DCityDB `v5` instance, such as importing, exporting, and deleting city model data. It also defines common options 12 | that apply to all subcommands. 13 | 14 | ## Synopsis 15 | 16 | ```bash 17 | citydb [OPTIONS] COMMAND 18 | ``` 19 | 20 | ## Options 21 | 22 | --8<-- "docs/citydb-tool/includes/global-options.md" 23 | 24 | ## Commands 25 | 26 | | Command | Description | 27 | |---------------------------------------|--------------------------------------------------------------------------------------| 28 | | [`help`](#help-and-cli-documentation) | [Display help information about the specified command.](#help-and-cli-documentation) | 29 | | [`import`](import.md) | [Import data in a supported format.](import.md) | 30 | | [`export`](export.md) | [Export data in a supported format.](export.md) | 31 | | [`delete`](delete.md) | [Delete features from the database.](delete.md) | 32 | | [`index`](index-command.md) | [Perform index operations.](index-command.md) | 33 | 34 | !!! note 35 | If [plugins](#plugins) are registered for citydb-tool, they may extend the command list by adding their own 36 | commands to the CLI. 37 | 38 | ## Usage 39 | 40 | ### Version and 3DCityDB support 41 | 42 | The `--version` option displays the version of citydb-tool along with the supported 3DCityDB versions. A `+` sign next 43 | to a 3DCityDB version indicates that support starts with that version and includes all subsequent patch updates. Below 44 | is an example output. 45 | 46 | ```shell 47 | $ citydb --version 48 | citydb-tool version 1.0.0 49 | Supported 3DCityDB versions: 5.0.0+ 50 | (C) 2022-2025 virtualcitysystems GmbH 51 | ``` 52 | 53 | ### Help and CLI documentation 54 | 55 | To get help for a specific command, use the `--help` option. This will display a help message, including the 56 | command's synopsis and its available options. If the command has subcommands, the `--help` option applies to the 57 | command immediately preceding it. Alternatively, you can use the `help` command followed by the desired `COMMAND`, 58 | which can also be a subcommand, to get the same information. 59 | 60 | === "Help option" 61 | 62 | ```bash 63 | citydb --help 64 | citydb import --help 65 | citydb import citygml --help 66 | # ... 67 | ``` 68 | 69 | === "Help command" 70 | 71 | ```bash 72 | citydb help 73 | citydb help import 74 | citydb import help citygml 75 | # ... 76 | ``` 77 | 78 | ### Logging 79 | 80 | citydb-tool logs events such as activities or errors in the console, with each entry including a timestamp, severity 81 | level, and a descriptive message. The `--log-level` option controls the level of logging output shown in the console. It 82 | will include all events of the specified severity and those of higher severity. Available levels are: 83 | 84 | - `fatal`: Critical errors causing immediate termination 85 | - `error`: Non-recoverable errors 86 | - `warn`: Warnings about potential issues 87 | - `info`: General operational messages (default) 88 | - `debug`: Detailed debugging information 89 | - `trace`: Most detailed logs for troubleshooting 90 | 91 | Log messages can also be recorded in a log file specified with the `--log-file` option. The log level set with the 92 | `--log-level` option also applies to the log file. 93 | 94 | !!! note 95 | The log file will be truncated at startup if it already exists. 96 | 97 | ### Configuration files 98 | 99 | Options and settings for executing a citydb-tool command can also be loaded from a JSON-encoded configuration file 100 | specified with `--config-file`. Configuration files override default settings and can be used alongside command-line 101 | options for flexibility. However, command-line options always take precedence. Each CLI command defines its own JSON 102 | structure. For more information, see the [JSON configuration](config.md) chapter. 103 | 104 | === "Linux" 105 | 106 | ```bash 107 | ./citydb export citygml [...] \ 108 | --config-file=/path/to/my-config.json 109 | ``` 110 | 111 | === "Windows CMD" 112 | 113 | ```bat 114 | citydb export citygml [...] ^ 115 | --config-file=C:\path\to\my-config.json 116 | ``` 117 | 118 | !!! note 119 | Some commands may provide options exclusively in the JSON configuration, without corresponding command-line options. 120 | 121 | ### Plugins 122 | 123 | citydb-tool provides a flexible plugin mechanism for adding custom functionality, allowing plugins to introduce new 124 | commands or extend existing ones. Plugins are typically distributed as a ZIP package containing the plugin's 125 | Java Archive (JAR) file and any additional resources. 126 | 127 | To install a plugin, unzip it (if necessary) and place the files in the `plugins` subfolder within the citydb-tool 128 | installation directory. For better organization, it is recommended to create a separate subfolder for each plugin. 129 | citydb-tool will automatically detect and load the plugins from this location, logging successfully loaded plugins 130 | separately in the console. To uninstall a plugin, simply delete its folder from the `plugins` subfolder. 131 | 132 | The `--plugins` option allows you to specify a different location for loading plugins. To enable or disable plugins, use 133 | the `--use-plugin` option followed by the fully qualified Java class name and a value of `true` (enable) or `false` 134 | (disable) (default: `true`). Disabled plugins will not be loaded. Multiple plugins can be specified as a comma-separated 135 | list as shown below. 136 | 137 | === "Linux" 138 | 139 | ```bash 140 | ./citydb export citygml [...] \ 141 | --plugins=/path/to/my/plugins \ 142 | --use-plugin=com.example.PluginA=true,com.example.PluginB=false 143 | ``` 144 | 145 | === "Windows CMD" 146 | 147 | ```bat 148 | citydb export citygml [...] ^ 149 | --plugins=/path/to/my/plugins ^ 150 | --use-plugin=com.example.PluginA=true,com.example.PluginB=false 151 | ``` 152 | 153 | !!! tip 154 | Refer to the plugin's documentation for details on its functionality, available CLI commands, options, and the fully 155 | qualified class name for the `--use-plugin` option. The class name will also be printed to the console when the plugin 156 | is loaded by citydb-tool. 157 | 158 | ### Exit codes 159 | 160 | citydb-tool uses exit codes to indicate the success or failure of an operation. These codes help users and scripts 161 | determine whether the execution was successful or if an error occurred. Below are the exit codes used by citydb-tool: 162 | 163 | - `0`: The operation completed successfully without errors 164 | - `1`: The operation terminated abnormally due to errors or issues 165 | - `2`: Invalid input for an option or parameter 166 | - Greater than `2`: Specific operation errors 167 | 168 | ## CLI tips and tricks 169 | 170 | ### Specifying options 171 | 172 | Options that take a value can be specified using an equal sign (`=`) or a space. This applies to both short and long 173 | options. Short options that do not take a value can be grouped behind a single `-` delimiter, followed by at most one 174 | short option that requires a value. 175 | 176 | The following generic examples are all equivalent, assuming `-f` is a short form for `--file`: 177 | 178 | ```bash 179 | -a -b -c --file=my-file.txt 180 | -ab -c --file my-file.txt 181 | -abc -f my-file.txt 182 | -abcf=my-file.txt 183 | ``` 184 | 185 | Multi-value options, such as `--use-plugin`, can accept one or more values. If multiple values are needed, they can either 186 | be provided as a comma-separated list or by specifying the option multiple times. 187 | 188 | The following examples are all valid: 189 | 190 | ```bash 191 | citydb --use-plugin=com.example.PluginA,com.example.PluginB=false 192 | citydb --use-plugin=com.example.PluginA --use-plugin=com.example.PluginB=false 193 | ``` 194 | 195 | ### Double dash delimiter 196 | 197 | citydb-tool supports the `--` delimiter to separate options from positional arguments. Any argument after `--` is 198 | treated as a positional parameter, even if it matches an option name. 199 | 200 | For example, consider the following `import citygml` command to import the CityGML file `my-city.gml`: 201 | 202 | ```bash 203 | citydb import citygml [...] --db-password my-city.gml 204 | ``` 205 | 206 | The `--db-password` option of citydb-tool either takes a password as a value or, if left empty, prompts the user for input. 207 | In this example, the user intended to be prompted for a password. However, `my-city.gml` will instead be interpreted as 208 | the password rather than the input file. To prevent this, use the `--` delimiter: 209 | 210 | ```bash 211 | citydb import citygml [...] --db-password -- my-city.gml 212 | ``` 213 | 214 | ### Abbreviated options and commands 215 | 216 | To simplify CLI usage, citydb-tool provides short forms for some options (e.g., `-h` for `--help`). Additionally, long 217 | options without a specific short form can be abbreviated by using the initial letter(s) of the first component and 218 | optionally of one or more subsequent components of the option name. "Components" are separated by `-` (dash) characters 219 | or by case. For example, both `--camelCase` and `--kebab-case` consist of two components. 220 | 221 | The following are valid abbreviations for `--super-long-option`, which has three components: 222 | 223 | ```bash 224 | --sup, --slo, --s-l-o, --s-lon, --s-opt, --sLon, --sOpt, --soLoOp (...) 225 | ``` 226 | 227 | The same abbreviation syntax can also be used for command names. However, abbreviations for both options and commands 228 | must be unambiguous. For example, the command `import city` could be interpreted as both `import citygml` and 229 | `import cityjson`, leading to a conflict. In such cases, citydb-tool will abort and display an error message to 230 | prevent ambiguity. 231 | 232 | ### Argument files 233 | 234 | When a command line includes many options or long arguments, system limitations on command length may become an issue. 235 | Argument files (`@-files`) help overcome this limitation by allowing arguments to be stored in a separate file. You can 236 | specify one or more argument files by prefixing their filenames with `@` on the command line. The contents of each `@-file` 237 | are automatically expanded into the argument list. 238 | 239 | Arguments in an `@-file` can be separated by spaces or newlines. Arguments containing spaces must be enclosed in 240 | double (`"`) or single (`'`) quotes. Within quoted values, quotes are escaped with a backslash (`\`), and backslashes are 241 | escaped by doubling them (`\\`). Lines starting with `#` are comments and are ignored. The argument file can also 242 | contain references to additional `@-files`, which will be processed recursively. 243 | 244 | For example, suppose an `@-file` exists at `/home/foo/args`, containing the following logging and database connection 245 | options: 246 | 247 | ```bash 248 | # This line is a comment and is ignored 249 | --log-level=debug 250 | --log-file=/path/to/my/logfile.log 251 | --db-host=localhost 252 | --db-name=citydb 253 | --db-user=citydb_user 254 | --db-password=changeMe 255 | ``` 256 | 257 | This `@-file` can be used with a citydb-tool command as shown below. The specified path can be either absolute or 258 | relative to the current directory. 259 | 260 | ```bash 261 | citydb index status @/home/foo/args 262 | ``` 263 | 264 | You can also use multiple `@-files` on the command line to logically group their contents. 265 | 266 | ```bash 267 | citydb index status @/home/foo/db-args @/home/foo/logging-args 268 | ``` 269 | 270 | !!! tip 271 | Although `@-files` are intended for a different purpose, they can be used similarly to configuration files to execute 272 | commands with different options depending on the scenario or use case. However, it is recommended to use configuration 273 | files whenever possible. 274 | 275 | !!! warning 276 | Argument files have a limitation: parameter or option values enclosed in quotes must not be preceded by an equal sign. 277 | For example, `--my-option="foo bar"` will not work inside an argument file. To work around this, either omit the equal sign 278 | (`--my-option "foo bar"`) or enclose the entire expression in quotes (`"--my-option=\"foo bar\""`). -------------------------------------------------------------------------------- /docs/citydb-tool/config.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: JSON configuration 3 | description: Overview of the JSON configuration of citydb-tool 4 | tags: 5 | - citydb-tool 6 | - JSON 7 | - config 8 | --- 9 | 10 | # JSON configuration 11 | 12 | The options and settings for executing a citydb-tool command can be defined in a JSON-encoded configuration file, 13 | offering an alternative to manually specifying them via the command line. The configuration file organizes 14 | options into functional sections, with each command using one or more sections based on its specific task 15 | and operation. 16 | 17 | The example below illustrates the basic structure of the configuration file, highlighting the main sections. 18 | A configuration file can include all sections for reusability across different commands, or it may contain only the 19 | sections needed for a specific command. 20 | 21 | ```json 22 | { 23 | "databaseOptions": {...}, 24 | "importOptions": {...}, 25 | "readOptions": {...}, 26 | "exportOptions": {...}, 27 | "writeOptions": {...}, 28 | "deleteOptions": {...}, 29 | ... 30 | } 31 | ``` 32 | 33 | ## Configuration sections 34 | 35 | The purpose of each configuration section is outlined below. Their content and usage for different citydb-tool commands are 36 | explained in more detail in the following chapters. 37 | 38 | |
Section
| Description | 39 | |--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------| 40 | | [`"databaseOptions"`](database.md#using-configuration-files) | Defines connection details for one or more 3DCityDB instances, usable by all commands that require a database connection. | 41 | | [`"importOptions"`](import-config.md#import-options) | Defines options for controlling the import process. | 42 | | [`"readOptions"`](import-config.md#read-options) | Specifies settings for reading input files, including format-specific options. | 43 | | [`"exportOptions"`](export-config.md#export-options) | Defines options for controlling the export process. | 44 | | [`"writeOptions"`](export-config.md#write-options) | Specifies settings for writing output files, including format-specific options. | 45 | | [`"deleteOptions"`](delete-config.md) | Defines options for controlling the delete process. | | 46 | 47 | You can load configuration files using the [`--config-file`](cli.md#configuration-files) option when executing 48 | citydb-tool commands. 49 | 50 | === "Linux" 51 | 52 | ```bash 53 | ./citydb import citygml \ 54 | --config-file=/path/to/my-config.json \ 55 | my-city.gml 56 | ``` 57 | 58 | === "Windows CMD" 59 | 60 | ```bat 61 | citydb import citygml ^ 62 | --config-file=C:\path\to\my-config.json ^ 63 | my-city.gml 64 | ``` 65 | 66 | !!! tip 67 | - Configuration files can be used alongside command-line options for flexibility. However, command-line options always 68 | take precedence. 69 | - Some commands may provide options exclusively in the JSON configuration, without corresponding command-line options. 70 | - If [plugins](cli.md#plugins) are registered for citydb-tool, they may extend the configuration by adding their 71 | own sections. -------------------------------------------------------------------------------- /docs/citydb-tool/cql2.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: CQL2 query language 3 | description: Filter and query data using CQL2 query language 4 | tags: 5 | - cql2 6 | - query 7 | - filter 8 | - spatial filter 9 | - attribute filter 10 | --- 11 | 12 | **CQL2** (Common Query Language 2) is an advanced query language used to filter and query spatial and attribute 13 | data within the **citydb-tool**. It allows users to define precise queries for exporting or deleting features 14 | based on attribute values, spatial properties, or logical conditions. 15 | 16 | CQL2 is a standard maintained by the **OGC (Open Geospatial Consortium)** and serves as an evolution of the 17 | original CQL language, providing better expressiveness and flexibility for data filtering. 18 | 19 | Key Features of CQL2 20 | 21 | - Expressive Syntax: Combines logical operators with a rich set of functions for building complex queries. 22 | - Spatial Filtering: Supports geospatial functions to filter data based on spatial relationships. 23 | - Ease of Use: Simple, human-readable expressions that are easy to construct and interpret. 24 | 25 | --- 26 | 27 | ## Using CQL2 with citydb-tool 28 | 29 | citydb-tool allows the use of the `-f` or `--filter` option followed by a CQL2 expression to filter data when exporting or 30 | deleting records. This enables users to select only the relevant subset of data based on attribute values, 31 | spatial conditions, or both. 32 | 33 | - Text-based (string) encoding 34 | - JSON-based encoding 35 | 36 | Both encodings are supported by citydb-tool, giving you flexibility in how you structure your filters. 37 | 38 | ## Syntax 39 | 40 | The general syntax for using CQL2 with citydb-tool is: 41 | 42 | ```bash 43 | citydb [command] -f "" 44 | ``` 45 | 46 | Where `` is a valid CQL2 query that defines the filtering conditions for the data export. 47 | 48 | ## Writing CQL2 expressions 49 | 50 | A CQL2 expression consists of attribute names, operators, and values. It can also include spatial functions to handle geospatial conditions. 51 | 52 | ### Understanding literals 53 | 54 | In CQL2, literals are direct values that appear in your filter expressions. Common types of literals include: 55 | 56 | - Strings: Enclosed in single quotes in text-based queries (e.g., `'Forest tree 3'`), or as JSON strings in JSON-based queries (e.g., `'Forest tree 3'`). 57 | - Numbers: Used without quotes in both text-based and JSON-based queries (e.g., `> 10` or `10` in JSON). 58 | - Booleans: Typically represented as `true` or `false`. 59 | - Dates/Times: Represented in ISO-8601 format (e.g., `'2023-01-31'` or `'2023-01-31'` in JSON), if your data or schema supports date/time attributes. 60 | 61 | ### Attribute references 62 | 63 | #### Implicit vs. explicit attribute references 64 | 65 | When writing CQL2 queries, it's important to correctly reference attributes by their full property names rather than 66 | relying on implicit assumptions. While some query tools allow shorthand notations for convenience, 67 | the proper CQL2 syntax requires explicit attribute references. 68 | 69 | For example, in some cases, a query like: 70 | 71 | ```bash 72 | citydb export citygml --filter="height > 1" 73 | ``` 74 | 75 | might work as expected, but it is a simplified form. The correct way is to specify the full property path. For instance, 76 | if the attribute height belongs to the bldg (building) namespace, the correct query should be: 77 | 78 | ```bash 79 | citydb export citygml --filter="bldg.height > 1" 80 | ``` 81 | 82 | #### Advanced handling of namespaces and complex attributes 83 | 84 | In 3D CityDB, attributes may be defined with namespaces or at nested (child) levels. 85 | This advanced scenario requires careful handling: 86 | 87 | __Namespaces & Object Classes:__ 88 | Use a colon (:) to separate namespace prefixes from attribute names. For example, the object class Building might be 89 | referenced as bldg:Building. citydb-tool recognizes alias names for object classes, but incorrect casing or namespace 90 | mismatches can lead to errors since the system is extremely case sensitive. 91 | 92 | __Property Paths:__ 93 | Use dot (.) notation to define paths to nested attributes (e.g., bldg.details.height). While top-level attributes 94 | can be referenced with a simple name, lower-level or child attributes require explicit, fully qualified paths. 95 | 96 | __Multi-occurring Values:__ 97 | For attributes that occur multiple times (arrays), reference specific occurrences using list notation (e.g., property[1] 98 | for the first occurrence). Note: Indexing starts at 1 rather than 0. 99 | 100 | __Generic Attributes and Datatype Specification:__ 101 | When dealing with generic attributes (such as those in a property table) where the database does not infer the data type 102 | automatically, you may need to explicitly specify the expected datatype using a cast-like syntax (e.g., ::datatype similar 103 | to PostgreSQL conventions). 104 | 105 | For example, using the -t option to specify the feature type along with -f for the filter: 106 | 107 | ```bash 108 | citydb export citygml -t Building -f "bldg:height < 15" 109 | ``` 110 | 111 | Here, Building is the target object class (with its associated namespace alias), and bldg:height is the explicitly 112 | referenced attribute. This explicit approach minimizes ambiguity—especially important when attributes are defined on 113 | child levels or in complex structures. 114 | 115 | ### Attribute filtering 116 | 117 | Filter based on attribute values using comparison operators such as =, !=, <, <=, >, and >=. Logical operators 118 | AND, OR, and NOT can be used to combine conditions. 119 | 120 | #### Basic example 121 | 122 | === "Text-based Filter" 123 | 124 | ```bash 125 | citydb export citygml --filter="name = 'Forest tree 3'" -o filtered_tree.gml 126 | ``` 127 | 128 | === "JSON-based filter" 129 | 130 | ```json 131 | { 132 | "op": "=", 133 | "args": [ 134 | { "property": "name" }, 135 | "Forest tree 3" 136 | ] 137 | } 138 | ``` 139 | 140 | #### Combining with logical operators 141 | 142 | === "Text-based filter" 143 | 144 | === "Linux" 145 | ```bash 146 | citydb export citygml \ 147 | --filter="name = 'Forest tree 3' AND height > '1'" \ 148 | -o filtered_tree.gml 149 | ``` 150 | 151 | === "Windows CMD" 152 | 153 | ```bash 154 | citydb export citygml ^ 155 | --filter="name = 'Forest tree 3' AND height > '1'" ^ 156 | -o filtered_tree.gml 157 | ``` 158 | 159 | === "JSON-based filter" 160 | 161 | ```json 162 | { 163 | "op": "AND", 164 | "args": [ 165 | { 166 | "op": "=", 167 | "args": [ 168 | { "property": "name" }, 169 | "Forest tree 3" 170 | ] 171 | }, 172 | { 173 | "op": ">", 174 | "args": [ 175 | { "property": "height" }, 176 | "1" 177 | ] 178 | } 179 | ] 180 | } 181 | ``` 182 | 183 | #### Filtering with lists 184 | 185 | === "Text-based filter" 186 | 187 | === "Linux" 188 | 189 | ```bash 190 | citydb export citygml \ 191 | --filter="name IN ('Forest tree 1', 'Forest tree 2', 'Forest tree 3')" \ 192 | -o filtered_trees.gml 193 | ``` 194 | 195 | === "Windows CMD" 196 | 197 | ```bash 198 | citydb export citygml ^ 199 | --filter="name IN ('Forest tree 1', 'Forest tree 2', 'Forest tree 3')" ^ 200 | -o filtered_trees.gml 201 | ``` 202 | 203 | === "JSON-based filter" 204 | 205 | ```json 206 | { 207 | "op": "IN", 208 | "args": [ 209 | { "property": "name" }, 210 | ["Forest tree 1", "Forest tree 2", "Forest tree 3"] 211 | ] 212 | } 213 | ``` 214 | 215 | ### Spatial filtering 216 | 217 | Use spatial functions to filter based on the spatial relationship of geometries. Commonly used functions include: 218 | 219 | - `intersects`: Returns true if two geometries intersect. 220 | - `contains`: Returns true if one geometry contains another. 221 | - `within`: Returns true if one geometry is within another. 222 | 223 | #### Example 224 | 225 | === "Text-based filter" 226 | 227 | === "Linux" 228 | 229 | ```bash 230 | citydb export citygml \ 231 | --filter="S_INTERSECTS(Envelope, \ 232 | BBOX(-560.8678155819734, 604.1012795512906, \ 233 | -553.8099297783192, 627.1318523068805))" \ 234 | @options.txt -o=output.gml 235 | ``` 236 | === "Windows CMD" 237 | 238 | ```bash 239 | citydb export citygml ^ 240 | --filter="S_INTERSECTS(Envelope, ^ 241 | BBOX(-560.8678155819734, 604.1012795512906, ^ 242 | -553.8099297783192, 627.1318523068805))" ^ 243 | @options.txt -o=output.gml 244 | ``` 245 | === "JSON-based filter" 246 | 247 | ```json 248 | { 249 | "op": "func", 250 | "function": "S_INTERSECTS", 251 | "args": [ 252 | { "property": "Envelope" }, 253 | { 254 | "op": "func", 255 | "function": "BBOX", 256 | "args": [ 257 | -560.8678155819734, 258 | 604.1012795512906, 259 | -553.8099297783192, 260 | 627.1318523068805 261 | ] 262 | } 263 | ] 264 | } 265 | ``` 266 | -------------------------------------------------------------------------------- /docs/citydb-tool/database.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Database connection 3 | description: Options for connection to a 3DCityDB 4 | tags: 5 | - database 6 | - connection options 7 | - 3dcitydb 8 | --- 9 | 10 | Most citydb-tool commands require a connection to a 3DCityDB `v5` instance. Connection details can be specified via 11 | command-line options, argument files, JSON configuration files, or environment variables. 12 | 13 | ## Using command-line options 14 | 15 | --8<-- "docs/citydb-tool/includes/db-options.md" 16 | 17 | Use `--db-host` to specify the network name or IP address of the database server. The `--db-name` option 18 | defines the name of the 3DCityDB `v5` instance, while `--db-schema` sets the database schema to connect to. For 19 | PostgreSQL, the default schema is `citydb`. Additional schemas can be created using 20 | the [database scripts](../3dcitydb/db-scripts.md) included in the 3DCityDB `v5` software package. 21 | 22 | The username and password for connecting to the 3DCityDB are set with `--db-username` and `--db-password`. You can 23 | provide the password directly or leave it empty to be prompted for input before connecting. The prompt will time out 24 | after 60 seconds. If this option is omitted, citydb-tool will attempt to connect without a password. 25 | 26 | In addition to the standard connection parameters, database-specific properties can be provided through the 27 | `--db-property` option to configure the JDBC driver behavior. These properties should be specified as a comma-separated 28 | list of `property=value` pairs. 29 | 30 | The example below shows how to use the database connection options. It includes the PostgreSQL-specific `ssl` parameter to 31 | establish an SSL connection. 32 | 33 | === "Linux" 34 | 35 | ```bash 36 | ./citydb export citygml \ 37 | -H localhost \ 38 | -d citdb \ 39 | -u citydb_user \ 40 | -p mySecret \ 41 | --db-property=ssl=true \ 42 | -o output.gml 43 | ``` 44 | 45 | === "Windows CMD" 46 | 47 | ```bat 48 | citydb export citygml ^ 49 | -H localhost ^ 50 | -d citdb ^ 51 | -u citydb_user ^ 52 | -p mySecret ^ 53 | --db-property=ssl=true ^ 54 | -o output.gml 55 | ``` 56 | !!! tip 57 | Consult the database documentation for an overview of supported JDBC connection properties. For PostgreSQL, further 58 | details can be found [here](https://jdbc.postgresql.org/documentation/use/#connection-parameters){target="blank"}. 59 | 60 | ## Using configuration files 61 | 62 | citydb-tool supports loading options and settings from a JSON-encoded configuration file, as described 63 | [here](cli.md#configuration-files). The JSON structure for storing database connection options is illustrated below. 64 | 65 | ```json 66 | { 67 | "databaseOptions": { 68 | "connections": { 69 | "myFirstConnection": { 70 | "host": "localhost", 71 | "port": 5432, 72 | "database": "citydb", 73 | "schema": "citydb", 74 | "user": "citydb_user", 75 | "password": "mySecret", 76 | "properties": { 77 | "ssl": true 78 | }, 79 | "poolOptions": { 80 | "loginTimeout": 120 81 | } 82 | }, 83 | "mySecondConnection": { 84 | "host": "the.host.de", 85 | "database": "3dcitydb", 86 | "user": "citydb_user", 87 | "password": "mySecret" 88 | } 89 | }, 90 | "defaultConnection": "myFirstConnection" 91 | } 92 | } 93 | ``` 94 | 95 | Database connection options are defined in the `"databaseOptions"` object within the configuration file. The `"connections"` 96 | key contains one or more connection configurations, each identified by a unique, user-defined name. In the example 97 | above, `myFirstConnection` and `mySecondConnection` define connections to different 3DCityDB `v5` instances with distinct 98 | settings. The `"defaultConnection"` key specifies which connection to use. It can be omitted if only one connection 99 | is defined. 100 | 101 | Each connection can include the following properties, closely aligned with the corresponding command-line 102 | options: 103 | 104 | | Property | Description | Default value | 105 | |-----------------|----------------------------------------------------------------------|----------------------| 106 | | `"host"` | Name of the host on which the 3DCityDB is running. | | 107 | | `"port"` | Port of the 3DCityDB server. | 5432 | 108 | | `"database"` | Name of the 3DCityDB database to connect to. | | 109 | | `"schema"` | Schema to use when connecting to the 3DCityDB | `citydb` or username | 110 | | `"user"` | Username to use when connecting to the 3DCityDB. | | 111 | | `"password"` | Password to use when connecting to the 3DCityDB | | 112 | | `"properties"` | Database-specific connection properties provided as key-value pairs. | | 113 | | `"poolOptions"` | Connection pool options provided as key-value pairs. | | 114 | 115 | The `"poolOptions"` property is available only in the JSON configuration and is not exposed as a command-line option. It 116 | configures internal connection pool behavior. Currently, the only supported option is `"loginTimeout"`, which sets the 117 | maximum time (in seconds) to wait for a connection attempt before timing out (default: `60` seconds). Additional pool 118 | options may be added in future versions. 119 | 120 | You can use a configuration file as shown below. 121 | 122 | ```bash 123 | citydb export citygml --config-file=/path/to/config.json -o output.gml 124 | ``` 125 | 126 | !!! note 127 | Connection options from a configuration file can be used alongside command-line options, in which case command-line 128 | options take precedence. 129 | 130 | !!! warning 131 | Storing passwords in a configuration file in clear text may pose a security risk. Consider using an environment 132 | variable for the password instead, or leave the `--db-password` option empty to be prompted. 133 | 134 | ## Using argument files 135 | 136 | You can also store the database connection options in an argument file and reference it in the command using the `@` 137 | symbol. The contents of the argument file are automatically expanded into the argument list. For more information on 138 | using argument files, refer to the section [here](cli.md#argument-files). 139 | 140 | For example, suppose the following database options are stored in an `@-file` located at `/home/foo/db-args`: 141 | 142 | ```bash 143 | --db-host=localhost 144 | --db-port=5432 145 | --db-name=citdb 146 | --db-schema=citydb 147 | --db-username=citydb_user 148 | --db-password=mySecret 149 | --db-property=ssl=true 150 | ``` 151 | 152 | This `@-file` can then be used as shown below. 153 | 154 | ```bash 155 | citydb export citygml @/home/foo/db-args -o output.gml 156 | ``` 157 | 158 | !!! warning 159 | Storing passwords in an argument file in clear text may pose a security risk. Consider using an environment 160 | variable for the password instead, or leave the `--db-password` option empty to be prompted. 161 | 162 | ## Using environment variables 163 | 164 | Environment variables allow for dynamic definition of database connection details. This approach is useful for 165 | automated scripts, CI/CD pipelines, or when credentials should not be hard-coded. It is also ideal for running 166 | citydb-tool in Docker environments, where environment variables can be easily passed into containers at runtime. 167 | 168 | The following environment variables for defining database connection details are supported by citydb-tool and 169 | closely align with the command-line options: 170 | 171 | | Environment variable | Description | 172 | |----------------------|-----------------------------------------------------------------------------------------------------| 173 | | `CITYDB_HOST` | Name of the host on which the 3DCityDB is running. | 174 | | `CITYDB_PORT` | Port of the 3DCityDB server. | 175 | | `CITYDB_NAME` | Name of the 3DCityDB database to connect to. | 176 | | `CITYDB_SCHEMA` | Schema to use when connecting to the 3DCityDB. | 177 | | `CITYDB_USER` | Username to use when connecting to the 3DCityDB. | 178 | | `CITYDB_PASSWORD` | Password to use when connecting to the 3DCityDB. | 179 | | `CITYDB_CONN_PROPS` | Database-specific connection properties provided as comma-separated list of `property=value` pairs. | 180 | 181 | The following command demonstrates how to use these environment variables to dynamically specify database connection 182 | details. 183 | 184 | === "Linux" 185 | 186 | ```bash 187 | export CITYDB_HOST=localhost 188 | export CITYDB_PORT=5432 189 | export CITYDB_NAME=citdb 190 | export CITYDB_SCHEMA=citydb 191 | export CITYDB_USER=citydb_user 192 | export CITYDB_PASSWORD=mySecret 193 | export CITYDB_CONN_PROPS=ssl=true 194 | 195 | ./citydb export citygml -o output.gml 196 | ``` 197 | 198 | === "Windows CMD" 199 | 200 | ```bat 201 | set CITYDB_HOST=localhost 202 | set CITYDB_PORT=5432 203 | set CITYDB_NAME=citdb 204 | set CITYDB_SCHEMA=citydb 205 | set CITYDB_USER=citydb_user 206 | set CITYDB_PASSWORD=mySecret 207 | set CITYDB_CONN_PROPS=ssl=true 208 | 209 | citydb export citygml -o output.gml 210 | ``` 211 | 212 | !!! note 213 | Environment variables can be used alongside command-line options and configuration files. However, they have the lowest 214 | precedence and are overridden by these options. -------------------------------------------------------------------------------- /docs/citydb-tool/delete-config.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Delete configuration 3 | description: Description of the JSON delete configuration 4 | tags: 5 | - citydb-tool 6 | - delete 7 | - config 8 | --- 9 | 10 | The configuration settings for the `delete` command are shown below. 11 | 12 | !!! tip 13 | The names and purposes of the JSON properties align closely with their counterparts in the command-line options. Where 14 | applicable, the description of each JSON property links to the command-line option for more details. 15 | 16 | ```json 17 | { 18 | "deleteOptions": { 19 | "mode": "terminate", 20 | "terminateWithSubFeatures": true, 21 | "terminationDate": "2018-07-01T00:00:00", 22 | "lineage": "myLineage", 23 | "updatingPerson": "myUpdatingPerson", 24 | "reasonForUpdate": "myReasonForUpdate", 25 | "query": {...}, 26 | "validityOptions": {...} 27 | } 28 | } 29 | ``` 30 | 31 | ## General delete options 32 | 33 | |
Property
| Description | Default value | 34 | |-----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|---------------| 35 | | [`"mode"`](delete.md#delete-mode) | Delete mode: `delete`, `terminate`. | `terminate` | 36 | | ["terminateWithSub
Features"](delete.md#delete-mode) | Also terminate sub-features. | `true` | 37 | | [`"terminationDate"`](delete.md#defining-termination-metadata) | Time in `` or <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 | |
Property
| Description | Default value | 86 | |-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| 87 | | [`"featureTypes"`](delete.md#feature-type-filter) | Array of JSON objects specifying the features to process. Each object must include the `"name"` of the feature type. To avoid ambiguity, use the format `"prefix:name"` with a namespace alias or specify the full namespace using the `"namespace"` property. | | 88 | | [`"filter"`](delete.md#cql2-based-filtering) | A CQL2 filter expression, encoded as [CQL2 text or JSON](cql2.md). | | 89 | | [`"filterSrs"`](delete.md#cql2-based-filtering) | Specifies a CRS for filter geometries that differs from the 3DCityDB CRS. Use the `"srid"` or `"identifier"` property to define the filter CRS. | | 90 | | [`"countLimit"`](delete.md#count-filter) | The `"limit"` property sets the maximum number of features to delete, and the `"startIndex"` property defines the `0`-based index within the result set to delete from. | | 91 | 92 | ## Validity options 93 | 94 | The `"validityOptions"` property is a container object for filtering features based on their validity. 95 | 96 | ```json 97 | { 98 | "validityOptions": { 99 | "mode": "valid", 100 | "reference": "database", 101 | "at": "2018-07-01", 102 | "lenient": false 103 | } 104 | } 105 | ``` 106 | 107 | | Property | Description | Default value | 108 | |---------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------| 109 | | [`"mode"`](delete.md#deleting-historical-versions) | Process features by validity: `valid`, `invalid`, `all`. | `valid` | 110 | | [`"at"`](delete.md#deleting-historical-versions) | Check validity at a specific point in time. If provided, the time must be in `` or <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=` | CityGML version: `3.0`, `2.0`, `1.0`. | `3.0` | 43 | | `--[no-]pretty-print` | Format and indent output file. | `true` | 44 | | `-x`, --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=` | CityJSON version: `2.0`, `1.1`, `1.0`. | `2.0` | 45 | | `--[no-]json-lines` | Write output as CityJSON Text Sequence in JSON Lines format. This option requires CityJSON 1.1 or later. | `true` | 46 | | `--pretty-print` | Format and indent output file. | | 47 | | `--html-safe` | Write JSON that is safe to embed into HTML. | | 48 | | `--vertex-precision=` | Number of decimal places to keep for geometry vertices. | 3 | 49 | | `--template-precision=` | Number of decimal places to keep for template vertices. | 3 | 50 | | `--texture-vertex-precision=` | Number of decimal places to keep for texture vertices. | 7 | 51 | | `--[no-]transform-coordinates` | Transform coordinates to integer values when exporting in CityJSON 1.0. | `true` | 52 | | `--replace-templates` | Replace template geometries with real coordinates. | | 53 | | `--[no-]material-defaults` | Use CityGML default values for material properties. | `true` | 54 | 55 | ### Upgrade options for CityGML 2.0 and 1.0 56 | 57 | | Option | Description | Default value | 58 | |------------------------|---------------------------------------------------------|---------------| 59 | | `--use-lod4-as-lod3` | Use LoD4 as LoD3, replacing an existing LoD3. | | 60 | 61 | ### Query and filter options 62 | 63 | --8<-- "docs/citydb-tool/includes/export-filter-options.md" 64 | 65 | For more details on the query and filter options and usage hints, see [here](export.md#query-and-filter-options). 66 | 67 | ### Time-based feature history options 68 | 69 | --8<-- "docs/citydb-tool/includes/export-history-options.md" 70 | 71 | For more details on the time-based feature history options and usage hints, see [here](export.md#time-based-feature-history-options). 72 | 73 | ### Tiling options 74 | 75 | --8<-- "docs/citydb-tool/includes/export-tiling-options.md" 76 | 77 | For more details on the tiling options and usage hints, see [here](export.md#tiling-options). 78 | 79 | ### Database connection options 80 | 81 | --8<-- "docs/citydb-tool/includes/db-options.md" 82 | 83 | For more details on the database connection options and usage hints, see [here](database.md#using-command-line-options). 84 | 85 | ## Usage 86 | 87 | !!! tip 88 | For general usage hints applicable to all subcommands of the `export` command (including but not limited to 89 | `export cityjson`), refer to the documentation for the `export` command [here](export.md#usage). 90 | 91 | ### Specifying the CityJSON version 92 | 93 | The `export cityjson` command supports CityJSON versions 2.0, 1.1, and 1.0 as output formats. Use the `--cityjson-version` 94 | option to select a specific version for export (default: `2.0`). 95 | 96 | ### Streaming exports 97 | 98 | When exporting to CityJSON 2.0 and 1.1, the default output format 99 | is [CityJSON Text Sequence (CityJSONSeq)](https://www.cityjson.org/cityjsonseq/){target="blank"}, which efficiently 100 | supports streaming large exports. Features are exported in chunks as individual `CityJSONFeature` objects, with each 101 | object written to the output file on a separate line. This streaming approach improves memory efficiency, reduces storage 102 | requirements, and allows immediate access to the data as it is streamed. 103 | 104 | If the newline-delimited CityJSONSeq format is not preferred, streaming can be disabled using the 105 | `--no-json-lines` option. 106 | 107 | !!! note 108 | CityJSON 1.0 does not support CityJSONSeq or streaming. 109 | 110 | !!! warning 111 | Without streaming, the entire export must be loaded into memory before being written to the output file, which could 112 | quickly exceed system memory limits for large exports. In such cases, consider 113 | using [filters](export.md#querying-and-filtering) or [tiled exports](export.md#tiled-exports) to reduce the export size. 114 | 115 | ### Upgrading CityGML 2.0 and 1.0 116 | 117 | CityJSON does not support LoD4 representations of features as defined in CityGML 2.0 and 1.0. Therefore, if you have 118 | imported CityGML 2.0 or 1.0 data containing LoD4 geometries into your 3DCityDB `v5`, these geometries will be skipped 119 | by default when exporting to CityJSON. 120 | 121 | To address this, you can use the `--use-lod4-as-lod3` option to map LoD4 geometries to LoD3 during export. However, 122 | this will also overwrite any existing LoD3 representation of the features. 123 | 124 | ### Transforming coordinates 125 | 126 | CityJSON applies quantization to the coordinates of the geometry vertices to reduce file size. The coordinates are 127 | represented as integer values, with the scale factor and translation required to recover the original coordinates stored 128 | as separate `"transform"` property. 129 | 130 | Quantization is mandatory for CityJSON 2.0 and 1.1, but optional for CityJSON 1.0. By default, the `export cityjson` 131 | command uses quantization for CityJSON 1.0 as well, though it can be disabled using the `--no-transform-coordinates` 132 | option. 133 | 134 | ### Replacing template geometries 135 | 136 | CityJSON supports the CityGML concept of [implicit geometries](../3dcitydb/geometry-module.md#implicit_geometry-table), 137 | enabling template geometries to be defined and stored once in a CityJSON file and reused by multiple features. These 138 | template geometries are stored using local coordinates. Features that reference a template must provide both a reference 139 | point and a transformation matrix to convert the coordinates to real-world values and place the template correctly 140 | within the city model. 141 | 142 | If the target system consuming the CityJSON export cannot handle template geometries, the `--replace-templates` option can 143 | be used to replace them with real-world coordinates during export. 144 | 145 | !!! note 146 | Replacing templates will increase the file size and eliminate the benefits of reusing them. 147 | 148 | ### Suppressing material defaults 149 | 150 | By default, citydb-tool includes default values for material properties such as `"diffuseColor"`, `"emissiveColor"`, and 151 | `"ambientIntensity"` in the output file when specific values for these properties are missing in the database. 152 | These defaults are defined in the [CityGML Appearance model](https://docs.ogc.org/is/20-010/20-010.html#toc31) and help 153 | prevent issues with target systems that do not automatically apply them. 154 | 155 | You can use the `--no-material-defaults` option to suppress this behavior and omit the properties with default values, 156 | which also reduces the file size. 157 | 158 | ### Formatting the output 159 | 160 | The `export cityjson` command provides several options to format the CityJSON output: 161 | 162 | - `--vertex-precision`: Controls the number of decimal places retained for the coordinates of geometries. The coordinate 163 | values will be rounded to the specified number of decimal places (default: `3`). This option balances data accuracy 164 | with file size. More decimal places increase precision but may result in a larger file size. 165 | - `--template-precision`: Similar to `--vertex-precision`, but affects the number of decimal places for the coordinates 166 | of implicit geometries (default: `3`). 167 | - `--texture-vertex-precision`: Similar to `--vertex-precision`, but affects the number of decimal places for texture 168 | coordinates (default: `7`). 169 | - `--pretty-print`: Enhances readability by adding line breaks and indentation to clearly represent the hierarchy and 170 | nesting of JSON elements, but increases file size. 171 | - `--html-safe`: Escapes special characters in the CityJSON output for safe use in HTML contexts. 172 | 173 | !!! note 174 | The `--pretty-print` option cannot be used with streaming exports that use newline-delimited JSON. -------------------------------------------------------------------------------- /docs/citydb-tool/import-citygml.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Import CityGML command 3 | description: Importing CityGML data 4 | tags: 5 | - citydb-tool 6 | - CityGML 7 | - import 8 | --- 9 | 10 | # Import CityGML command 11 | 12 | The `import citygml` command imports one or more [CityGML files](https://www.ogc.org/publications/standard/citygml/) 13 | into the 3DCityDB `v5`. 14 | 15 | ## Synopsis 16 | 17 | ```bash 18 | citydb import citygml [OPTIONS] ... 19 | ``` 20 | 21 | ## Options 22 | 23 | The `import citygml` command inherits global options from the main [`citydb`](cli.md) command and general import, 24 | metadata, and filter options from its parent [`import`](import.md) command. Additionally, it provides CityGML 25 | format-specific import options. 26 | 27 | ### Global options 28 | 29 | --8<-- "docs/citydb-tool/includes/global-options.md" 30 | 31 | For more details on the global options and usage hints, see [here](cli.md#options). 32 | 33 | ### General import options 34 | 35 | --8<-- "docs/citydb-tool/includes/import-general-options.md" 36 | 37 | For more details on the general import options and usage hints, see [here](import.md#general-import-options). 38 | 39 | ### CityGML import options 40 | 41 | | Option | Description | Default value | 42 | |------------------------------------------------------------------------------|---------------------------------------------------------------------------|---------------| 43 | | `--import-xal-source` | Import XML snippets of xAL address elements. | | 44 | | `-x`, --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 `` input instead of a single file. 92 | In such cases, the directory or archive is recursively scanned for input files, which are identified using the 93 | extensions listed above and then processed for import. 94 | 95 | ### Upgrading CityGML 2.0 and 1.0 96 | 97 | CityGML data can be exported from the 3DCityDB `v5` in the same version as it was imported, without loss. However, 98 | switching CityGML versions between import and export may result in data loss, as CityGML 3.0 is not fully backward 99 | compatible with versions 2.0 and 1.0. While citydb-tool applies automatic conversions where possible, certain 100 | scenarios require user input. 101 | 102 | If CityGML 3.0 is the primary format for your 3DCityDB `v5` instance, the following upgrade options are 103 | available to resolve compatibility issues when importing CityGML 2.0 or 1.0 files: 104 | 105 | - `--use-lod4-as-lod3`: Converts LoD4 geometries to LoD3, replacing any existing LoD3. 106 | - `--map-lod0-roof-edge`: Converts LoD0 roof edge geometries into roof surface features. 107 | - `--map-lod1-surface`: Converts LoD1 multi-surfaces into generic thematic surface features. 108 | 109 | !!! note 110 | The upgrade options are not required if you only manage CityGML 2.0 and 1.0 data in your 3DCityDB `v5`. 111 | However, be cautious when importing CityGML 3.0 in this setup, as citydb-tool does not offer downgrade options. Any 112 | CityGML 3.0 content that cannot be automatically downgraded when exporting to CityGML 2.0 or 1.0 will be skipped. 113 | For more details, refer to the [compatibility and data migration](../compatibility.md) guide. 114 | 115 | ### Filtering CityGML features 116 | 117 | The `import citygml` command inherits [filtering options](import.md#filtering-features) from the parent `import` 118 | command. In the context of CityGML input files, the filters operate as follows: 119 | 120 | | Filter | Description | 121 | |----------------------------------------------------------------------|------------------------------------------------------------| 122 | | [Feature identifier filter](import.md#feature-identifier-filter) | Applies to the `gml:id` property of input features. | 123 | | [Bounding box filter](import.md#bounding-box-filter) | Applies to the `gml:boundedBy` property of input features. | 124 | 125 | !!! note 126 | Filters are applied to the top-level `` elements in the input file. Matching features 127 | are imported, including all their subfeatures. Filtering subfeatures is not supported. 128 | 129 | ### Filtering appearances 130 | 131 | By default, the `import citygml` command imports all appearance information from the input files. The 132 | `--appearance-theme` option restricts the import of appearances based on their `` property. You can specify one 133 | or more themes as a comma-separated list. To filter appearances that have no theme property, use `none` as the value. 134 | 135 | Only appearances associated with the specified themes will be imported. To exclude all appearances from the import, use 136 | the `--no-appearances` option. 137 | 138 | ### Applying XSL transformations 139 | 140 | XSLT stylesheets enable the on-the-fly transformation of CityGML input data before it is imported into the database. 141 | This allows you to modify or restructure the data to meet specific needs, such as changing values, filtering attributes, 142 | or removing and replacing entire GML/XML structures. 143 | 144 | The `--xsl-transform` option specifies one or more XSLT stylesheets to be applied to the input files. Each stylesheet must 145 | be referenced by its filename and path, which can be either absolute or relative to the current directory. Multiple XSLT 146 | stylesheets can be listed, separated by commas, to facilitate a multi-step transformation process. In this case, the 147 | stylesheets are executed in the specified order, with the output of one stylesheet serving as the input for the next. 148 | 149 | === "Linux" 150 | 151 | ```bash 152 | ./citydb import citygml [...] my-city.gml \ 153 | --xsl-transform=my-first-stylesheet.xsl,my-second-stylesheet.xsl 154 | ``` 155 | 156 | === "Windows CMD" 157 | 158 | ```bat 159 | citydb import citygml [...] my-city.gml ^ 160 | --xsl-transform=my-first-stylesheet.xsl,my-second-stylesheet.xsl 161 | ``` 162 | 163 | !!! note 164 | - To handle large input files, citydb-tool chunks each CityGML file into top-level features, which are then imported 165 | into the database. As a result, each XSLT stylesheet operates on individual top-level features, not the entire file. 166 | Keep this in mind when developing your XSLT. 167 | - The output of each XSLT stylesheet must be valid CityGML. 168 | 169 | ### Storing xAL address elements 170 | 171 | CityGML uses the [OASIS Extensible Address Language (xAL)](https://docs.oasis-open.org/ciq/v3.0/specs/ciq-specs-v3.html) 172 | standard to encode address data. During import, citydb-tool parses the xAL content and maps it to the separate columns 173 | of the [`ADDRESS`](../3dcitydb/feature-module.md#address-table) table, which provides a comprehensive and flexible 174 | structure for storing address data. However, if the original xAL address element is too complex to be fully mapped to 175 | the `ADDRESS` table columns, the `--import-xal-source` option allows importing and retaining the original xAL element. 176 | For more details, see [here](../3dcitydb/feature-module.md#address-table). -------------------------------------------------------------------------------- /docs/citydb-tool/import-cityjson.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Import CityJSON command 3 | description: Importing CityJSON data 4 | tags: 5 | - citydb-tool 6 | - CityJSON 7 | - import 8 | --- 9 | 10 | # Import CityJSON command 11 | 12 | The `import cityjson` command imports one or more [CityJSON files](https://www.cityjson.org/) into the 3DCityDB `v5`. 13 | 14 | ## Synopsis 15 | 16 | ```bash 17 | citydb import cityjson [OPTIONS] ... 18 | ``` 19 | 20 | ## Options 21 | 22 | The `import cityjson` command inherits global options from the main [`citydb`](cli.md) command and general import, 23 | metadata, and filter options from its parent [`import`](import.md) command. Additionally, it provides CityJSON 24 | format-specific import 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 import options 33 | 34 | --8<-- "docs/citydb-tool/includes/import-general-options.md" 35 | 36 | For more details on the general import options and usage hints, see [here](import.md#general-import-options). 37 | 38 | ### CityJSON import options 39 | 40 | | Option | Description | Default value | 41 | |-----------------------------------------------------------------------|---------------------------------------------------------------------------|---------------| 42 | | `--[no-]map-unknown-objects` | Map city objects from unsupported extensions onto generic city objects. | `true` | 43 | | `--no-appearances` | Do not process appearances. | | 44 | | `-a`, --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 `` input instead of a single file. 86 | In such cases, the directory or archive is recursively scanned for input files, which are identified using the 87 | extensions listed above and then processed for import. 88 | 89 | ### Filtering CityJSON features 90 | 91 | The `import cityjson` command inherits [filtering options](import.md#filtering-features) from the parent `import` 92 | command. In the context of CityJSON input files, the filters operate as follows: 93 | 94 | | Filter | Description | 95 | |------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 96 | | [Feature identifier filter](import.md#feature-identifier-filter) |
  • Regular CityJSON files: Applies to the `key` in the `"CityObjects"` collection.
  • CityJSONSeq files: Applies to the `"id"` property of `"CityJSONFeature"` objects.
| 97 | | [Bounding box filter](import.md#bounding-box-filter) | Applies to the `"geographicalExtent"` property of input features. | 98 | 99 | !!! note 100 | Filters are applied to the 1st-level city objects in the input file. Matching city objects are imported, including all 101 | their 2nd-level city objects. Filtering 2nd-level city objects is not supported. 102 | 103 | ### Filtering appearances 104 | 105 | By default, the `import cityjson` command imports all appearance information from the input files. The 106 | `--appearance-theme` option restricts the import of appearances based on their `"theme"` property. You can specify one 107 | or more themes as a comma-separated list. To filter appearances that have no theme property, use `none` as the value. 108 | 109 | Only appearances associated with the specified themes will be imported. To exclude all appearances from the import, use 110 | the `--no-appearances` option. 111 | 112 | ### Handling unknown extensions 113 | 114 | CityJSON provides a flexible extension mechanism similar to CityGML Application Domain Extensions (ADE). This mechanism 115 | allows the addition of new feature attributes and feature types not covered by the CityJSON specification. If a dataset 116 | contains extensions that are not registered in the 3DCityDB `v5`, citydb-tool handles them as follows: 117 | 118 | - Unknown attributes are mapped to generic attributes and stored in the database. 119 | - Unknown feature types are mapped to generic city objects in the database. This default behavior can be 120 | suppressed using the `--no-map-unknown-objects` option, which will prevent unknown feature types from being imported. 121 | 122 | !!! tip 123 | To import CityJSON extensions as defined, the corresponding type definitions have to be registered in the 124 | [`OBJECTCLASS`](../3dcitydb/metadata-module.md#objectclass-table) and 125 | [`DATATYPE`](../3dcitydb/metadata-module.md#datatype-table) metadata tables of the 3DCityDB `v5`. Additionally, a 126 | corresponding extension module must be loaded for citydb-tool to correctly parse and import the extensions. -------------------------------------------------------------------------------- /docs/citydb-tool/includes/db-options.md: -------------------------------------------------------------------------------- 1 | | Option | Description | Default value | 2 | |------------------------------------------------------------------------------|------------------------------------------------------------------------------|----------------------| 3 | | `-H`, `--db-host=` | Name of the host on which the 3DCityDB is running. | | 4 | | `-P`, `--db-port=` | Port of the 3DCityDB server. | 5432 | 5 | | `-d`, `--db-name=` | Name of the 3DCityDB database to connect to. | | 6 | | `-S`, `--db-schema=` | Schema to use when connecting to the 3DCityDB. | `citydb` or username | 7 | | `-u`, `--db-username=` | Username to use when connecting to the 3DCityDB. | | 8 | | `-p`, --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=` | Filter to apply when retrieving features. Use the extended CQL2 filtering language of the 3DCityDB. | | 5 | | `--filter-crs=` | SRID or identifier of the CRS to use for geometries in the filter expression. | 3DCityDB CRS | 6 | | `--sql-filter=` | SQL query expression to use as filter. | | 7 | | `-s`, --sort-by=<property[+|-]>
[,<property[+|-]>...] | Properties and sort orders for sorting features. | | 8 | | `--limit=` | Maximum number of features to process. | | 9 | | `--start-index=` | Index within the input set from which features are processed. | | 10 | | `-l`, --lod=<lod>
[,<lod>...] | Export geometries with a matching LoD. | | 11 | | `--lod-mode=` | LoD filter mode: `or`, `and`, `minimum`, `maximum`. | `or` | 12 | | --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=` | Name of the output file. | | 4 | | `--output-encoding=` | Encoding to use for the output file. | | 5 | | `--fail-fast` | Fail fast on errors. | | 6 | | `--temp-dir=` | Store temporary files in this directory. | | 7 | | `--threads=` | Number of threads to use for parallel processing. | | 8 | | `--crs=` | SRID or identifier of the CRS to use for the coordinates of geometries. | 3DCityDB CRS | 9 | | `--crs-name=` | Name of the CRS to use in the output file. | | 10 | | --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=` | Process features by validity: `valid`, `invalid`, `all`. | `valid` | 4 | | `-T`, `--validity-at=