From 38686fb1ea719fdad045e0619af7dbab70c2f01a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bal=C3=A1zs=20Dukai?= <balazs.dukai@gmail.com>
Date: Fri, 24 May 2024 13:22:30 +0200
Subject: [PATCH] Add modelling guide on material and texture themes

---
 dev/modelling-guide.md | 48 +++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/dev/modelling-guide.md b/dev/modelling-guide.md
index 673c469457..425b84f064 100644
--- a/dev/modelling-guide.md
+++ b/dev/modelling-guide.md
@@ -14,11 +14,57 @@ permalink: /dev/modelling-guide/
 
 ---
 
+## Themes of Materials and Textures
+
+The materials and textures of a Geometry are grouped into *themes*. In the example below, there are two material themes, `irradiation`, `irradiation-2`, and there are two texture themes, `winter-textures`, `summer-textures`.
+
+A *theme* does not refer to a single Material or Texture object, but it gives a name to a certain configuration of materials or textures within a specific geometry.
+In the example below, the material theme `irradiation` assigns the Materials with indices `0, 1` to the surfaces of the geometry.
+
+```json
+{
+  "type": "Solid",
+  "lod": "2.1",
+  "boundaries": [
+    [ [[0, 3, 2, 1]], [[4, 5, 6, 7]], [[0, 1, 5, 4]], [[1, 2, 6, 5]] ] 
+  ],
+  "material": {
+    "irradiation": { 
+      "values": [[0, 0, 1, null]] 
+    },
+    "irradiation-2": { 
+      "values": [[2, 2, 1, null]] 
+    }
+  },
+  "texture": {
+    "winter-textures": {
+      "values": [
+        [ [[0, 10, 23, 22, 21]], [[0, 1, 2, 6, 5]], [[null]], [[null]] ]                  
+      ]
+    },
+    "summer-textures": {
+      "values": [
+        [ 
+          [[1, 10, 23, 22, 21]], 
+          [[1, 1, 2, 6, 5]], 
+          [[1, 66, 12, 64, 5]], 
+          [[2, 99, 21, 16, 25]] 
+        ]                  
+      ]      
+    }
+  }
+}
+```
+
+There is no global list of all the available themes in CityJSON, they are defined per geometry.
+Following, the same theme for instance `irradiation`, can have a different configuration of materials (or textures) per geometry.
+Although, it is possible to define a default theme in the Appearance object, it is advised to handle the case when the default theme cannot be found in the geometry.
+
 ## Geometry objects and Semantic Surfaces
 
 Note that a single, empty surface is represented with a `[[]]`. In case the surface has one interior boundary then we have `[[],[]]`. However CityJSON does not allow `Surface` or `Polygon` as geometry type, only `MultiSurface`. Thus in case of a `MultiSurface` we have an array of surfaces, such as `[ [[0, 3, 2, 1]], [[4, 5, 6, 7]], [[0, 1, 5, 4]] ]`. 
 
-A Semantic Surface refers to a *single* surface (as its name implies). Also, holes, interior surfaces cannot have semantics, but they the semantic of info of the surface itself. Hence there are 5 indices in the `semantics.values` property below (one per surface), not 6.
+A Semantic Surface refers to a *single* surface (as its name implies). Also, holes, interior surfaces cannot have semantics, but they get the semantic of info of the surface itself. Hence there are 5 indices in the `semantics.values` property below (one per surface), not 6.
 
 ```json
 {