CityGML v3.0 implementation details

Table of contents

  1. Overview CityGML modules
  2. Generics module
    1. Adding new attributes
    2. Extensions to extend the data model
  3. Specific CityGML v3.0 features not supported
  4. Extra features in CityJSON but not in CityGML

CityJSON v2.0 partially implements the CityGML data model v3.0 and includes a JSON-specific extension mechanism (akin to CityGML ADEs).

The CityGML conceptual model is thematically decomposed into one Core module and 16 extension modules. Below we list each of the modules and describe what is supported and what not.

Overview CityGML modules

100% supported
partially supported (often missing features are for the sake of an efficient implementation)
module not supported at all
CityGML module compliant? extra info
Core all geometries can be represented, Implicit Geometries are supported (called Geometry Templates). Only the ExternalReferences are not supported.
Appearance the CityGML class TexCoordGen is not supported, ie one must specify the UV coordinates in the texture files.
CityObjectGroup groups of City Objects are supported, but not groups of parts of objects (eg it is not possible to group some walls of a building together)
Generics everything supported, but implemention differs, see details below
PointCloud this Extension can be used
Relief only the TINRelief/TriangulatedSurface is supported. Tin (where only elevation points and break lines are stored) is not supported since it would require viewer/applications to have a constrained Delaunay triangulator, which is problematic (especially for web-based tools). Also, it is not possible to store areas over a terrain that would support different resolutions. RasterRelief is also not supported.
Versioning instead, CityJSON aims at offering a Git-based alternative, see our work-in-progress

Generics module

The generics module is for:

  1. adding generic attributes that are not prescribed by the CityGML data model
  2. representing city objects that are not described in the CityGML data model

CityJSON implements these but the handling differs from CityGML slightly.

Adding new attributes

One of the philosophy of JSON is being”schema-less”, which means that one is allowed to define new properties for the JSON objects without documenting them in a JSON schema. While this is in contrast to CityGML (and GML as a whole) where the schemas are central, the schemas of CityJSON are partly following that philosophy. That is, for a given City Object, the “allowed” properties/attributes are listed in the schema, but it is not an error to add new ones. The “official validator” of CityJSON (cjval) does more than simply validate a dataset against the schemas, and will return a warning if an attribute is not in the schema, but it is not considered as invalid in CityJSON.

Extensions to extend the data model

To add new city objects, CityGML has the ADE mecanism (Application Domain Extensions). CityJSON has a similar concept, called Extensions. Extensions do not follow the same rules and thus cannot be considered as a direct JSON translation of ADEs. They are deliberately simpler than ADEs, with the aim of being easy to use in practice (ADEs are generally not very user-friendly).

Extensions allows us to: (1) add new complex attributes to existing City Objects; (2) add new properties at the root of a document; (3) create a new City Object, or “extending” one, and defining complex geometries; (4) create new Semantic Surfaces.

Specific CityGML v3.0 features not supported

  1. Several CRSs in the same datasets. In CityJSON, all geometries in a given CityJSON object must use the same CRS. In CityGML, 3 adjacent buildings can all have different CRSs, and some of the geometries to represent the walls can be in yet another CRS (although admittedly it is seldom used!).
  2. Identifiers for low-level geometries. In CityGML most objects can have an ID (usually a gml:id if the XML encoding is used). That is, not only can one building have an ID, but also each of the 3D primitives forming its geometry can have an ID. In CityJSON, only city objects and semantic surfaces can have IDs.
  3. topological relationships, eg relativeToTerrain and relativeToWater, which qualify relationships, are not supported. XLinks to identify that some surfaces are shared between 2 objects is also not supported, however the fact that more topology is explicitly stored compensates somehow.
  4. Terrain Intersection Curve (TIC). This feature of CityGML is seldom used in practice it seems, and can always be simply computed on-the-fly: intersection between the solid of the buildings (or other objects) and the terrain. Furthermore, it is dependent on the LoD of the object (different LoDs can have different footprints)
  5. Complex attributes have been simplified. For instance, several attributes in CityGML are derived from gml:Measure (like bldg:measuredHeight), and thus you cannot just store a value but also have to store the unit of measurement. This is not represented in CityJSON directly, an Extension must be used. Also, generic attributes in CityGML cannot be mapped simply because in CityJSON you can add any attributes you like (inline with the JSON philosophy).

Extra features in CityJSON but not in CityGML

  1. CityJSON supports the so-called “TU Delft LoDs”, which refine and improve the 5 LoDs in CityGML (only for buildings).
  2. CityJSON addresses the issue of very large files, and how to stream them.
  3. CityJSON offers the possibility to store metadata, 6 ISO19115 properties are supported, and with the Metadata Extension more can be stored.