Skip to content

Commit ca00730

Browse files
clausnagelclausnagel
committed
added JSON config documentation
1 parent 0886579 commit ca00730

File tree

7 files changed

+707
-4
lines changed

7 files changed

+707
-4
lines changed

‎docs/3dcitydb/geometry-module.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ the outer shell formed by the polygons. Moreover, the solid, the composite surfa
160160
identifier that allows the reuse of the component and the assignment of textures or colors. The following JSON object
161161
encodes this extra metadata and links it to the `POLYHEDRALSURFACE Z` representation:
162162

163-
```javascript
163+
```json
164164
{
165165
"type": 9, // (1)!
166166
"objectId": "mySolid",

‎docs/citydb-tool/.pages

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,5 +12,10 @@ nav:
1212
- CityJSON export: export-cityjson.md
1313
- delete.md
1414
- 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
1520
- cql2.md
1621
- docker.md

‎docs/citydb-tool/cli.md

Lines changed: 17 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -97,9 +97,23 @@ Log messages can also be recorded in a log file specified with the `--log-file`
9797
### Configuration files
9898

9999
Options and settings for executing a citydb-tool command can also be loaded from a JSON-encoded configuration file
100-
specified with `--config-file`. Each CLI command defines its own JSON structure, so refer to the respective command's
101-
documentation for details. Configuration files override default settings and can be used alongside command-line options
102-
for flexibility. However, command-line options always take precedence.
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+
```
103117

104118
!!! note
105119
Some commands may provide options exclusively in the JSON configuration, without corresponding command-line options.

‎docs/citydb-tool/config.md

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
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+
The purpose of each configuration section is outlined below. Their content and usage for different citydb-tool commands are
34+
explained in more detail in the following chapters.
35+
36+
| <div style="width:130px;">Section</div> | Description |
37+
|--------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
38+
| [`"databaseOptions"`](database.md#using-configuration-files) | Defines connection details for one or more 3DCityDB instances, usable by all commands that require a database connection. |
39+
| [`"importOptions"`](import-config.md#import-options) | Defines options for controlling the import process. |
40+
| [`"readOptions"`](import-config.md#read-options) | Specifies settings for reading input files, including format-specific options. |
41+
| [`"exportOptions"`](export-config.md#export-options) | Defines options for controlling the export process. |
42+
| [`"writeOptions"`](export-config.md#write-options) | Specifies settings for writing output files, including format-specific options. |
43+
| [`"deleteOptions"`](delete-config.md) | Defines options for controlling the delete process. | |
44+
45+
You can load configuration files using the [`--config-file`](cli.md#configuration-files) option when executing
46+
citydb-tool commands.
47+
48+
=== "Linux"
49+
50+
```bash
51+
./citydb import citygml \
52+
--config-file=/path/to/my-config.json \
53+
my-city.gml
54+
```
55+
56+
=== "Windows CMD"
57+
58+
```bat
59+
citydb import citygml ^
60+
--config-file=C:\path\to\my-config.json ^
61+
my-city.gml
62+
```
63+
64+
!!! tip
65+
- Configuration files can be used alongside command-line options for flexibility. However, command-line options always
66+
take precedence.
67+
- Some commands may provide options exclusively in the JSON configuration, without corresponding command-line options.
68+
- If [plugins](cli.md#plugins) are registered for citydb-tool, they may extend the configuration by adding their
69+
own sections.

‎docs/citydb-tool/delete-config.md

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
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+
| <div style="width:130px;">Property</div> | Description | Default value |
34+
|-----------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|---------------|
35+
| [`"mode"`](delete.md#delete-mode) | Delete mode: `delete`, `terminate`. | `terminate` |
36+
| [<code>"terminateWithSub<br/>Features"</code>](delete.md#delete-mode) | Also terminate sub-features. | `true` |
37+
| [`"terminationDate"`](delete.md#defining-termination-metadata) | Time in `<YYYY-MM-DD>` or <code>&lt;YYYY-MM-DDThh&#58;mm:ss[(+&#124;-)hh:mm]></code> 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 import. | 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+
| <div style="width:110px;">Property</div> | 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 export, and the `"startIndex"` property defines the `0`-based index within the result set to export. | |
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 `<YYYY-MM-DD>` or <code>&lt;YYYY-MM-DDThh&#58;mm:ss[(+&#124;-)hh:mm]></code> 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` |

0 commit comments

Comments
 (0)