PaperlayerView exact revision on arXiv

Source-linked AI summary

CityJSON: a compact and easy-to-use encoding of the CityGML data model

Hugo Ledoux, Ken Arroyo Ohori, Kavisha Kumar, Balázs Dukai, Anna Labetski, Stelios Vitalis

arXiv:1902.09155v3cs.DB

TL;DR

CityGML’s XML-based exchange format is difficult to parse and manipulate because of its verbosity, hierarchy, and representational variation. The paper presents CityJSON, a simpler JSON encoding of the CityGML data model, and reports that real-world CityJSON files are about six times more compact while remaining easier for software development.

  • Problem

    CityGML’s XML/GML encoding is verbose, hierarchical, and complex, making parsing difficult and limiting practical software support and web-based processing.

  • Method

    The paper develops CityJSON, a JSON encoding that flattens CityGML structures, uses indexed shared vertices, and supports documented Extensions.

  • Results

    Real-world CityJSON files are on average 6× more compact than CityGML files, with compression factors varying between 4.4 and 8.1.

  • Takeaways & Limitations

    CityJSON reduces the complexity of developing applications for the CityGML data model by making files easier to parse, query, and manipulate in many programming languages.

  • Takeaways & Limitations

    CityJSON is conformant only to a subset of CityGML, and its Extensions are less flexible than CityGML ADEs.

Abstract

from arXiv · show

The international standard CityGML is both a data model and an exchange format to store digital 3D models of cities. While the data model is used by several cities, companies, and governments, in this paper we argue that its XML-based exchange format has several drawbacks. These drawbacks mean that it is difficult for developers to implement parsers for CityGML, and that practitioners have, as a consequence, to convert their data to other formats if they want to exchange them with others. We present CityJSON, a new JSON-based exchange format for the CityGML data model (version 2.0.0). CityJSON was designed with programmers in mind, so that software and APIs supporting it can be quickly built. It was also designed to be compact (a compression factor of around six with real-world datasets), and to be friendly for web and mobile development. We argue that it is considerably easier to use than the CityGML format, both for reading and for creating datasets. We discuss in this paper the main features of CityJSON, briefly present the different software packages to parse/view/edit/create files (including one to automatically convert between the JSON and GML encodings), analyse how real-world datasets compare to those of CityGML, and we also introduce \emph{Extensions}, which allow us to extend the core data model in a documented manner.

1 Introduction

CityGML provides a rich standardized model for 3D city objects, but its XML/GML encoding is difficult to use in practice. CityJSON addresses these usability concerns with a compact JSON encoding designed for developers and extensible through documented additions.

  • CityGML models common urban objects, their hierarchical relationships, and multiple levels of detail for different applications.
  • The standardized XML/GML encoding is verbose, hierarchical, complex, and poorly adapted to web use, limiting practical software and dataset support.
  • CityJSON encodes the CityGML 2.0.0 data model in JSON, using structures familiar to developers and widely supported across programming languages.
  • CityJSON is not an official OGC standard, and the paper reports no concrete plans for it to become one.
  • CityJSON removes deep hierarchies and standardizes feature representations, producing real-world files that are on average 6× more compact than CityGML files.
  • CityJSON supports documented Extensions that add new feature types and attributes for specific applications and datasets.

2 CityGML: a data model and an encoding

CityGML combines a hierarchical 3D city data model with XML and GML encodings. Although expressive, these encodings create substantial parsing complexity, representational variation, and file-management difficulties that weaken software support.

  • CityGML recursively decomposes cities into semantically related objects, supports five levels of detail, and permits application domain extensions through XML schemas.
  • XML-based CityGML files encode hierarchical objects, attributes, GML geometries, textures, and materials, producing deeply nested datasets.
  • CityGML files are difficult to parse because complexity arises across XML, GML, and CityGML-specific structures.
  • GML permits at least 25 variations for storing a simple square, requiring developers to handle many geometry configurations and causing inconsistent software behavior.
  • CityGML files are often massive, with 1GB+ files common, while semantic surfaces and implicit geometries introduce additional representational and reference-resolution burdens.
  • The resulting lack of full JavaScript parser support makes efficient web-based exchange and processing of CityGML models very difficult, if not impossible.

3 CityJSON

CityJSON implements most of the CityGML data model in a simpler JSON structure. Its design uses standard JSON data types, flattened city-object organization, direct identifier access, and consistent locations for geometry and attributes.

  • CityJSON maps all CityGML modules and implements most of the data model, omitting or simplifying parts that would add complexity or are rarely used.
  • JSON supplies simple data types plus arrays and dictionaries, which can be nested to represent CityJSON content.
  • CityJSON stores city objects in a dictionary named CityObjects, flattening the CityGML hierarchy while retaining parent and child links.
  • Identifier-based dictionaries give developers direct access to city objects, potentially in constant time when implemented with a hashmap.
  • A common city-object structure places geometries in geometry and attributes in attributes, simplifying access compared with CityGML.

