This add-on was originally developed by Konstantinos Mastorakis (konmast3r) as part of their research orientation project for the MSc Geomatics programme of TU Delft. Its functionality was further developed for the needs of their MSc thesis An integrative workflow for 3D city model versioning
I plan to keep developing this add-on as a free-time project since I enjoy it a lot and because I see that there are many enthusiasts out there already using it in ways more serious than I expected. Although I am very excited to see that, I can't guarantee how much and how often
Up3date going to be further developed.
A Blender add-on to import, edit and export new instances of CityJSON-encoded 3D city models. All buildings' levels of detail (LoD), attributes and semantic surfaces are stored and can be accesed via Blender's graphical interface.
- Blender Version >=2.80
You can find sample datasets at the official CityJSON website. In case you have 3D city model datasets encoded in
CityGML you can use the free Conversion Tool to convert to and from
CityJSON and vice versa.
Trying to import really big datasets such as
New York will take several minutes because of the amount of information contained. With the rest sample
CityJSON files everything should work noticeably faster. Depending on your machine, it could take some seconds up to few minutes minute to import the 3D city model.
Download this repository as zip (through GitHub this can be done through the
Clone or download>
Blenderand go to
Edit > Preferences > Add-onsand press the
Select the downloaded ZIP and press
Install Add-on from File....
Enable the add-on from the list, by ticking the empty box next to the add-on's name.
(Optional: If you wish to update to a newer version, un-tick and tick again the add-on to reload it!)
Before you start!
For better understanding of the logic behind the add-on it is strongly recommended to have a quick (or thorough :-)) look on the CityJSON documentation if you are unfamiliar with it.
In case you run
Blenderthrough the console, useful feedback is given in it, informing about the progress of the import and export process. Upon importing and exporting from
Blenderit might prove quite useful since in the case of big files it can take up to several minutes. It will also print an error message in case of a crash, which is quite useful for debugging purposes.*
*Important: Make sure
Blender'sviewport is in
Object Modebefore importing and exporting a CityJSON file.
Importing a 3D city model
File > Import > CityJSON (.json) and navigate to the directory where the
CityJSON file is stored and open it.
The following options are available during file selection:
Surfaceswill create materials according to semantic surfaces (e.g. RoofSurface, WallSurface), if present, and load their attributes.
City Objectswill create materials per city object and according to the city object's type (e.g. Building, Road).
Reuse materials: Enable this if you want semantic surface materials to be reused when they share the same type. For example, all
RoofSurfacefaces will have the same materials. This only work when
Surfacesare selected as
*Important: Greatly improves speed of loading, but semantic surfaces' attributes can be lost, if present!
Clean scene: Enable this if you want the script to clean the scene of any existing object prior to importing the
After a successful import, you should be able to see the model somewhere close to the axis origin. Rotation of the scene and zooming in and out might help you, locating the model. In case you can't see the model, select an object from the
Outliner* (always in
Object Mode) and click
View > Frame Selectedor use the
homebutton of your keyboard right after importing and try zooming in.
*Important: Make sure the object you are selecting is a
mesh objectand not an
empty object. You can check that from the small pointing down triangle icon next to the object's name.
Collectionis created for each
LoDpresent in the 3D city model. In case more than 1 geometry exists for the objects -representing different
LODs(levels of detail)-, every geometry is stored under the appropriate
Collection, under the parent
CityObject. You can display different
Collectionsby clicking on the
eye iconin the
Outlinerat the top right of the interface (see screenshot below). By default all the
LOD_xcollections should be visible right after importing the 3D city model. In case you see any artefacts that is the reason! Choosing only one visible collection should remove all artifacts.
In case you want to visualize a certain area, click
Shift + Band draw a rectangle with your mouse to zoom into that specific area of the 3D city model. This also moves the rotation center at that point, which will come handy when you want to inspect specific areas of the model.
To see the attributes of each object, simply select the object on the screen and click on the
Object Propertiestab on the bottom right of
Blender'sinterface. Then click
Custom Propertiesdrop down menu (see screenshot below).
To see the semantics of each surface, select an object in
Object Mode, hit
Edit Modeand click
Face Select(top left of the viewport between the
Edit Modeand the
Viewbutton). Select a face of the object and click on the
Material Propertiestab at the bottom right. Scroll down and click on
Custom Properties(see screenshot below).
Blendertranslates the 3D city model at the beginning of the axis upon importing. The translation parameters and the
CRSare visible under the
World Propertiesfor transforming the coordinates back to original if needed.
Exporting a 3D city model
Up3date's exporting module was desinged and implemented in order to be able to export any scene of
Blender into a
**To do so and because there are certain differences between the two data models (Blender and CityJSON) some conventions were made to allow lossless exporting. **
In order to export objects from
Blender's scene the following steps need to be followed:
- For every
Mesh object* has to be added into
Blender'sscene. In case there are already created
Collectionsfrom a previously imported
CityJSONfile, it is not necessary to add the
LoD/geometryinto it, but recommended for organization purposes.
*Important: The mesh should be named in a predefined way for
Up3date to be able to parse it correctly. Example: a
LoD0 geometry should be named as
0: [LoD0] ID_of_object preserving also the spaces.
Mesh / geometry 2 more things needs to be added as
Custom Properties for the exporter to work. You need to add them yourself after selecting the
Mesh object in
Object Mode, clicking on the
Object Properties button (second screenshot of the documentation), expanding the
Custom Properties and clicking the
Add button to add a new
Custom Property. After addition, edit the property by hitting the
Edit button next to it. You only need to change
Property Name and
type: the_surface_type (
Empty objectrepresenting the
CityObjecthas to be created named as
ID_of_object(should be exactly the same name as the
Meshdescribed above without the
0: [LoD0]prefix). To rename any object just double-click on it in the
Outlinerand type a new name.
This object will be the
parentfor the various
LoDgeometries that a
CityObjectmight have. For any
CityObject's(aka building's) attribute you wish to store, a new
Custom Propertyhas to be added to the
Empty Object. You have to manually add them via
Blender'sgraphical interface exactly the same way as described in
In case the attributes have to be nested, for example the
postal codeof an
address, then the
Custom Propertykey should be
Up3datecan understand the nested attribute structure from the
.and handle it accordingly (see picture below).
- If the semantics of a (
LoD 2or above)
geometrysurfaces are known and you want to add them, they can be assigned (again) as
Materialsto the respective faces. For every
Mesh / Geometryobject
Blenderallows the creation of
Materials. To assign semantics that will be exported in the
CityJSONfile, you will need to first create (a) new material(s) inside the newly added
Mesh / Geometryobject (just select the object in
Object Modeand go to the
Materialstab). If working with a pre-imported file, you can select an already existing material. Don't worry if the materials' names look like
WallSurface.001etc. The only information exported is the value of the
typeof the material (i.e. the semantic).
In the case of creating new materials you need to add a
Custom Propertyto each one of them which must look like the following:
GroundSurfaceetc) (see also picture below).
After successfully adding the material(s) and the
Custom Property, select the geometry in
Object Mode, hit the
tabbutton to swap to
Edit Modeand click the
Face Selectbutton right next to the
Edit Modeoption (as explained under the 5th
Useful tipin the section above).
With the appropriate face selected select the appropriate material and hit the
Assignbutton to link that material to the face.
- Finally, go to
File > Export > CityJSON (.json)and export the new instance. Voila!
If you are using
Visual Studio Code, you may:
- Install Blender Development: a plugin that allows starting and debugging Python scripts from VSC.
- Install the fake-bpy-module to enable auto-completion:
pip install fake-bpy-module-2.80.
Clone this repository and have fun!
If you experience any bugs or have recommendations etc, you can open a new issue, providing all the necessary information. I can't promise to take them all under consideration but I always appreciate them.