Info command

The info command generates a comprehensive summary of a 3DCityDB v5 instance, providing key details about the data sored in the database, including available feature types, Levels of Detail (LoDs), feature and geometry counts, appearance information, generic attributes, the spatial extent of all features, and database metadata such as the coordinate reference system (CRS).

By default, the command prints a human-readable report to the console, but the same information can also be output in JSON format for automated workflows or programmatic use.

Synopsis¶

citydb info [OPTIONS]

Options¶

The info command inherits global options from the main citydb command. Additionally, it defines report and output options.

Global options¶

Option	Description	Default value
`[@<filename>...]`	One or more argument files containing options.
`-h`, `--help`	Show a help message and exit.
`-V`, `--version`	Print version information and exit.
`--config-file=<file>`	Load configuration from this file.
`-L`, `--log-level=<level>`	Log level: `fatal`, `error`, `warn`, `info`, `debug`, `trace`.	`info`
`--log-file=<file>`	Write log messages to this file.
`--quiet`	Disable console log messages.
`--pid-file=<file>`	Create a file containing the process ID.
`--plugins=<dir>`	Load plugins from this directory.
`--use-plugin=<plugin[=true\|false]> [,<plugin[=true\|false]>...]`	Enable or disable plugins with a matching fully qualified class name.	`true`

For more details on the global options and usage hints, see here.

Report options¶

Option	Description	Default value
`-o`, `--output=<file\|->`	Write output as a JSON file. Use `-` for `stdout`.
`--threads=<threads>`	Number of threads to use for parallel processing.	4
`-s`, `--feature-scope=<scope>`	Feature scope: `all`, `active`. For `active`, only properties of non-terminated features are considered.	`all`
`--include-generic-attributes`	Include generic attributes and their data types.
`--include-size-metrics`	Include database size metrics.

Database connection options¶

Option	Description	Default value
`-H`, `--db-host=<host>`	Name of the host on which the 3DCityDB is running.
`-P`, `--db-port=<port>`	Port of the 3DCityDB server.	5432
`-d`, `--db-name=<database>`	Name of the 3DCityDB database to connect to.
`-S`, `--db-schema=<schema>`	Schema to use when connecting to the 3DCityDB.	`citydb` or username
`-u`, `--db-username=<user>`	Username to use when connecting to the 3DCityDB.
`-p`, `--db-password [=<password>]`	Password to use when connecting to the 3DCityDB. Leave empty to be prompted.
`--db-property=<property=value> [,<property=value>...]`	Database-specific connection properties.

For more details on the database connection options and usage hints, see here.

Usage¶

Generating a database report¶

A database report is generated by executing the info command with the connection details of the target 3DCityDB v5 instance.

LinuxWindows CMD

./citydb info \
    -H localhost \
    -d citdb \
    -u citydb_user \
    -p mySecret

citydb info ^
    -H localhost ^
    -d citdb ^
    -u citydb_user ^
    -p mySecret

Note

The time required to generate a report depends on the size of the database. Reports are generally much faster to compute when indexes are enabled. If indexes are disabled, report generation may take considerably longer. Use the index command to check the current status of indexes and enable them as needed.

The report is displayed on the console in a human-readable format. It can also be generated in machine-readable JSON using the --output option. If a file path is provided for --output, the JSON report will be written to that file. If - is specified instead of a file path, the JSON report will be written to stdout. This JSON report can be easily piped to and processed by external tools.

The following examples demonstrate the usage of the --output option.

LinuxWindows CMD

./citydb info [...] -o report.json      # write JSON to a file
./citydb info [...] -o -                # write JSON to stdout
./citydb info [...] -o - > report.json  # redirect stdout to a file

citydb info [...] -o report.json      # write JSON to a file
citydb info [...] -o -                # write JSON to stdout
citydb info [...] -o - > report.json  # redirect stdout to a file

Report contents¶

The following example shows the structure of a JSON report generated by the info command. The human-readable version of the report printed to the console contains the same information in a more concise form.

{
  "metadata": {
    "generatedAt": "2025-08-21T07:51:40Z",
    "featureScope": "all",
    "genericAttributesProcessed": false
  },
  "summary": {
    "topLevelFeatures": [
      "bldg:Building"
    ],
    "lods": [
      "2",
      "3"
    ],
    "themes": [
      "Photovoltaic Potential",
      "Solar Thermal Potential",
      "rgbTexture"
    ],
    "crs": {
      "srid": 25833,
      "identifier": "urn:ogc:def:crs:EPSG::25833",
      "name": "ETRS89 / UTM zone 33N"
    },
    "extent": [
      778260.4775,
      5809001.5376,
      -703.348,
      823412.6066,
      5844145.0696,
      405.5
    ],
    "wgs84Extent": [
      19.087075,
      52.335758,
      19.782079,
      52.675649
    ]
  },
  "database": {
    "name": "3D City Database",
    "version": "5.1.0",
    "dbms": {
      "name": "PostgreSQL",
      "version": "17.2",
      "properties": {
        "postgis": {
          "name": "PostGIS",
          "value": "3.5.0"
        },
        "postgis_sfcgal": {
          "name": "SFCGAL",
          "value": "n/a"
        }
      }
    },
    "hasChangelogEnabled": false,
    "connection": {
      "host": "localhost",
      "port": 5432,
      "database": "citydb",
      "schema": "citydb",
      "user": "citydb_user"
    }
  },
  "features": {
    "featureCount": {
      "active": 3476418,
      "terminated": 0
    },
    "topLevelFeatureCount": {
      "active": 539247,
      "terminated": 0
    },
    "byType": {
      "bldg:Building": {
        "active": 539247,
        "terminated": 0
      },
      "con:GroundSurface": {
        "active": 547284,
        "terminated": 0
      },
      "con:RoofSurface": {
        "active": 763994,
        "terminated": 0
      },
      "con:WallSurface": {
        "active": 1625893,
        "terminated": 0
      }
    }
  },
  "geometries": {
    "geometryCount": 3011975,
    "implicitGeometryCount": 0,
    "byType": {
      "core:MultiSurface": 2937193,
      "core:Solid": 74782
    },
    "byLod": {
      "2": 3011738,
      "3": 7
    }
  },
  "addresses": {
    "addressCount": 586034
  },
  "appearances": {
    "appearanceCount": 1617618,
    "hasGlobalAppearances": false,
    "hasMaterials": true,
    "hasTextures": true,
    "hasGeoreferencedTextures": false,
    "byTheme": {
      "Photovoltaic Potential": 539247,
      "Solar Thermal Potential": 539247,
      "rgbTexture": 539247
    }
  },
  "extensions": [],
  "codeLists": {},
  "modules": {
    "bldg": "http://3dcitydb.org/3dcitydb/building/5.0",
    "con": "http://3dcitydb.org/3dcitydb/construction/5.0",
    "core": "http://3dcitydb.org/3dcitydb/core/5.0"
  }
}

