Getting started with CityJSON

Table of contents

  1. Download a simple file with 2 buildings
  2. Visualise it
  3. Manipulate and edit it with cjio
  4. What else?

Download a simple file with 2 buildings

Download twobuilding.json, a simple file with 2 buildings.

You can open that file in any text editor to see its structure, and notice that you can manually edit it to change values and/or add new buildings, new metadata, or delete some attributes.

Visualise it

Go to the CityJSON official online viewer and drop the file on the logo, and voilà:

You can also use more powerful viewers (where the semantics and attributes of the buildings are shown for instance), we offer a list of viewers and of other software. One of them is azul, a macOS-only viewer:

Manipulate and edit it with cjio

Manually editing a file is error-prone, so instead you can use cjio. It can be used to manipulate, edit, and validate CityJSON files.

You must have Python (version >3.5) installed, and pip.

cjio is a command-line interface program, which means that there is no graphical user interface and that you need to use the console (also called the “Command Prompt”, or the terminal).

To install the latest release:

pip install cjio

After the installation, you have a small program called cjio, to see its possibilities type cjio --help and it should print all the options, as shown here:

To get some general information about the file you downloaded, navigate to the folder where it is located, and type:

cjio twobuildings.json info

and you should get this output:

Parsing twobuildings.json
  "cityjson_version": "1.0",
  "epsg": null,
  "cityobjects_total": 2,
  "cityobjects_present": [
  "vertices_total": 255,
  "transform/compressed": false,
  "geom_primitives_present": [
  "materials": false,
  "textures": false

Observe that the "epsg" is null. To assign an EPSG to the file (26918 is the value, that dataset is part of the Montréal open 3D dataset), you can type:

cjio twobuildings.json assign_epsg 26918 save twobuildings_reprojected.json 

Notice that 2 cjio operators are used in one command: assign_epsg and save. The first one assigns the CRS to the file, and the second allows us to save the file on disk (in the current folder).

If you then type cjio twobuildings_reprojected.json info you should see that now an EPSG is assigned to 3D city model.

The cjio operators can be linked in a pipeline, and the 3D city model opened is passed through all the operators, and it gets modified by some operators. Operators like info and validate output information in the console and just pass the 3D city model to the next operator.

Some examples:

$ cjio example.json subset --id house12 info remove_materials info save out.json
$ cjio example.json remove_textures compress info
$ cjio example.json upgrade_version save new.json
$ cjio myfile.json merge '/home/elvis/temp/*.json' save all_merged.json

What else?

One important point is ensuring that the files you produce and manipulate are valid, see our validation tutorial to learn how to do this (for the schema and the geometric primitives).

Several datasets can be downloaded from the datasets page, but more importantly, it is possible to convert any CityGML file, see our tutorial.