Export configuration

The configuration settings for the export command are divided into "exportOptions" for general export settings and "writeOptions" for output file settings and format-specific options.

Tip

The names and purposes of the JSON properties align closely with their counterparts in the command-line options. Where applicable, the description of each JSON property links to the command-line option for more details.

Export options¶

The example below illustrates the JSON structure for the export options.

{
  "exportOptions": {
    "numberOfThreads": 4,
    "useAbsoluteResourcePaths": false,
    "targetSrs": { // (1)!
      "srid": 4326,
      "identifier": "http://www.opengis.net/def/crs/EPSG/0/4326"
    },
    "affineTransform": [0.0,1.0,0.0,0.0,1.0,0.0,0.0,0.0,0.0,0.0,1.0,0.0],
    "lodOptions": {
      "lods": ["2","3"],
      "mode": "minimum"
    },
    "appearanceOptions": {
      "exportAppearances": true,
      "themes": ["foo","bar"],
      "numberOfTextureBuckets": 10
    },
    "query": {...},
    "validityOptions": {...},
    "tiling": {...}
  }
}

Use either "srid", "identifier", or both to define the target CRS.

General export options¶

Property	Description	Default value
`"numberOfThreads"`	Number of threads to use for parallel processing.
`"useAbsoluteResource Paths"`	Use absolute paths to reference external resources, such as texture images and library objects. Paths are OS-specific and may break on a different OS.	`false`
`"targetSrs"`	Specifies the CRS for reprojecting geometries during export. Use the `"srid"` or `"identifier"` property to define the target CRS.
`"affineTransform"`	Transform coordinates using a 3x4 matrix in row-major order. The matrix coefficients are represented as array.
`"lodOptions"`	Defines an `"lods"` array and a `"mode"` to specify whether to `"keep"` (default), `"remove"`, or keep only the `"minimum"` or `"maximum"` matching LoD representation of each feature.
`"appearanceOptions"`	The `"themes"` array restricts the export of appearances based on their `theme` property. To exclude all appearances, set the `"exportAppearances"` property to `false` (default: `true`). Use the `"numberOfTextureBuckets"` property to organize exported texture images into subfolders (default: `0`).

Query options¶

The "query" property is a container object for the following query and filtering options.

{
  "query": {
    "featureTypes": [ // (1)!
      {
        "name": "bldg:Building"
      },
      {
        "name": "Road",
        "namespace": "http://3dcitydb.org/3dcitydb/transportation/5.0"
      }
    ],
    "filter": {
      "op": "s_intersects",
      "args": [
        {
          "property": "core:envelope"
        },
        {
          "bbox": [10.0,10.0,20.0,20.0]
        }
      ]
    },
    "filterSrs": { // (2)!
      "srid": 4326,
      "identifier": "http://www.opengis.net/def/crs/EPSG/0/4326"
    },
    "countLimit": {
      "limit": 1000,
      "startIndex": 20
    },
    "lodFilter": {
      "lods": ["2","3"],
      "mode": "or",
      "searchDepth": 1
    },
    "sorting": {
      "sortBy": [
        {
          "property": "core:objectId",
          "sortOrder": "desc"
        }
      ]
    }
  }
}

The "name" property is mandatory. To avoid ambiguity, use the format "prefix:name" with a namespace alias as prefix or specify the full namespace using the "namespace" property.
Use either "srid", "identifier", or both to define the target CRS.

Property	Description	Default value
`"featureTypes"`	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 as prefix or specify the full namespace using the `"namespace"` property.
`"filter"`	A CQL2 filter expression, encoded as CQL2 text or JSON.
`"filterSrs"`	Specifies a CRS for filter geometries that differs from the 3DCityDB CRS. Use the `"srid"` or `"identifier"` property to define the filter CRS.
`"countLimit"`	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 from.
`"lodFilter"`	Defines an `"lods"` array and a `"mode"` to filter features based on LoD: `"or"` (default) requires any matching LoD, while `"and"` requires all. The `"searchDepth"` sets the number of subfeature levels to search for a matching LoD (default: `0`).
`"sorting"`	Array of `"sortBy"` objects to sort the output by a `"property"` (specified as a JSON path) in the given `"sortOrder"`: `"asc"` (default) or `"desc"`.

Validity options¶

The "validityOptions" property is a container object for filtering features based on their validity.

{
  "validityOptions": {
    "mode": "valid",
    "reference": "database",
    "at": "2018-07-01",
    "lenient": false
  }
}

Property	Description	Default value
`"mode"`	Process features by validity: `valid`, `invalid`, `all`.	`valid`
`"at"`	Check validity at a specific point in time. If provided, the time must be in `<YYYY-MM-DD>` or `<YYYY-MM-DDThh:mm:ss[(+\|-)hh:mm]>` format.
`"reference"`	Validity time reference: `database`, `realWorld`.	`database`
`"lenient"`	Ignore incomplete validity intervals of features.	`false`

Tiling options¶

The "tiling" property is a container object for defining tiled exports.

{
  "tiling": {
    "extent": {
      "coordinates": [10.0,10.0,20.0,20.0],
      "srs": { // (1)!
        "srid": 4326,
        "identifier": "http://www.opengis.net/def/crs/EPSG/0/4326"
      }
    },
    "tileMatrixOrigin": "topLeft",
    "scheme": {...}
  }
}

Use either "srid", "identifier", or both to define the target CRS.

Property	Description	Default value
`"extent"`	Defines a 2D bounding box as tiling extent using a `"coordinates"` array for the lower-left and upper-right corners. If the coordinates differ from the 3DCityDB CRS, a different `"srs"` can be specified with `"srid"` or `"identifier"` property.	`auto-computed`
`"tileMatrixOrigin"`	Tile indexes origin: `topLeft`, `bottomLeft`.	`topLeft`