The JSON report is structured into sections, each summarizing a specific aspect of the database. The table below provides an overview and description of these sections.

Section	Description
`metadata`	General information about the report, including the timestamp of generation, the scope of features considered, and whether generic attributes were processed.
`summary`	High-level overview of the database content, including top-level feature, available LoDs, appearance themes, CRS information, and spatial extent in both the database CRS and WGS84 coordinates.
`database`	Information about the connected database, including name and version, DBMS details including available extensions, 3DCityDB properties such as whether changelog tracking is enabled, and connection details.
`features`	Counts of all features in the database, broken down into active vs. terminated, top-level features, and counts by feature type.
`geometries`	Statistics about geometries, including total count, count of implicit geometries, distribution by geometry type, and counts by LoD.
`addresses`	Total number of addresses stored in the database.
`appearances`	Detailed information about all appearances, including total number of appearances, presence of global appearances, materials, textures, georeferenced textures, and appearance counts broken down by theme.
`extensions`	List of all ADE extensions registered in the database, including name, version, and description. An empty array is included if no extensions are available.
`codeLists`	References to external codelists that are registered for appropriate CityGML data types in the database. An empty object is included if no codelists are available.
`modules`	List of 3DCityDB module namespaces used by the data stored in the database. An empty object is included if no modules are used.

Feature scope¶

The --feature-scope option controls which features are considered when generating the report:

all: Includes all features in the 3DCityDB, both active and terminated. All counts and derived statistics reflect the complete database. This is the default mode.
active: Includes only active features when computing statistics and properties. Terminated features are ignored for derived statistics such as top-level features, available LoDs, and other feature-based properties. However, overall feature counts still show both active and terminated features.

For example, if a specific LoD exists only for terminated features, it will not be included in an export of active features or be usable for filtering them. Consequently, this LoD does not appear in reports with active scope. This makes the active scope ideal for concise reports focused on current features, while the all scope provides a complete overview of the database.

Note

Generating the report for only active features may take considerably more time.
For more information about terminating features, see the FEATURE table and the delete command.

Including generic attributes¶

The --include-generic-attributes option adds an additional genericAttributes section to the report. This section lists all generic attributes present in the database together with their data types as defined in the DATATYPE metadata table. Use this option when you need a complete overview of the generic attributes available in the database.

The example below shows an excerpt of the genericAttributes section.

{
  "metadata": {},
  "summary": {},
  ...
  "genericAttributes": {
    "ownerName": [
      "core:String"
    ],
    "roofHeight": [
      "core:Double"
    ],
    "energyPerformance": [ // (1)!
      "core:Integer",
      "core:String"
    ],
    ...
  }
}

In general, each generic attribute should be associated with a single data type. The presence of multiple data types usually indicates a consistency issue.

Note

Depending on the number and complexity of generic attributes, generating the report may take more time.

Including database size metrics¶

Enabling the --include-size-metrics option appends a size subsection to the database section of the report. This subsection contains size values in bytes for the entire database, the selected schema, and individual tables. An example is shown below.

{
  "metadata": {},
  "summary": {},
  ...
  "database":{
    "name":"3D City Database",
    "version":"5.1.0",
    ...
    "size":{
      "databaseSize":21454392467,
      "schemaSize":21436571648,
      "byTable":{
        "address":54951936,
        "appear_to_surface_data":2442379264,
        "appearance":283295744,
        "feature":3317882880,
        "geometry_data":2525831168,
        "implicit_geometry":32768,
        "property":6379757568,
        "surface_data":1938014208,
        "surface_data_mapping":3295518720,
        "tex_image":1198391296
      }
    }
  }
}

Tip

This option allows you to quickly evaluate the storage footprint of a 3DCityDB v5 instance and its tables, which can be helpful for performance analysis, monitoring growth, or planning backups.

Controlling the report process¶

The info command offers the following options to control the report generation process:

--threads: Sets the number of threads for parallel processing to improve performance. By default, four threads are used independent of the number of processors available to the JVM.

Note

Setting the number of threads too high can lead to performance issues due to thrashing. Additionally, each thread requires a separate database connection, so ensure your database can handle the required number of connections.