3.2 Geometry

CityJSON preserves CityGML’s geometric primitives and restrictions while changing how geometry is indexed and stored. Vertices are centralized in a shared array, and surfaces and solids reference them through indexed rings and shells.

  • CityJSON uses the same 3D geometric primitives and linearity and planarity restrictions as CityGML.
  • Each geometry must specify a level of detail, and one city object may store several levels of detail concurrently.
  • CityJSON stores vertex coordinates in a separate vertices array, while geometric primitives reference vertex positions instead of repeating coordinates.
  • The format reuses Wavefront OBJ-style indexing, allowing shared vertices to reduce repetition and making more topological relationships explicit.
  • MultiSurfaces enumerate surfaces and their exterior or interior boundaries, while Solids enumerate exterior and interior shells composed of surfaces.

3.3 Semantic surfaces

CityJSON stores semantic surfaces separately from geometry so repeated semantic surfaces can be declared once and referenced by multiple geometric surfaces.

  • 3.3 Semantic surfaces: Semantic surfaces are stored as separate JSON objects from a city object’s geometry.This supports cases where several geometric surfaces share the same semantics.
  • 3.3 Semantic surfaces: A semantic surface can be declared once and reused by surfaces representing the same city object.The geometry can point to the separately stored semantic-surface object.
  • 3.3 Semantic surfaces: The example encodes roof, wall, and ground surfaces as distinct semantic types.The example also associates boundary values with semantic-surface indices.

3.4 Geometry templates

CityJSON represents reusable geometric templates at a central location and instantiates them through links and transformation matrices, reducing repeated geometry definitions.

  • 3.4 Geometry templates: Geometry templates are stored centrally so identical geometries can be reused with translations, rotations, and scaling.This is CityJSON’s implementation of CityGML implicit geometries.
  • 3.4 Geometry templates: A GeometryInstance specifies a location, a link to a geometry template, and a transformation matrix.A city object can use this type instead of directly embedding one of the other geometry types.
  • 3.4 Geometry templates: SolitaryVegetationObject is shown using a GeometryInstance with a transformationMatrix.The example identifies the instance type and provides matrix entries for its transformation.

3.5 Appearance

CityJSON supports CityGML-compatible materials and textures while centralising their storage, and uses JSON Schema plus extra validation functions to document and check files.

  • 3.5 Appearance: CityJSON supports both textures and materials using the same mechanisms as CityGML.Materials use X3D specifications, while textures reuse COLLADA specifications.
  • 3.5 Appearance: All materials and textures must be located at the same entry point in a CityJSON file.CityGML permits them to be located anywhere in the file.
  • 3.5 Appearance: JSON Schema documents CityJSON’s data model and validates allowed structure and syntax.Schemas define city objects, attributes, geometries, and other constraints.
  • 3.5 Appearance: The cjio software adds validation for properties and internal-consistency constraints that JSON Schema cannot express.These checks include object links, boundary and semantic-array coherence, duplicate IDs, vertices, and invalid vertex indices.

3.7 CityGML support

CityJSON maps CityGML modules into a simpler representation but supports only a subset of CityGML, with explicit restrictions on detail level, coordinate systems, identifiers, and coordinate storage.

  • 3.7 CityGML support: CityJSON represents the same information differently rather than providing a one-to-one mapping of CityGML classes and features.It implements most of the data model, but some modules and features are omitted or simplified.
  • 3.7 CityGML support: CityJSON is conformant to a subset of CityGML, whereas only XML-encoded CityGML files can technically conform to the CityGML specifications.This distinguishes practical data-model coverage from formal CityGML conformance.
  • 3.7 CityGML support: LoD4, which represents building interiors and their details, is not implemented.The stated reasons are an expected redesign in the next CityGML version and the scarcity of LoD4 datasets.
  • 3.7 CityGML support: CityJSON supports only EPSG-code coordinate reference systems, and all geometries in one object must use the same CRS.Arbitrary CRSs are not supported.
  • 3.7 CityGML support: Only city objects and semantic surfaces can have IDs in CityJSON.CityGML can also assign IDs to individual 3D primitives forming an object’s geometry.
  • 3.7 CityGML support: Integer vertex coordinates can be combined with stored scale and translation values to recover original coordinates and reduce file size.For the x component, the original coordinate is computed by scaling the integer vertex value and adding the translation.
  • 3.7 CityGML support: 5–10% compression is typical for this coordinate representation, which also reduces floating-point rounding risks.The paper identifies this as the preferred way to store CityJSON files.

3.9 Handling and streaming (large) CityJSON files