The "scheme" property is an object that defines the tiling scheme, with the "type" property indicating the specific scheme being used.

DimensionMatrix

{
  "scheme": {
    "type": "Dimension",
    "width": {
      "value": 2.0,
      "unit": "km"
    },
    "height": {
      "value": 2.0,
      "unit": "km"
    }
  }
}

Property	Description	Default value
`"type"`	`"Dimension"` (fixed).
`"width"`	Specifies the width of each tile using the `"value"` property. If the `"unit"` is omitted, the database CRS unit is used.
`"height"`	Specifies the height of each tile using the `"value"` property. If the `"unit"` is omitted, the database CRS unit is used.

{
  "scheme": {
    "type": "Matrix",
    "columns": 10,
    "rows": 20
  }
}

Property	Description	Default value
`"type"`	`"Matrix"` (fixed).
`"columns"`	Specifies the number of `columns` for the resulting grid.	`1`
`"rows"`	Specifies the number of `rows` for the resulting grid.	`1`

Write options¶

The JSON structure for storing write options is shown below. Format-specific settings are provided within the "formatOptions" container object, with the output format name used as the key for the corresponding settings.

Tip

You only need to provide format-specific options for the file format that matches your output files.

{
  "writeOptions": {
    "failFast": false,
    "numberOfThreads": 4,
    "tempDirectory": "/path/to/temp",
    "encoding": "UTF-8",
    "srsName": "http://www.opengis.net/def/crs/EPSG/0/25832",
    "formatOptions": {
      "CityGML": {...},
      "CityJSON": {...}
    }
  }
}

General write options¶

Property	Description	Default value
`"failFast"`	Fail fast on errors.	`false`
`"numberOfThreads"`	Number of threads to use for parallel processing.
`"tempDirectory"`	Store temporary files in this directory.
`"encoding"`	Encoding to use for the output file.
`"srsName"`	Name of the CRS to use in the output file.

CityGML options¶

The "CityGML" property is a container object for CityGML-specific format options.

{
  "CityGML": {
    "version": "3.0",
    "prettyPrint": true,
    "addressMode": "columnsFirst",
    "xslTransforms": [
      "/path/to/myFirstStylesheet.xsl",
      "/path/to/mySecondStylesheet.xsl"
    ],
    "useLod4AsLod3": false,
    "mapLod0RoofEdge": false,
    "mapLod1MultiSurfaces": false
  }
}

Property	Description	Default value
`"version"`	CityGML version: `3.0`, `2.0`, `1.0`.	`3.0`
`"prettyPrint"`	Format and indent output file.	`true`
`addressMode`	Specifies how to construct addresses based on the `ADDRESS` table: `columnsOnly`: Use only structured address fields. `columnsFirst`: Prefer structured columns; fall back to `content` blob. `xalSourceOnly`: Use only the address blob stored in the `content` column. `xalSourceFirst`: Prefer the `content` blob; fall back to structured columns.	`columnsFirst`
`"xslTransforms"`	An array of XSLT stylesheets to transform the output, referenced by filename and path (absolute or relative). The stylesheets are applied in the specified order.
`"useLod4AsLod3"`	Use LoD4 as LoD3, replacing an existing LoD3.	`false`
`"mapLod0RoofEdge"`	Map LoD0 roof edges onto roof surfaces.	`false`
`"mapLod1Multi Surfaces"`	Map LoD1 multi-surfaces onto generic thematic surfaces.	`false`

CityJSON options¶

The "CityJSON" property is a container object for CityJSON-specific format options.

{
  "CityJSON": {
    "version": "2.0",
    "jsonLines": true,
    "prettyPrint": false,
    "htmlSafe": false,
    "vertexPrecision": 3,
    "templatePrecision": 3,
    "textureVertexPrecision": 7,
    "transformCoordinates": true,
    "replaceTemplateGeometries": false,
    "useMaterialDefaults": true,
    "fallbackTheme": "unnamed",
    "useLod4AsLod3": false,
    "writeGenericAttributeTypes": false
  }
}

Property	Description	Default value
`"version"`	CityJSON version: `2.0`, `1.1`, `1.0`.	`2.0`
`"jsonLines"`	Write output as CityJSON Sequence in JSON Lines format. This option requires CityJSON 1.1 or later. If both `jsonLines` and `prettyPrint` are enabled, `jsonLines` takes precedence and output will not be pretty-printed. Automatically set to `false` for CityJSON 1.0.	`true`
`"prettyPrint"`	Format and indent output file.	`false`
`"htmlSafe"`	Write JSON that is safe to embed into HTML.	`false`
`"vertexPrecision"`	Number of decimal places to keep for geometry vertices.	3
`"templatePrecision"`	Number of decimal places to keep for template vertices.	3
`"textureVertexPrecision"`	Number of decimal places to keep for texture vertices.	7
`"transformCoordinates"`	Transform coordinates to integer values when exporting in CityJSON 1.0.	`true`
`"replaceTemplate Geometries"`	Replace template geometries with real coordinates.	`false`
`"useMaterialDefaults"`	Name of the CRS to use in the output file.	`true`
`"fallbackTheme"`	Defines the fallback theme used when the `theme` property is missing from the database.	`unnamed`
`"writeGenericAttribute Types"`	Adds an extra root property to the CityJSON output that lists generic attributes along with the CityGML data types.	`false`
`useLod4AsLod3`	Use LoD4 as LoD3, replacing an existing LoD3.	`false`