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.

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": {...}
  }
}
1 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.

"useAbsoluteResourcePaths"

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"
        }
      ]
    }
  }
}
1 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.
2 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 VCDB 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": {...}
  }
}
1 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 VCDB 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.

  • Dimension

  • Matrix

{
  "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.

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",
    "skipEmptyTiles": false,
    "metadataOptions": {...},
    "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.

"skipEmptyTiles"

Skip tile files containing no exported features.

false

"metadataOptions"

Metadata options for the output files.

Metadata options

The "metadataOptions" property is a container object for adding metadata to output files. Each metadata property is added only if supported by the selected output format. If "computeExtent" is enabled, the extent is computed from all features exported to the respective output file.

{
  "metadataOptions": {
    "title": "My dataset title",
    "description": "My dataset description",
    "computeExtent": true
  }
}
Property Description Default value

"title"

Title to add to the output file.

"description"

Description to add to the output file.

"computeExtent"

Compute and add the extent of exported features to the output file.

false

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"
    ],
    "prefixes": {
      "http://www.opengis.net/citygml/3.0": "core",
      "http://www.opengis.net/citygml/building/3.0": "bldg"
    },
    "schemaLocations": {
      "http://www.opengis.net/citygml/3.0": "/path/to/citygml.xsd",
      "http://www.opengis.net/citygml/building/3.0": "/path/to/building.xsd"
    },
    "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.

"prefixes"

Map namespace URIs to XML prefixes.

"schemaLocations"

Map namespace URIs to schema locations.

"useLod4AsLod3"

Use LoD4 as LoD3, replacing an existing LoD3.

false

"mapLod0RoofEdge"

Map LoD0 roof edges onto roof surfaces.

false

"mapLod1MultiSurfaces"

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

"replaceTemplateGeometries"

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

"writeGenericAttributeTypes"

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