CityJSON’s shared vertex list complicates direct streaming of large files, so the paper proposes partitioning files into smaller parts and updating local indices.

  • Streaming limitations: Shared vertex references make large CityJSON files memory-intensive to reconstruct and complicate streaming.All vertices must be read to reconstruct geometries.
  • Streaming limitations: CityJSON cannot use vertex-lifetime tags because of its current file structure.The paper contrasts this with an approach that frees memory once vertices are no longer used.
  • Partitioning approach: Partitioning a CityJSON file into several files is proposed as an alternative, using spatial, object-type, or random partitioning rules.The vertex list and indices are updated for each partition.
  • Partitioning approach: Partitioning usually does not increase storage and may reduce size because repeated metadata is offset by smaller zero-based indices.The paper reports this as an empirical observation.
  • Metadata support: CityJSON incorporates metadata into its core schema, including support at city-model, module, and city-feature levels.The supplied passages identify this as a CityJSON addition to the CityGML data model.

4 Implementation and experiments

The paper demonstrates CityJSON through multiple software implementations and converted real-world datasets, finding substantial size reductions relative to CityGML.

  • Implementation: CityJSON has software for parsing, viewing, editing, creating, validating, converting, and processing files across several programming languages.The implementations include citygml4j, cjio, azul, 3dfier, a QGIS plugin, and val3dity.
  • Implementation: CityJSON’s flattened, dictionary-indexed structure provides direct access to city objects without an auxiliary indexing data structure.Building objects can refer directly to BuildingParts by identifier.
  • Experiments: The experiments converted openly available CityGML subsets automatically and covered textures, materials, geometry templates, and different levels of detail.The datasets were reconstructed using varied methodologies and software.
  • Experiments: Sixfold average compression was observed for CityGML files without whitespace versus integer-coordinate CityJSON files, with factors ranging from 4.4 to 8.1.The comparison uses CityGML without spaces or carriage returns and CityJSON with integer coordinates.
  • Experiments: Compression reflects merged vertices, less verbose generic attributes, dataset complexity, and loss of polygon gml:id values during translation.The paper notes that polygon identifiers are believed to have little practical meaning.
  • Experiments: Texture and material presence does not appear to affect compression because texture files are excluded and both formats reference them similarly.The paper reports similar results on several additional datasets.

5 Extensions to the core data model

CityJSON Extensions document controlled additions to the core data model while preserving compatibility with standard CityJSON processing, trading away some flexibility compared with ADEs.

  • Motivation: CityGML ADEs extend the model through additional XML schemas, inheritance, new classes, and new attributes.Practitioners use ADEs to represent additional objects or attributes.
  • Extension model: CityJSON Extensions are JSON files that document and validate additions to the core model through three restricted extension cases.The cases add complex attributes, create or extend city objects with complex geometries, or add root properties.
  • Trade-offs: Extensions are less flexible than ADEs because inheritance, namespaces, and some customization are unsupported, but ADE software support is likely inconsistent.The paper connects ADE flexibility with uncertainty about structures and handling in processing software.
  • Extension model: Extensions must define a name, URI, version, and JSON-schema snippets that can reuse CityJSON definitions and geometric primitives.The extension file is linked to CityJSON definitions by preprocessing software such as cjio.
  • Compatibility rules: Extension rules require new city objects to use a plus-prefixed name, contain type and geometry properties, and keep geometries inside geometry.These constraints allow standard software to process extended files without modification in many cases.
  • Examples: Extensions can add new attributes to existing objects, including simple strings and complex measurements with values and units.The paper illustrates this with noise-related attributes on Building objects.

6 Conclusions

CityJSON applies a developer-centred JSON encoding to reduce the complexity of working with the CityGML data model. Its compactness, lossless conversion with GML, and open development are presented as practical benefits, while future work targets larger files and evolving CityGML specifications.

  • Developer-centred design: CityJSON reduces application-development complexity by using a simpler JSON encoding for the CityGML data model.The authors contrast native JSON parsing with the more complex, error-prone task of building CityGML parsers on generic XML libraries.
  • Developer-centred design: CityJSON specifications were iteratively tested through implementations in software packages using different programming languages.This process informed improvements and helped avoid escalating complexity in the standard.
  • Practical exchange: CityJSON preserves the CityGML data model as an additional encoding, with a few deliberately omitted and documented features.Open-source software can convert between CityJSON and GML without loss of information, allowing tasks to use either encoding.
  • Practical exchange: 6× smaller files in practice make CityJSON beneficial for web contexts, while also supporting dataset exchange, creation, and editing.The authors describe the encoding as more flexible for practitioners and especially useful where compact files matter.
  • Community impact: The authors expect CityJSON and its open GitHub development to foster open-source tools and make dataset exchange and processing easier.They specifically identify small programmers and researchers as potential contributors to the tool ecosystem.
  • Future work: Future work includes tiling large files, adding a binary BSON-based encoding, and adapting CityJSON to CityGML v3 while retaining simplicity and usability.The planned tiling scheme may use a quadtree, and the binary encoding is intended to compress files further.
Loading 1902.09155v3…